All Infra Resources
This reference describes each of the resources available to Chef Infra Client, including a list of actions, properties, and usage examples.
Common Functionality
The properties and actions in this section apply to all resources.
Actions
The following actions may be used with any resource:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Examples
The following examples show how to use common actions in a recipe.
Use the :nothing action
service 'memcached' do
action :nothing
end
Properties
The following properties are common to every resource:
ignore_failure
- Ruby Type: true, false | Default Value:
false
Continue running a recipe if a resource fails for any reason.
retries
- Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
- Ruby Type: Integer | Default Value:
2
The retry delay (in seconds).
sensitive
- Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Examples
The following examples show how to use common properties in a recipe.
Use the ignore_failure common property
gem_package 'syntax' do
action :install
ignore_failure true
end
Use the retries and retry_delay common properties
service 'apache' do
action [ :enable, :start ]
retries 3
retry_delay 5
end
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
Properties
The following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Arguments
The following arguments can be used with the not_if
or only_if
guard
properties:
:user
Specify the user that a command will run as. For example:
not_if 'grep adam /etc/passwd', user: 'adam'
:group
Specify the group that a command will run as. For example:
not_if 'grep adam /etc/passwd', group: 'adam'
:environment
Specify a Hash of environment variables to be set. For example:
not_if 'grep adam /etc/passwd', environment: { 'HOME' => '/home/adam', }
:cwd
Set the current working directory before running a command. For example:
not_if 'grep adam passwd', cwd: '/etc'
:timeout
Set a timeout for a command. For example:
not_if 'sleep 10000', timeout: 10
not_if Examples
The following examples show how to use not_if
as a condition in a recipe:
Create a file, but not if an attribute has a specific value
The following example shows how to use the not_if
condition to create
a file based on a template and using the presence of an attribute value
on the node to specify the condition:
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
not_if { node['some_value'] }
end
Create a file with a Ruby block, but not if “/etc/passwd” exists
The following example shows how to use the not_if
condition to create
a file based on a template and then Ruby code to specify the condition:
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
not_if do
::File.exist?('/etc/passwd')
end
end
Create a file with Ruby block that has curly braces, but not if “/etc/passwd” exists
The following example shows how to use the not_if
condition to create
a file based on a template and using a Ruby block (with curly braces) to
specify the condition:
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
not_if { ::File.exist?('/etc/passwd') }
end
Create a file using a string, but not if “/etc/passwd” exists
The following example shows how to use the not_if
condition to create
a file based on a template and using a string to specify the condition:
template '/etc/some_config' do
mode '0640'
source 'some_config.erb'
not_if 'some_app --check-config'
end
only_if Examples
The following examples show how to use only_if
as a condition in a recipe:
Create a file, but only if an attribute has a specific value
The following example shows how to use the only_if
condition to create
a file based on a template and using the presence of an attribute on the
node to specify the condition:
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
only_if { node['some_value'] }
end
Create a file with a Ruby block, but only if “/etc/passwd” does not exist
The following example shows how to use the only_if
condition to create
a file based on a template, and then use Ruby to specify a condition:
template '/etc/some_app/some_config' do
mode '0640'
source 'some_config.erb'
only_if { ::File.exist?('/etc/some_app/') }
end
Create a file using a string, but only if “/etc/passwd” exists
The following example shows how to use the only_if
condition to create
a file based on a template and using a string to specify the condition:
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
only_if 'test -f /etc/passwd'
end
Guard Interpreters
Any resource that passes a string command may also specify the interpreter that will be used to evaluate that string command. This is done by using theguard_interpreter
property to specify a
script-based resource.Attributes
The guard_interpreter
property may be set to any of the following
values:
:bash
Evaluates a string command using the bash resource.
:batch
Evaluates a string command using the batch resource. Default value (within a batch resource block):
:batch
.:csh
Evaluates a string command using the csh resource.
:default
Default. Executes the default interpreter as identified by Chef Infra Client.
:perl
Evaluates a string command using the perl resource.
:powershell_script
Evaluates a string command using the powershell_script resource. Default value (within a powershell_script resource block):
:powershell_script
.:python
Evaluates a string command using the python resource.
:ruby
Evaluates a string command using the ruby resource.
Inheritance
The guard_interpreter
property is set to :default
by default for the
bash, csh, perl, python, and ruby resources. When
the guard_interpreter
property is set to :default
, not_if
or
only_if
guard statements do not inherit properties that are
defined by the script-based resource.
Warning
The batch and powershell_script resources inherit properties by
default. The guard_interpreter
property is set to :batch
or
:powershell_script
automatically when using a not_if
or only_if
guard statement within a batch or powershell_script resource,
respectively.
bash 'javatooling' do
environment 'JAVA_HOME' => '/usr/lib/java/jdk1.7/home'
code 'java-based-daemon-ctl.sh -start'
not_if 'java-based-daemon-ctl.sh -test-started'
end
and requires adding the environment
property to the not_if
guard
statement so that it may use the JAVA_HOME
path as part of its
evaluation:
bash 'javatooling' do
environment 'JAVA_HOME' => '/usr/lib/java/jdk1.7/home'
code 'java-based-daemon-ctl.sh -start'
not_if 'java-based-daemon-ctl.sh -test-started', :environment => 'JAVA_HOME' => '/usr/lib/java/jdk1.7/home'
end
To inherit properties, add the guard_interpreter
property to the
resource block and set it to the appropriate value:
:bash
for bash:csh
for csh:perl
for perl:python
for python:ruby
for ruby
For example, using the same example as from above, but this time adding
the guard_interpreter
property and setting it to :bash
:
bash 'javatooling' do
guard_interpreter :bash
environment 'JAVA_HOME' => '/usr/lib/java/jdk1.7/home'
code 'java-based-daemon-ctl.sh -start'
not_if 'java-based-daemon-ctl.sh -test-started'
end
The not_if
statement now inherits the environment
property and will
use the JAVA_HOME
path as part of its evaluation.
Examples
For example, the following code block will ensure the command is evaluated using the default interpreter as identified by Chef Infra Client:
resource 'name' do
guard_interpreter :default
# code
end
Lazy Evaluation
In some cases, the value for a property cannot be known until the execution phase of a Chef Infra Client run. In this situation, using lazy evaluation of property values can be helpful. Instead of a property being assigned a value, it may instead be assigned a code block. The syntax for using lazy evaluation is as follows:
property_name lazy { code_block }
where lazy
is used to tell Chef Infra Client to evaluate the contents
of the code block later on in the resource evaluation process (instead
of immediately) and { code_block }
is arbitrary Ruby code that
provides the value.
For example, a resource that is not doing lazy evaluation:
template 'template_name' do
# some properties
path '/foo/bar'
end
and a resource block that is doing lazy evaluation:
template 'template_name' do
# some properties
path lazy { ' some Ruby code ' }
end
In the previous examples, the first resource uses the value /foo/bar
and the second resource uses the value provided by the code block, as
long as the contents of that code block are a valid resource property.
The following example shows how to use lazy evaluation with template variables:
template '/tmp/canvey_island.txt' do
source 'canvey_island.txt.erb'
variables(
lazy do
{ canvey_island: node.run_state['sea_power'] }
end
)
end
Notifications
A notification is a property on a resource that listens to other resources in the resource collection and then takes actions based on the notification type (notifies
or subscribes
).Timers
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
Notifies
A resource may notify another resource to take action when its state
changes. Specify a 'resource[name]'
, the :action
that resource
should take, and then the :timer
for that action. A resource may
notify more than one resource; use a notifies
statement for each
resource to be notified.
If the referenced resource does not exist, an error is raised.
In contrast, subscribes
will not fail if the source
resource is not found.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
Examples
The following examples show how to use the notifies
notification in a recipe.
Delay notifications
template '/etc/nagios3/configures-nagios.conf' do
# other parameters
notifies :run, 'execute[test-nagios-config]', :delayed
end
Notify immediately
By default, notifications are :delayed
, that is they are queued up as
they are triggered, and then executed at the end of a Chef Infra
Client run. To run an action immediately, use :immediately
:
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:
execute 'test-nagios-config' do
command 'nagios3 --verify-config'
action :nothing
end
Notify multiple resources
template '/etc/chef/server.rb' do
source 'server.rb.erb'
owner 'root'
group 'root'
mode '0755'
notifies :restart, 'service[chef-elasticsearch]', :delayed
notifies :restart, 'service[chef-server]', :delayed
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:
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'
.
Reload a service
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
notifies :reload, 'service[apache]', :immediately
end
Restart a service when a template is modified
template '/etc/www/configures-apache.conf' do
notifies :restart, 'service[apache]', :immediately
end
Send notifications to multiple resources
To send notifications to multiple resources, just use multiple attributes. Multiple attributes will get sent to the notified resources in the order specified.
template '/etc/netatalk/netatalk.conf' do
notifies :restart, 'service[afpd]', :immediately
notifies :restart, 'service[cnid]', :immediately
end
service 'afpd'
service 'cnid'
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:
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.
Restart a service, and then notify a different service
The following example shows how start a service named example_service
and immediately notify the Nginx service to restart.
service 'example_service' do
action :start
notifies :restart, 'service[nginx]', :immediately
end
Restart one service before restarting another
This example uses the :before
notification to restart the php-fpm
service before restarting nginx
:
service 'nginx' do
action :restart
notifies :restart, 'service[php-fpm]', :before
end
With the :before
notification, the action specified for the nginx
resource will not run until action has been taken on the notified
resource (php-fpm
).
Notify when a remote source changes
remote_file '/tmp/couch.png' do
source 'http://couchdb.apache.org/img/sketch.png'
action :nothing
end
http_request 'HEAD http://couchdb.apache.org/img/sketch.png' do
message ''
url 'http://couchdb.apache.org/img/sketch.png'
action :head
if ::File.exist?('/tmp/couch.png')
headers 'If-Modified-Since' => File.mtime('/tmp/couch.png').httpdate
end
notifies :create, 'remote_file[/tmp/couch.png]', :immediately
end
Subscribes
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Examples
The following examples show how to use the subscribes
notification in a recipe.
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:
execute 'test-nagios-config' do
command 'nagios3 --verify-config'
action :nothing
subscribes :run, 'template[/etc/nagios3/configures-nagios.conf]', :immediately
end
Reload a service using a template
To reload a service that is based on a template, use the template and service resources together in the same recipe, similar to the following:
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
end
service 'apache' do
action :enable
subscribes :reload, 'template[/tmp/somefile]', :immediately
end
where the subscribes
notification is used to reload the service
whenever the template is modified.
Stash a file in a data bag
The following example shows how to use the ruby_block resource to stash a BitTorrent file in a data bag so that it can be distributed to nodes in the organization.
# the following code sample comes from the ``seed`` recipe
# in the following cookbook: https://github.com/mattray/bittorrent-cookbook
ruby_block 'share the torrent file' do
block do
f = File.open(node['bittorrent']['torrent'], 'rb')
#read the .torrent file and base64 encode it
enc = Base64.encode64(f.read)
data = {
'id' => bittorrent_item_id(node['bittorrent']['file']),
'seed' => node['ipaddress'],
'torrent' => enc,
}
item = Chef::DataBagItem.new
item.data_bag('bittorrent')
item.raw_data = data
item.save
end
action :nothing
subscribes :create, "bittorrent_torrent[#{node['bittorrent']['torrent']}]", :immediately
end
Relative Paths
The following relative paths can be used with any resource:
#{ENV['HOME']}
Use to return the
~
path in Linux and macOS or the%HOMEPATH%
in Windows.
Examples
template "#{ENV['HOME']}/chef-getting-started.txt" do
source 'chef-getting-started.txt.erb'
mode '0755'
end
Run in Compile Phase
Chef Infra Client processes recipes in two phases:
- First, each resource in the node object is identified and a resource collection is built. All recipes are loaded in a specific order, and then the actions specified within each of them are identified. This is also referred to as the “compile phase”.
- Next, Chef Infra Client configures the system based on the order of the resources in the resource collection. Each resource then examines the node and performs the necessary steps to complete the action. This is also referred to as the “execution phase”.
Typically, actions are processed during the execution phase of a Chef Infra Client run. However, sometimes it is necessary to run an action during the compile phase. For example, a resource can be configured to install a package during the compile phase to ensure that application is available to other resources during the execution phase.
Note
Use the chef_gem resource to install gems that are needed by Chef Infra Client during the execution phase.
run_action
Use .run_action(:some_action)
at the end of a resource block to run
the specified action during the compile phase. For example:
build_essential 'Install compilers' do
action :nothing
end.run_action(:install)
where action
is set to :nothing
to ensure the run_action
is run
during the compile phase and not later during the execution phase.
This can be simplified by using the compile_time
flag in Chef Infra
Client 16 and later versions:
build_essential 'Install compilers' do
compile_time true
end
That flag both forces the resource to run at compile time and sets the
converge action to :nothing
.
The following examples show when (and when not) to use run_action
.
Using Custom Resources preferred to forcing to compile time
Compile time execution is often used to install gems before requiring them in recipe code.
This is a poor pattern since gems may depend on native gems which may require installing compilers at compile time.
build_essential 'Install compilers' do
compile_time true
end
chef_gem 'aws-dsk' do
compile_time true
end
require 'aws-sdk'
A better strategy is to move the code, which requires the gem, into a custom resource. Since all the actions of custom resources run at converge time, this defers requiring the gem until later in the overall Chef Infra Client execution. Unified mode can also be used in the resource to eliminate compile/converge mode issues entirely:
unified_mode true
action :run do
build_essential 'Install compilers'
chef_gem 'aws-sdk'
require 'aws-sdk'
end
Download and parse a configuration file
A common use case is to download a configuration file, parse it, and then use the values in templates and to control other configuration.
An important distinction to make is that the downloaded configuration file only exists in a temporary state to be used by the Chef Infra Client. It will not be used directly by the system or applications that are managed by the Chef Infra Client.
To download and parse a JSON file and render it in a template, it makes sense to download the file during compile time:
# the remote_file is being downloaded to a temporary file
remote_file "#{Chef::Config[:file_cache_path]}/users.json" do
source "https://jsonplaceholder.typicode.com/users"
compile_time true
end
# this parsing needs to happen after the remote_file is downloaded, but will
# be executed at compile time.
array = JSON.parse(IO.read("#{Chef::Config[:file_cache_path]}/users.json")
# the `array.last["phone"]` expression here will also be evaluated at compile
# time and must be lazied using wrapping the expresssion in `lazy {}`
file "/tmp/phone_number.txt" do
content array.last["phone"]
end
This is considerably cleaner than the alternative of lazy evaluating both the parsing of the
JSON and the rendering of the data into the file template, which will happen if
the remote_file
resource is not run at compile time:
# the execution of this is now deferred
remote_file "#{Chef::Config[:file_cache_path]}/users.json" do
source "https://jsonplaceholder.typicode.com/users"
end
# it is necessary due to lexical scoping issues to create this variable here
array = nil
# the parsing of the JSON is now deferred due to the ruby_block
ruby_block "parse JSON" do
block do
array = JSON.parse(IO.read("#{Chef::Config[:file_cache_path]}/users.json")
end
end
# the argument to the content property must now also be deferred
file "/tmp/phone_number.txt" do
content lazy { array.last["phone"] }
end
This is an example of code that overuses deferred execution, uses more “lazy” evaluation, and is considerably harder to understand and write correctly.
Notifications will not work
Resources that are executed during the compile phase cannot notify other resources. For example:
execute 'ifconfig'
package 'vim-enhanced' do
compile_time true
notifies :run, 'execute[ifconfig]', :immediately
end
A better approach in this type of situation is to install the package before the resource collection is built to ensure that it is available to other resources later on.
The best approach to this problem is to use unified mode
, which eliminates
the compile time and converge time distinction while allowing notifications
to work correctly.
Resources that are forced to compile time by default
The ohai_hint
and hostname
resources run at compile time by default.
This is due to the fact that later resources may consume the node attributes which
are set by those resources leading to excessive use of lazy
in subsequent
resources (and similar issues to the remote_file
example above).
The chef_gem
resource used to execute at compile time by default, but now we
recommend that users move code that executes at compile time to custom resources.
Atomic File Updates
Atomic updates are used with file-based resources to help ensure that file updates can be made when updating a binary or if disk space runs out.
Atomic updates are enabled by default. They can be managed globally
using the file_atomic_update
setting in the client.rb
file. They can
be managed for each resource using the atomic_update
property
that is available with the cookbook_file, file,
remote_file, and template resources.
Note
On certain platforms, and after a file has been moved into place, Chef
Infra Client may modify file permissions to support features specific to
those platforms. On platforms with SELinux enabled, Chef Infra Client
will fix up the security contexts after a file has been moved into the
correct location by running the restorecon
command. On the Microsoft
Windows platform, Chef Infra Client will create files so that ACL
inheritance works as expected.
Windows File Security
To support Windows security, the template, file, remote_file, cookbook_file, directory, and remote_directory resources support the use of inheritance and access control lists (ACLs) within recipes.Access Control Lists (ACLs)
The rights
property can be used in a recipe to manage access control
lists (ACLs), which allow permissions to be given to multiple users and
groups. Use the rights
property can be used as many times as
necessary; Chef Infra Client will apply them to the file or directory as
required. The syntax for the rights
property is as follows:
rights permission, principal, option_type => value
where
permission
Use to specify which rights are granted to the
principal
. The possible values are::read
,:write
,read_execute
,:modify
,:full_control
, or an integer.Integers used for permissions must match the following list FileSystemRights Enum fields.
These permissions are cumulative. If
:write
is specified, then it includes:read
. If:full_control
is specified, then it includes both:write
and:read
.(For those who know the Windows API:
:read
corresponds toGENERIC_READ
;:write
corresponds toGENERIC_WRITE
;:read_execute
corresponds toGENERIC_READ
andGENERIC_EXECUTE
;:modify
corresponds toGENERIC_WRITE
,GENERIC_READ
,GENERIC_EXECUTE
, andDELETE
;:full_control
corresponds toGENERIC_ALL
, which allows a user to change the owner and other metadata about a file.)principal
Use to specify a group or user. The principal can be specified by either name or SID. When using name, this is identical to what is entered in the login box for Windows, such as
user_name
,domain\user_name
, oruser_name@fully_qualified_domain_name
. When using a SID, you may use either the standard string representation of a SID (S-R-I-S-S) or one of the SDDL string constants. Chef Infra Client does not need to know if a principal is a user or a group.option_type
A hash that contains advanced rights options. For example, the rights to a directory that only applies to the first level of children might look something like:
rights :write, 'domain\group_name', :one_level_deep => true
.Possible option types:
:applies_to_children
Specify how permissions are applied to children. Possible values:
true
to inherit both child directories and files;false
to not inherit any child directories or files;:containers_only
to inherit only child directories (and not files);:objects_only
to recursively inherit files (and not child directories).:applies_to_self
Indicates whether a permission is applied to the parent directory. Possible values:
true
to apply to the parent directory or file and its children;false
to not apply only to child directories and files.:one_level_deep
Indicates the depth to which permissions will be applied. Possible values:
true
to apply only to the first level of children;false
to apply to all children.
For example:
resource 'x.txt' do
rights :read, 'S-1-1-0'
rights :write, 'domain\group'
rights :full_control, 'group_name_or_user_name'
rights :full_control, 'user_name', applies_to_children: true
end
or:
rights :read, %w(Administrators Everyone)
rights :full_control, 'Users', applies_to_children: true
rights :write, 'Sally', applies_to_children: :containers_only, applies_to_self: false, one_level_deep: true
Some other important things to know when using the rights
attribute:
- Only inherited rights remain. All existing explicit rights on the object are removed and replaced.
- If rights are not specified, nothing will be changed. Chef Infra Client does not clear out the rights on a file or directory if rights are not specified.
- Changing inherited rights can be expensive. Windows will propagate rights to all children recursively due to inheritance. This is a normal aspect of Windows, so consider the frequency with which this type of action is necessary and take steps to control this type of action if performance is the primary consideration.
Use the deny_rights
property to deny specific rights to specific
users. The ordering is independent of using the rights
property. For
example, it doesn’t matter if rights are granted to everyone is placed
before or after deny_rights :read, ['Julian', 'Lewis']
, both Julian
and Lewis will be unable to read the document. For example:
resource 'x.txt' do
rights :read, 'Everyone'
rights :write, 'domain\group'
rights :full_control, 'group_name_or_user_name'
rights :full_control, 'user_name', applies_to_children: true
deny_rights :read, %w(Julian Lewis)
end
or:
deny_rights :full_control, ['Sally']
Inheritance
By default, a file or directory inherits rights from its parent
directory. Most of the time this is the preferred behavior, but
sometimes it may be necessary to take steps to more specifically control
rights. The inherits
property can be used to specifically tell Chef
Infra Client to apply (or not apply) inherited rights from its parent
directory.
For example, the following example specifies the rights for a directory:
directory 'C:\mordor' do
rights :read, 'MORDOR\Minions'
rights :full_control, 'MORDOR\Sauron'
end
and then the following example specifies how to use inheritance to deny access to the child directory:
directory 'C:\mordor\mount_doom' do
rights :full_control, 'MORDOR\Sauron'
inherits false # Sauron is the only person who should have any sort of access
end
If the deny_rights
permission were to be used instead, something could
slip through unless all users and groups were denied.
Another example also shows how to specify rights for a directory:
directory 'C:\mordor' do
rights :read, 'MORDOR\Minions'
rights :full_control, 'MORDOR\Sauron'
rights :write, 'SHIRE\Frodo' # Who put that there I didn't put that there
end
but then not use the inherits
property to deny those rights on a child
directory:
directory 'C:\mordor\mount_doom' do
deny_rights :read, 'MORDOR\Minions' # Oops, not specific enough
end
Because the inherits
property is not specified, Chef Infra Client will
default it to true
, which will ensure that security settings for
existing files remain unchanged.
Resources
The following resources are built into the Chef Infra Client:
alternatives resource
alternatives resource pageUse the alternatives resource to configure command alternatives in Linux using the alternatives or update-alternatives packages.
New in Chef Infra Client 16.0.
Syntax
The full syntax for all of the properties that are available to the alternatives resource is:
alternatives 'name' do
link String # default value: "/usr/bin/LINK_NAME"
link_name String # default value: 'name' unless specified
path String
priority String, Integer
action Symbol # defaults to :install if not specified
end
where:
alternatives
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.link
,link_name
,path
, andpriority
are the properties available to this resource.
Actions
The alternatives resource has the following actions:
:auto
- Set an alternative up in automatic mode with the highest priority automatically selected.
:install
- Install an alternative on the system including symlinks. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:refresh
- Refresh alternatives.
:remove
- Remove an alternative and all associated links.
:set
- Set the symlink for an alternative.
Properties
The alternatives resource has the following properties:
link
- Ruby Type: String | Default Value:
/usr/bin/LINK_NAME
The path to the alternatives link.
link_name
- Ruby Type: String | Default Value:
The resource block's name
The name of the link to create. This will be the command you type on the command line such as
ruby
orgcc
.
path
- Ruby Type: String
The absolute path to the original application binary such as
/usr/bin/ruby27
.
priority
- Ruby Type: String, Integer
The priority of the alternative.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the alternatives resource in recipes:
Install an alternative:
alternatives 'python install 2' do
link_name 'python'
path '/usr/bin/python2.7'
priority 100
action :install
end
Set an alternative:
alternatives 'python set version 3' do
link_name 'python'
path '/usr/bin/python3'
action :set
end
Set the automatic alternative state:
alternatives 'python auto' do
link_name 'python'
action :auto
end
Refresh an alternative:
alternatives 'python refresh' do
link_name 'python'
action :refresh
end
Remove an alternative:
alternatives 'python remove' do
link_name 'python'
path '/usr/bin/python3'
action :remove
end
apt_package resource
apt_package resource pageUse the apt_package resource to manage packages on Debian, Ubuntu, and other platforms that use the APT package system.
Note
Syntax
An apt_package resource block manages a package on a node, typically by installing it. The simplest use of the apt_package resource is:
apt_package 'package_name'
which will install the named package using all of the default options and the default action of :install
.
The full syntax for all of the properties that are available to the apt_package resource is:
apt_package 'name' do
anchor_package_regex true, false # default value: false
default_release String
options String, Array
overwrite_config_files true, false # default value: false
package_name String, Array
response_file String
response_file_variables Hash # default value: {}
source String
timeout String, Integer
version String, Array
action Symbol # defaults to :install if not specified
end
where:
apt_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.anchor_package_regex
,default_release
,options
,overwrite_config_files
,package_name
,response_file
,response_file_variables
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The apt_package resource has the following actions:
:install
- Install a package. If a version is specified, install the specified version of the package. (default)
:lock
- Locks the apt package to a specific version.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:purge
- Purge a package. This action typically removes the configuration files as well as the package.
:reconfig
- Change the installed package.
:remove
- Remove a package.
:unlock
- Unlocks the apt package so that it can be upgraded to a newer version.
:upgrade
- Install a package and ensure that a package is the latest version.
Properties
The apt_package resource has the following properties:
anchor_package_regex
- Ruby Type: true, false | Default Value:
false
A Boolean flag that allows (
false
) or prevents (true
) apt_package from matching the named package with packages by regular expression if it can’t find a package with the exact same name.New in Chef Infra Client 18.3
default_release
- Ruby Type: String
The default release. For example:
stable
.
options
- Ruby Type: String, Array
One (or more) additional options that are passed to the command. For example, common apt-get directives, such as
--no-install-recommends
. See the apt-get man page for the full list.
overwrite_config_files
- Ruby Type: true, false | Default Value:
false
Overwrite existing configuration files with those supplied by the package, if prompted by APT.
New in Chef Client 14.0
package_name
- Ruby Type: String, Array
An optional property to set the package name if it differs from the resource block’s name.
response_file
- Ruby Type: String
The direct path to the file used to pre-seed a package.
response_file_variables
- Ruby Type: Hash | Default Value:
{}
A Hash of response file variables in the form of {‘VARIABLE’ => ‘VALUE’}.
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String, Array
The version of a package to be installed or upgraded.
Multiple Packages
A resource may specify multiple packages and/or versions for platforms that use Apt, Chocolatey, DNF, Homebrew, Pacman, or Zypper package managers. Specifying multiple packages and/or versions allows a single transaction to:
- Download the specified packages and versions using a single HTTP transaction
- Update or install multiple packages with a single resource during a Chef Infra Client run
For example, installing multiple packages:
package %w(package1 package2)
Installing multiple packages with versions:
package %w(package1 package2) do
version [ '1.3.4-2', '4.3.6-1']
end
Upgrading multiple packages:
package %w(package1 package2) do
action :upgrade
end
Removing multiple packages:
package %w(package1 package2) do
action :remove
end
Purging multiple packages:
package %w(package1 package2) do
action :purge
end
Notifications, using an implicit name:
package %w(package1 package2) do
action :nothing
end
log 'call a notification' do
notifies :install, 'package[package1, package2]', :immediately
end
Note
Notifications and subscriptions do not need to be updated when packages
and versions are added or removed from the package_name
or version
properties.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Multiple Packages
A resource may specify multiple packages and/or versions for platforms that use Apt, Chocolatey, DNF, Homebrew, Pacman, or Zypper package managers. Specifying multiple packages and/or versions allows a single transaction to:
- Download the specified packages and versions using a single HTTP transaction
- Update or install multiple packages with a single resource during a Chef Infra Client run
For example, installing multiple packages:
package %w(package1 package2)
Installing multiple packages with versions:
package %w(package1 package2) do
version [ '1.3.4-2', '4.3.6-1']
end
Upgrading multiple packages:
package %w(package1 package2) do
action :upgrade
end
Removing multiple packages:
package %w(package1 package2) do
action :remove
end
Purging multiple packages:
package %w(package1 package2) do
action :purge
end
Notifications, using an implicit name:
package %w(package1 package2) do
action :nothing
end
log 'call a notification' do
notifies :install, 'package[package1, package2]', :immediately
end
Note
Notifications and subscriptions do not need to be updated when packages
and versions are added or removed from the package_name
or version
properties.
Examples
The following examples demonstrate various approaches for using the apt_package resource in recipes:
Install a package using package manager:
apt_package 'name of package' do
action :install
end
Install a package without specifying the default action:
apt_package 'name of package'
Install multiple packages at once:
apt_package %w(package1 package2 package3)
Install without using recommend packages as a dependency:
package 'apache2' do
options '--no-install-recommends'
end
Prevent the apt_package resource from installing packages with pattern matching names:
By default, the apt_package resource will install the named package. If it can’t find a package with the exact same name, it will treat the package name as regular expression string and match with any package that matches that regular expression. This may lead Chef Infra Client to install one or more packages with names that match that regular expression.
In this example, anchor_package_regex true
prevents the apt_package resource from installing matching packages if it can’t find the lua5.3
package.
apt_package 'lua5.3' do
version '5.3.3-1.1ubuntu2'
anchor_package_regex true
end
apt_preference resource
apt_preference resource pageUse the apt_preference resource to create APT preference files. Preference files are used to control which package versions and sources are prioritized during installation.
New in Chef Infra Client 13.3.
Syntax
The full syntax for all of the properties that are available to the apt_preference resource is:
apt_preference 'name' do
glob String
package_name String # default value: 'name' unless specified
pin String
pin_priority String, Integer
action Symbol # defaults to :add if not specified
end
where:
apt_preference
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.glob
,package_name
,pin
, andpin_priority
are the properties available to this resource.
Actions
The apt_preference resource has the following actions:
:add
- Creates a preferences file under
/etc/apt/preferences.d
. (default) :nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Removes the preferences file, thus unpinning the package.
Properties
The apt_preference resource has the following properties:
glob
- Ruby Type: String
Pin by a
glob()
expression or with a regular expression surrounded by/
.
package_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the package name if it differs from the resource block’s name.
pin
- Ruby Type: String |
REQUIRED
The package version or repository to pin.
pin_priority
- Ruby Type: String, Integer |
REQUIRED
Sets the Pin-Priority for a package. See https://wiki.debian.org/AptPreferences for more details.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the apt_preference resource in recipes:
Pin libmysqlclient16 to a version 5.1.49-3:
apt_preference 'libmysqlclient16' do
pin 'version 5.1.49-3'
pin_priority '700'
end
Note: The pin_priority
of 700
ensures that this version will be preferred over any other available versions.
Unpin a libmysqlclient16:
apt_preference 'libmysqlclient16' do
action :remove
end
Pin all packages to prefer the packages.dotdeb.org repository:
apt_preference 'dotdeb' do
glob '*'
pin 'origin packages.dotdeb.org'
pin_priority '700'
end
apt_repository resource
apt_repository resource pageUse the apt_repository resource to specify additional APT repositories. Adding a new repository will update the APT package cache immediately.
New in Chef Infra Client 12.9.
Syntax
The full syntax for all of the properties that are available to the apt_repository resource is:
apt_repository 'name' do
arch String, false
cache_rebuild true, false # default value: true
components Array # default value: `main` if using a PPA repository.
cookbook String, false
deb_src true, false # default value: false
distribution String, false # default value: The LSB codename of the node such as 'focal'.
key String, Array, false # default value: []
key_proxy String, false
keyserver String, false # default value: "keyserver.ubuntu.com"
repo_name String # default value: 'name' unless specified
trusted true, false # default value: false
uri String
options String, Array # default value: []
action Symbol # defaults to :add if not specified
end
where:
apt_repository
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.arch
,cache_rebuild
,components
,cookbook
,deb_src
,distribution
,key
,key_proxy
,keyserver
,repo_name
,trusted
, anduri
are the properties available to this resource.
Actions
The apt_repository resource has the following actions:
:add
- Creates a repository file at
/etc/apt/sources.list.d/
and builds the repository listing. (default) :nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Removes the repository listing.
Properties
The apt_repository resource has the following properties:
arch
- Ruby Type: String, false
Constrain packages to a particular CPU architecture such as
i386
oramd64
.
cache_rebuild
- Ruby Type: true, false | Default Value:
true
Determines whether to rebuild the APT package cache.
components
- Ruby Type: Array | Default Value:
`main` if using a PPA repository.
Package groupings, such as ‘main’ and ‘stable’.
cookbook
- Ruby Type: String, false
If key should be a cookbook_file, specify a cookbook where the key is located for files/default. Default value is nil, so it will use the cookbook where the resource is used.
deb_src
- Ruby Type: true, false | Default Value:
false
Determines whether or not to add the repository as a source repo as well.
distribution
- Ruby Type: String, false | Default Value:
The LSB codename of the node such as 'focal'.
Usually a distribution’s codename, such as
xenial
,bionic
, orfocal
.
key
- Ruby Type: String, Array, false | Default Value:
[]
If a keyserver is provided, this is assumed to be the fingerprint; otherwise it can be either the URI of GPG key for the repo, or a cookbook_file.
key_proxy
- Ruby Type: String, false
If set, a specified proxy is passed to GPG via
http-proxy=
.
keyserver
- Ruby Type: String, false | Default Value:
keyserver.ubuntu.com
The GPG keyserver where the key for the repo should be retrieved.
repo_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the repository name if it differs from the resource block’s name. The value of this setting must not contain spaces.
New in Chef Client 14.1
trusted
- Ruby Type: true, false | Default Value:
false
Determines whether you should treat all packages from this repository as authenticated regardless of signature.
options
- Ruby Type: String, Array | Default Value:
[]
Additional options to set for the repository.
uri
- Ruby Type: String
The base of the Debian distribution.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the apt_repository resource in recipes:
Add repository with basic settings:
apt_repository 'nginx' do
uri 'http://nginx.org/packages/ubuntu/'
components ['nginx']
end
Enable Ubuntu multiverse repositories:
apt_repository 'security-ubuntu-multiverse' do
uri 'http://security.ubuntu.com/ubuntu'
distribution 'xenial-security'
components ['multiverse']
deb_src true
end
Add the Nginx PPA, autodetect the key and repository url:
apt_repository 'nginx-php' do
uri 'ppa:nginx/stable'
end
Add the JuJu PPA, grab the key from the Ubuntu keyserver, and add source repo:
apt_repository 'juju' do
uri 'ppa:juju/stable'
components ['main']
distribution 'xenial'
key 'C8068B11'
action :add
deb_src true
end
Add repository that requires multiple keys to authenticate packages:
apt_repository 'rundeck' do
uri 'https://dl.bintray.com/rundeck/rundeck-deb'
distribution '/'
key ['379CE192D401AB61', 'http://rundeck.org/keys/BUILD-GPG-KEY-Rundeck.org.key']
keyserver 'keyserver.ubuntu.com'
action :add
end
Add the Cloudera Repo of CDH4 packages for Ubuntu 16.04 on AMD64:
apt_repository 'cloudera' do
uri 'http://archive.cloudera.com/cdh4/ubuntu/xenial/amd64/cdh'
arch 'amd64'
distribution 'xenial-cdh4'
components ['contrib']
key 'http://archive.cloudera.com/debian/archive.key'
end
Add repository that needs custom options:
apt_repository 'corretto' do
uri 'https://apt.corretto.aws'
arch 'amd64'
distribution 'stable'
components ['main']
options ['target-=Contents-deb']
key 'https://apt.corretto.aws/corretto.key'
end
Remove a repository from the list:
apt_repository 'zenoss' do
action :remove
end
apt_update resource
apt_update resource pageUse the apt_update resource to manage APT repository updates on Debian and Ubuntu platforms.
New in Chef Infra Client 12.7.
Syntax
The full syntax for all of the properties that are available to the apt_update resource is:
apt_update 'name' do
frequency Integer # default value: 86400
action Symbol # defaults to :periodic if not specified
end
where:
apt_update
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.frequency
is the property available to this resource.
Nameless
This resource can be nameless. Add the resource itself to your recipe to get the default behavior:
apt_update
will behave the same as:
apt_update 'update'
Actions
The apt_update resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:periodic
- Update the Apt repository at the interval specified by the
frequency
property. (default) :update
- Update the Apt repository at the start of a Chef Infra Client run.
Properties
The apt_update resource has the following properties:
frequency
- Ruby Type: Integer | Default Value:
86400
Determines how frequently (in seconds) APT repository updates are made. Use this property when the
:periodic
action is specified.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the apt_update resource in recipes:
Update the Apt repository at a specified interval:
apt_update 'all platforms' do
frequency 86400
action :periodic
end
Update the Apt repository at the start of a Chef Infra Client run:
apt_update 'update'
archive_file resource
archive_file resource pageUse the archive_file resource to extract archive files to disk. This resource uses the libarchive library to extract multiple archive formats including tar, gzip, bzip, and zip formats.
New in Chef Infra Client 15.0.
Syntax
The full syntax for all of the properties that are available to the archive_file resource is:
archive_file 'name' do
destination String
group String
mode String, Integer # default value: "'755'"
options Array, Symbol
overwrite true, false, auto # default value: false
owner String
path String # default value: 'name' unless specified
strip_components Integer # default value: 0
action Symbol # defaults to :extract if not specified
end
where:
archive_file
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.destination
,group
,mode
,options
,overwrite
,owner
,path
, andstrip_components
are the properties available to this resource.
Actions
The archive_file resource has the following actions:
:extract
- Extract and archive file. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The archive_file resource has the following properties:
destination
- Ruby Type: String |
REQUIRED
The file path to extract the archive file to.
group
- Ruby Type: String
The group of the extracted files.
mode
- Ruby Type: String, Integer | Default Value:
'755'
The mode of the extracted files. Integer values are deprecated as octal values (ex. 0755) would not be interpreted correctly.
options
- Ruby Type: Array, Symbol | Default Value:
lazy default
An array of symbols representing extraction flags. Example:
:no_overwrite
to prevent overwriting files on disk. By default, this properly sets:time
which preserves the modification timestamps of files in the archive when writing them to disk.
overwrite
- Ruby Type: true, false, auto | Default Value:
false
Should the resource overwrite the destination file contents if they already exist? If set to
:auto
the date stamp of files within the archive will be compared to those on disk and disk contents will be overwritten if they differ. This may cause unintended consequences if disk date stamps are changed between runs, which will result in the files being overwritten during each client run. Make sure to properly test any change to this property.
owner
- Ruby Type: String
The owner of the extracted files.
path
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the file path to the archive to extract if it differs from the resource block’s name.
strip_components
- Ruby Type: Integer | Default Value:
0
Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped. This behaves similarly to tar’s –strip-components command line argument.
New in Chef Infra Client 17.5
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the archive_file resource in recipes:
Extract a zip file to a specified directory:
archive_file 'Precompiled.zip' do
path '/tmp/Precompiled.zip'
destination '/srv/files'
end
Set specific permissions on the extracted files:
archive_file 'Precompiled.zip' do
owner 'tsmith'
group 'staff'
mode '700'
path '/tmp/Precompiled.zip'
destination '/srv/files'
end
bash resource
bash resource pageUse the bash resource to execute scripts using the Bash interpreter. This resource may also use any of the actions and properties that are available to the execute resource. 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.
Syntax
The full syntax for all of the properties that are available to the bash resource is:
bash 'name' do
code String
command String, Array # default value: 'name' unless specified
creates String
cwd String
default_env true, false # default value: false
domain String
elevated true, false # default value: false
environment Hash
flags String
group String, Integer
input String
interpreter String
live_stream true, false # default value: false
login true, false # default value: false
password String
returns Integer, Array # default value: 0
timeout Integer, String, Float # default value: 3600
user String, Integer
action Symbol # defaults to :run if not specified
end
where:
bash
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.code
,command
,creates
,cwd
,default_env
,domain
,elevated
,environment
,flags
,group
,input
,interpreter
,live_stream
,login
,password
,returns
,timeout
, anduser
are the properties available to this resource.
Actions
The bash resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:run
- Run a command. (default)
Properties
The bash resource has the following properties:
code
- Ruby Type: String |
REQUIRED
A quoted string of code to be executed.
command
- Ruby Type: String, Array | Default Value:
The resource block's name
An optional property to set the command to be executed if it differs from the resource block’s name.
Note
Use the execute resource to run a single command. Use multiple execute resource blocks to run multiple commands.
creates
- Ruby Type: String
Prevent a command from creating a file when that file already exists.
cwd
- Ruby Type: String
The current working directory from which the command will be run.
default_env
- Ruby Type: true, false | Default Value:
false
When
true
this enables ENV magic to add path_sanity to the PATH and force the locale to English+UTF-8 for parsing output.New in Chef Client 14.2
domain
- Ruby Type: String
Windows only: The domain of the user specified by the user property. If not specified, the username and password specified by the
user
andpassword
properties will be used to resolve that user against the domain in which the system running Chef Infra 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.New in Chef Client 12.21
elevated
- Ruby Type: true, false | Default Value:
false
Determines whether the script will run with elevated permissions to circumvent User Access Control (UAC) from interactively blocking the process. This will cause the process to be run under a batch login instead of an interactive login. The user running chef-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. Because this requires a login, the user and password properties are required.
New in Chef Client 13.3
environment
- Ruby Type: Hash
A Hash of environment variables in the form of
({'ENV_VARIABLE' => 'VALUE'})
. Note: These variables must exist for a command to be run successfully.
flags
- Ruby Type: String
One or more command line flags that are passed to the interpreter when a command is invoked.
group
- Ruby Type: String, Integer
The group name or group ID that must be changed before running a command.
input
- Ruby Type: String
An optional property to set the input sent to the command as STDIN.
New in Chef Infra Client 16.2
live_stream
- Ruby Type: true, false | Default Value:
false
Send the output of the command run by this execute resource block to the Chef Infra Client event stream.
login
- Ruby Type: true, false | Default Value:
false
Use a login shell to run the commands instead of inheriting the existing execution environment.
New in Chef Infra Client 17.0
password
- Ruby Type: String
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.
New in Chef Client 12.21
returns
- Ruby Type: Integer, Array | Default Value:
0
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.
timeout
- Ruby Type: Integer, String, Float | Default Value:
3600
The amount of time (in seconds) a command is to wait before timing out.
user
- Ruby Type: String, Integer
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.
domain\user
oruser@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.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the bash resource in recipes:
Compile an application
bash 'install_something' do
user 'root'
cwd '/tmp'
code <<-EOH
wget http://www.example.com/tarball.tar.gz
tar -zxf tarball.tar.gz
cd tarball
./configure
make
make install
EOH
end
Using escape characters in a string of code
In the following example, the find
command uses an escape character (\
). Use a second escape character (\\
) to preserve the escape character in the code string:
bash 'delete some archives ' do
code <<-EOH
find ./ -name "*.tar.Z" -mtime +180 -exec rm -f {} \\;
EOH
ignore_failure true
end
Install a file from a remote location
The following is an example of how to install the foo123 module for Nginx. This module adds shell-style functionality to an Nginx configuration file and does the following:
- Declares three variables
- Gets the Nginx file from a remote location
- Installs the file using Bash to the path specified by the
src_filepath
variable
src_filename = "foo123-nginx-module-v#{node['nginx']['foo123']['version']}.tar.gz"
src_filepath = "#{Chef::Config['file_cache_path']}/#{src_filename}"
extract_path = "#{Chef::Config['file_cache_path']}/nginx_foo123_module/#{node['nginx']['foo123']['checksum']}"
remote_file 'src_filepath' do
source node['nginx']['foo123']['url']
checksum node['nginx']['foo123']['checksum']
owner 'root'
group 'root'
mode '0755'
end
bash 'extract_module' do
cwd ::File.dirname(src_filepath)
code <<-EOH
mkdir -p #{extract_path}
tar xzf #{src_filename} -C #{extract_path}
mv #{extract_path}/*/* #{extract_path}/
EOH
not_if { ::File.exist?(extract_path) }
end
Install an application from git
git "#{Chef::Config[:file_cache_path]}/ruby-build" do
repository 'git://github.com/rbenv/ruby-build.git'
revision 'master'
action :sync
end
bash 'install_ruby_build' do
cwd "#{Chef::Config[:file_cache_path]}/ruby-build"
user 'rbenv'
group 'rbenv'
code <<-EOH
./install.sh
EOH
environment 'PREFIX' => '/usr/local'
end
Using Attributes in Bash Code
The following recipe shows how an attributes file can be used to store certain settings. An attributes file is located in the `attributes/`` directory in the same cookbook as the recipe which calls the attributes file. In this example, the attributes file specifies certain settings for Python that are then used across all nodes against which this recipe will run.
Python packages have versions, installation directories, URLs, and checksum files. An attributes file that exists to support this type of recipe would include settings like the following:
default['python']['version'] = '2.7.1'
if python['install_method'] == 'package'
default['python']['prefix_dir'] = '/usr'
else
default['python']['prefix_dir'] = '/usr/local'
end
default['python']['url'] = 'http://www.python.org/ftp/python'
default['python']['checksum'] = '80e387...85fd61'
and then the methods in the recipe may refer to these values. A recipe that is used to install Python will need to do the following:
- Identify each package to be installed (implied in this example, not shown)
- Define variables for the package
version
and theinstall_path
- Get the package from a remote location, but only if the package does not already exist on the target system
- Use the bash resource to install the package on the node, but only when the package is not already installed
version = node['python']['version']
install_path = "#{node['python']['prefix_dir']}/lib/python#{version.split(/(^\d+\.\d+)/)[1]}"
remote_file "#{Chef::Config[:file_cache_path]}/Python-#{version}.tar.bz2" do
source "#{node['python']['url']}/#{version}/Python-#{version}.tar.bz2"
checksum node['python']['checksum']
mode '0755'
not_if { ::File.exist?(install_path) }
end
bash 'build-and-install-python' do
cwd Chef::Config[:file_cache_path]
code <<-EOF
tar -jxvf Python-#{version}.tar.bz2
(cd Python-#{version} && ./configure #{configure_options})
(cd Python-#{version} && make && make install)
EOF
not_if { ::File.exist?(install_path) }
end
batch resource
batch resource pageUse the batch resource to execute a batch script using the cmd.exe interpreter on Windows. The batch resource creates and executes a temporary file (similar to how the script resource behaves), rather than running the command inline. 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.
Syntax
The full syntax for all of the properties that are available to the batch resource is:
batch 'name' do
code String
command String, Array # default value: 'name' unless specified
creates String
cwd String
default_env true, false # default value: false
domain String
elevated true, false # default value: false
environment Hash
flags String
group String, Integer
input String
interpreter String
live_stream true, false # default value: false
login true, false # default value: false
password String
returns Integer, Array # default value: 0
timeout Integer, String, Float # default value: 3600
user String, Integer
action Symbol # defaults to :run if not specified
end
where:
batch
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.code
,command
,creates
,cwd
,default_env
,domain
,elevated
,environment
,flags
,group
,input
,interpreter
,live_stream
,login
,password
,returns
,timeout
, anduser
are the properties available to this resource.
Actions
The batch resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:run
- Run a batch file.
Properties
The batch resource has the following properties:
architecture
- Ruby Type: Symbol
The architecture of the process under which a script is executed. If a value is not provided, Chef Infra Client defaults to the correct value for the architecture, as determined by Ohai. An exception is raised when anything other than
:i386
is specified for a 32-bit process. Possible values::i386
(for 32-bit processes) and:x86_64
(for 64-bit processes).
code
- Ruby Type: String |
REQUIRED
A quoted string of code to be executed.
command
- Ruby Type: String, Array | Default Value:
The resource block's name.
The name of the command to be executed.
creates
- Ruby Type: String
Prevent a command from creating a file when that file already exists.
cwd
- Ruby Type: String
The current working directory from which the command will be run.
flags
- Ruby Type: String
One or more command line flags that are passed to the interpreter when a command is invoked.
group
- Ruby Type: String, Integer
The group name or group ID that must be changed before running a command.
guard_interpreter
- Ruby Type: Symbol | Default Value:
:batch
When this property is set to
:batch
, the 64-bit version of the cmd.exe shell will be used to evaluate strings values for the not_if and only_if properties. Set this value to:default
to use the 32-bit version of the cmd.exe shell.
interpreter
- Ruby Type: String
The script interpreter to use during code execution. Changing the default value of this property is not supported.
returns
- Ruby Type: Integer, Array | Default Value:
0
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.
timeout
- Ruby Type: Integer, String, Float | Default Value:
3600
The amount of time (in seconds) a command is to wait before timing out.
user
- Ruby Type: String
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
oruser@subdomain.dns.example.com
via Universal Principal Name (UPN)format. It can also be specified without a domain simply asuser
if the domain is instead specified using the domain attribute. On Windows only, if this property is specified, the password property must be specified.
password
- Ruby Type: String
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 ifuser
is specified. The sensitive property for this resource will automatically be set totrue
if password is specified.
domain
- Ruby Type: String
Windows only: The domain of the user specified by the
user
property. If not specified, the user name and password specified by theuser
andpassword
properties will be used to resolve that user against the domain in which the system running Chef Infra 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 theuser
property.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the batch resource in recipes:
Unzip a file, and then move it
To run a batch file that unzips and then moves Ruby, do something like:
batch 'unzip_and_move_ruby' do
code <<-EOH
7z.exe x #{Chef::Config[:file_cache_path]}/ruby-1.8.7-p352-i386-mingw32.7z
-oC:\\source -r -y
xcopy C:\\source\\ruby-1.8.7-p352-i386-mingw32 C:\\ruby /e /y
EOH
end
batch 'echo some env vars' do
code <<-EOH
echo %TEMP%
echo %SYSTEMDRIVE%
echo %PATH%
echo %WINDIR%
EOH
end
or:
batch 'unzip_and_move_ruby' do
code <<-EOH
7z.exe x #{Chef::Config[:file_cache_path]}/ruby-1.8.7-p352-i386-mingw32.7z
-oC:\\source -r -y
xcopy C:\\source\\ruby-1.8.7-p352-i386-mingw32 C:\\ruby /e /y
EOH
end
batch 'echo some env vars' do
code 'echo %TEMP%\\necho %SYSTEMDRIVE%\\necho %PATH%\\necho %WINDIR%'
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:
# 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.
# Passing only username and password
batch 'mkdir test_dir' do
code "mkdir test_dir"
cwd Chef::Config[:file_cache_path]
user "username"
password "password"
end
# Passing username and domain
batch 'mkdir test_dir' do
code "mkdir test_dir"
cwd Chef::Config[:file_cache_path]
domain "domain"
user "username"
password "password"
end
# Passing username = 'domain-name\\username'. No domain is passed
batch 'mkdir test_dir' do
code "mkdir test_dir"
cwd Chef::Config[:file_cache_path]
user "domain-name\\username"
password "password"
end
# Passing username = 'username@domain-name'. No domain is passed
batch 'mkdir test_dir' do
code "mkdir test_dir"
cwd Chef::Config[:file_cache_path]
user "username@domain-name"
password "password"
end
bff_package resource
bff_package resource pageUse the bff_package resource to manage packages for the AIX platform using the installp utility. When a package is installed from a local file, it must be added to the node using the remote_file or cookbook_file resources.
Note
A Backup File Format (BFF) package may not have a .bff
file extension. Chef Infra Client will still identify the correct provider to use based on the platform, regardless of the file extension.
Note
Syntax
The full syntax for all of the properties that are available to the bff_package resource is:
bff_package 'name' do
options String, Array
package_name String
source String
timeout String, Integer
version String
action Symbol # defaults to :install if not specified
end
where:
bff_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.options
,package_name
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The bff_package resource has the following actions:
:install
- (default) Install a package. If a version is specified, install the specified version of the package.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:purge
- Purge a package. This action typically removes the configuration files as well as the package.
:remove
- Remove a package.
Properties
The bff_package resource has the following properties:
options
- Ruby Type: String, Array
One (or more) additional command options that are passed to the command.
package_name
- Ruby Type: String
An optional property to set the package name if it differs from the resource block’s name.
source
- Ruby Type: String
Required. The path to a package in the local file system. The AIX platform requires
source
to be a local file system path becauseinstallp
does not retrieve packages using HTTP or FTP.
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String
The version of a package to be installed or upgraded.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the bff_package resource in recipes:
The bff_package resource is the default package provider on the AIX platform. The base package resource may be used, and then when the platform is AIX, Chef Infra Client will identify the correct package provider. The following examples show how to install part of the IBM XL C/C++ compiler.
Installing using the base package resource
package 'xlccmp.13.1.0' do
source '/var/tmp/IBM_XL_C_13.1.0/usr/sys/inst.images/xlccmp.13.1.0'
action :install
end
Installing using the bff_package resource
bff_package 'xlccmp.13.1.0' do
source '/var/tmp/IBM_XL_C_13.1.0/usr/sys/inst.images/xlccmp.13.1.0'
action :install
end
breakpoint resource
breakpoint resource pageUse the breakpoint resource to add breakpoints to recipes. Run the chef-shell in Chef Infra Client mode, and then use those breakpoints to debug recipes. Breakpoints are ignored by the chef-client during an actual chef-client run. That said, breakpoints are typically used to debug recipes only when running them in a non-production environment, after which they are removed from those recipes before the parent cookbook is uploaded to the Chef server.
New in Chef Infra Client 12.0.
Syntax
The full syntax for all of the properties that are available to the breakpoint resource is:
breakpoint 'name' do
action Symbol # defaults to :break if not specified
end
where:
breakpoint
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.
Actions
The breakpoint resource has the following actions:
:break
- Add a breakpoint for use with chef-shell (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
This resource does not have any properties.
Debug Recipes with chef-shell
chef-shell is a recipe debugging tool that allows the use of breakpoints within recipes. chef-shell runs as an Interactive Ruby (IRb) session. chef-shell supports both recipe and attribute file syntax, as well as interactive debugging features.Modes
chef-shell is tool that is run using an Interactive Ruby (IRb) session. chef-shell currently supports recipe and attribute file syntax, as well as interactive debugging features. chef-shell has three run modes:
Mode | Description |
---|---|
Standalone | Default. No cookbooks are loaded, and the run-list is empty. |
Solo | chef-shell acts as a Chef Solo Client. It attempts to load the chef-solo configuration file at ~/.chef/config.rb and any JSON attributes passed. If the JSON attributes set a run-list, it will be honored. Cookbooks will be loaded in the same way that chef-solo loads them. chef-solo mode is activated with the -s or --solo command line option, and JSON attributes are specified in the same way as for chef-solo, with -j /path/to/chef-solo.json . |
Client | chef-shell acts as a Chef Infra Client. During startup, it reads the Chef Infra Client configuration file from ~/.chef/client.rb and contacts the Chef Infra Server to get the node's run_list, attributes, and cookbooks. Chef Infra Client mode is activated with the -z or --client options. You can also specify the configuration file with -c CONFIG and the server URL with -S SERVER_URL . |
Configure
chef-shell determines which configuration file to load based on the following:
- If a configuration file is specified using the
-c
option, chef-shell will use the specified configuration file - If a NAMED_CONF is given, chef-shell will load ~/.chef/NAMED_CONF/chef_shell.rb
- If no NAMED_CONF is given chef-shell will load ~/.chef/chef_shell.rb if it exists
- If no chef_shell.rb can be found, chef-shell falls back to load:
- /etc/chef/client.rb if -z option is given.
- /etc/chef/solo.rb if –solo-legacy-mode option is given.
- .chef/config.rb if -s option is given.
- .chef/knife.rb if -s option is given.
chef-shell.rb
The chef-shell.rb file can be used to configure chef-shell in the same
way as the client.rb file is used to configure Chef Infra Client. For
example, to configure chef-shell to authenticate to the Chef Infra
Server, copy the node_name
, client_key
, and chef_server_url
settings from the config.rb file:
node_name 'your-knife-clientname'
client_key File.expand_path('~/.chef/my-client.pem')
chef_server_url 'https://api.opscode.com/organizations/myorg'
and then add them to the chef-shell.rb file. Other configuration possibilities include disabling Ohai plugins (which will speed up the chef-shell boot process) or including arbitrary Ruby code in the chef-shell.rb file.
Run as a Chef Infra Client
By default, chef-shell loads in standalone mode and does not connect to the Chef Infra Server. The chef-shell can be run as a Chef Infra Client to verify functionality that is only available when Chef Infra Client connects to the Chef Infra Server, such as search functionality or accessing data stored in data bags.
chef-shell can use the same credentials as knife when connecting to a
Chef Infra Server. Make sure that the settings in chef-shell.rb are the
same as those in config.rb, and then use the -z
option as part of the
command. For example:
chef-shell -z
Manage
When chef-shell is configured to access a Chef Infra Server, chef-shell can list, show, search for and edit cookbooks, clients, nodes, roles, environments, policyfiles, and data bags.
The syntax for managing objects on the Chef Infra Server is as follows:
chef-shell -z named_configuration
Where:
named_configuration
is an existing configuration file in~/.chef/named_configuration/chef_shell.rb
, such asproduction
,staging
, ortest
.
Once in chef-shell, commands can be run against objects as follows:
chef (preprod) > items.command
Where:
items
is the type of item to search for:cookbooks
,clients
,nodes
,roles
,environments
or a data bag.command
is the command:list
,show
,find
, oredit
.
For example, to list all of the nodes in a configuration named “preprod”, enter:
chef (preprod) > nodes.list
Which will return something similar to:
=> [node[i-f09a939b], node[i-049a936f], node[i-eaaaa581], node[i-9154b1fb],
node[i-6a213101], node[i-c2687aa9], node[i-7abeaa11], node[i-4eb8ac25],
node[i-9a2030f1], node[i-a06875cb], node[i-145f457f], node[i-e032398b],
node[i-dc8c98b7], node[i-6afdf401], node[i-f49b119c], node[i-5abfab31],
node[i-78b8ac13], node[i-d99678b3], node[i-02322269], node[i-feb4a695],
node[i-9e2232f5], node[i-6e213105], node[i-cdde3ba7], node[i-e8bfb083],
node[i-743c2c1f], node[i-2eaca345], node[i-aa7f74c1], node[i-72fdf419],
node[i-140e1e7f], node[i-f9d43193], node[i-bd2dc8d7], node[i-8e7f70e5],
node[i-78f2e213], node[i-962232fd], node[i-4c322227], node[i-922232f9],
node[i-c02728ab], node[i-f06c7b9b]]
The list
command can take a code block, which will applied (but not
saved), to each object that is returned from the server. For example:
chef (preprod) > nodes.list {|n| puts "#{n.name}: #{n.run_list}" }
will return something similar to:
=> i-f09a939b: role[lb], role[preprod], recipe[aws]
i-049a936f: role[lb], role[preprod], recipe[aws]
i-9154b1fb: recipe[erlang], role[base], role[couchdb], role[preprod],
i-6a213101: role[chef], role[preprod]
# more...
The show
command can be used to display a specific node. For example:
chef (preprod) > load_balancer = nodes.show('i-f09a939b')
will return something similar to:
=> node[i-f09a939b]
Or:
chef (preprod) > load_balancer.ec2.public_hostname
will return something similar to:
=> "ec2-111-22-333-44.compute-1.amazonaws.com"
The find
command can be used to search the Chef Infra Server from the
chef-shell. For example:
chef (preprod) > pp nodes.find(:ec2_public_hostname => 'ec2*')
You can also format the results with a code block. For example:
chef (preprod) > pp nodes.find(:ec2_public_hostname => 'ec2*') {|n| n.ec2.ami_id } and nil
will return something similar to:
=> ["ami-f8927a91",
"ami-f8927a91",
"ami-a89870c1",
"ami-a89870c1",
"ami-a89870c1",
"ami-a89870c1",
"ami-a89870c1"
# and more...
Or:
chef (preprod) > amis = nodes.find(:ec2_public_hostname => 'ec2*') {|n| n.ec2.ami_id }
chef (preprod) > puts amis.uniq.sort
will return something similar to:
=> ami-4b4ba522
ami-a89870c1
ami-eef61587
ami-f8927a91
Use Breakpoints
chef-shell allows the current position in a run-list to be manipulated during a Chef Infra Client run. Add breakpoints to a recipe to take advantage of this functionality.Step Through Run-list
To explore how using the breakpoint to manually step through a Chef Infra Client run, create a simple recipe in chef-shell:
chef > recipe_mode
chef:recipe > echo off
chef:recipe > file "/tmp/before-breakpoint"
chef:recipe > breakpoint "foo"
chef:recipe > file "/tmp/after-breakpoint"
and then run Chef Infra Client:
chef:recipe > run_chef
[Fri, 15 Jan 2020 14:17:49 -0800] DEBUG: Processing file[/tmp/before-breakpoint]
[Fri, 15 Jan 2020 14:17:49 -0800] DEBUG: file[/tmp/before-breakpoint] using Chef::Provider::File
[Fri, 15 Jan 2020 14:17:49 -0800] INFO: Creating file[/tmp/before-breakpoint] at /tmp/before-breakpoint
[Fri, 15 Jan 2020 14:17:49 -0800] DEBUG: Processing [./bin/../lib/chef/mixin/recipe_definition_dsl_core.rb:56:in 'new']
[Fri, 15 Jan 2020 14:17:49 -0800] DEBUG: [./bin/../lib/chef/mixin/recipe_definition_dsl_core.rb:56:in 'new'] using Chef::Provider::Breakpoint
Chef Infra Client ran the first resource before the breakpoint
(file[/tmp/before-breakpoint]
), but then stopped after execution. Chef
Infra Client attempted to name the breakpoint after its position in the
source file, but Chef Infra Client was confused because the resource was
entered interactively. From here, chef-shell can resume the interrupted
Chef Infra Client run:
chef:recipe > chef_run.resume
[Fri, 15 Jan 2020 14:27:08 -0800] INFO: Creating file[/tmp/after-breakpoint] at /tmp/after-breakpoint
A quick view of the /tmp
directory shows that the following files were
created:
after-breakpoint
before-breakpoint
You can rewind and step through a Chef Infra Client run:
chef:recipe > Chef::Log.level = :debug # debug logging will not turn on automatically in this case
=> :debug
chef:recipe > chef_run.rewind
=> 0
chef:recipe > chef_run.step
[Fri, 15 Jan 2020 14:40:52 -0800] DEBUG: Processing file[/tmp/before-breakpoint]
[Fri, 15 Jan 2020 14:40:52 -0800] DEBUG: file[/tmp/before-breakpoint] using Chef::Provider::File
=> 1
chef:recipe > chef_run.step
[Fri, 15 Jan 2020 14:40:54 -0800] DEBUG: Processing [./bin/../lib/chef/mixin/recipe_definition_dsl_core.rb:56:in 'new']
[Fri, 15 Jan 2020 14:40:54 -0800] DEBUG: [./bin/../lib/chef/mixin/recipe_definition_dsl_core.rb:56:in 'new'] using Chef::Provider::Breakpoint
=> 2
chef:recipe > chef_run.step
[Fri, 15 Jan 2020 14:40:56 -0800] DEBUG: Processing file[/tmp/after-breakpoint]
[Fri, 15 Jan 2020 14:40:56 -0800] DEBUG: file[/tmp/after-breakpoint] using Chef::Provider::File
=> 3
From the output, the rewound run-list is shown, but when the resources are executed again, they will repeat their checks for the existence of files. If they exist, Chef Infra Client will skip creating them. If the files are deleted, then:
chef:recipe > ls("/tmp").grep(/breakpoint/).each {|f| rm "/tmp/#{f}" }
=> ["after-breakpoint", "before-breakpoint"]
Rewind, and then resume your Chef Infra Client run to get the expected results:
chef:recipe > chef_run.rewind
chef:recipe > chef_run.resume
[Fri, 15 Jan 2020 14:48:56 -0800] DEBUG: Processing file[/tmp/before-breakpoint]
[Fri, 15 Jan 2020 14:48:56 -0800] DEBUG: file[/tmp/before-breakpoint] using Chef::Provider::File
[Fri, 15 Jan 2020 14:48:56 -0800] INFO: Creating file[/tmp/before-breakpoint] at /tmp/before-breakpoint
[Fri, 15 Jan 2020 14:48:56 -0800] DEBUG: Processing [./bin/../lib/chef/mixin/recipe_definition_dsl_core.rb:56:in 'new']
[Fri, 15 Jan 2020 14:48:56 -0800] DEBUG: [./bin/../lib/chef/mixin/recipe_definition_dsl_core.rb:56:in 'new'] using Chef::Provider::Breakpoint
chef:recipe > chef_run.resume
[Fri, 15 Jan 2020 14:49:20 -0800] DEBUG: Processing file[/tmp/after-breakpoint]
[Fri, 15 Jan 2020 14:49:20 -0800] DEBUG: file[/tmp/after-breakpoint] using Chef::Provider::File
[Fri, 15 Jan 2020 14:49:20 -0800] INFO: Creating file[/tmp/after-breakpoint] at /tmp/after-breakpoint
Debug Existing Recipe
chef-shell can be used to debug existing recipes. The recipe first needs to be added to a run-list for the node, so that it is cached when starting chef-shell and then used for debugging. chef-shell will report which recipes are being cached when it is started:
loading configuration: none (standalone session)
Session type: standalone
Loading.............done.
Welcome to the chef-shell 15.8.23
For usage see https://docs.chef.io/chef_shell.html
run `help' for help, `exit' or ^D to quit.
chef (15.8.23)>
To just load one recipe from the run-list, go into the recipe and use
the include_recipe
command. For example:
chef > recipe_mode
chef:recipe > include_recipe "getting-started"
=> [#< Chef::Recipe:0x10256f9e8 @cookbook_name="getting-started",
... output truncated ...
To load all of the recipes from a run-list, use code similar to the following:
node.run_list.expand(node.chef_environment).recipes.each do |r|
include_recipe r
end
After the recipes that are to be debugged have been loaded, use the
run_chef
command to run them.
Advanced Debugging
In chef-shell, it is possible to get verbose debugging using the tracing feature in Interactive Ruby (IRb). chef-shell provides a shortcut for turning tracing on and off. For example:
chef > tracing on
tracing is on
=> nil
chef >
and:
chef > tracing off
#0:(irb):2:Object:-: tracing off
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:109:Shell::Extensions::ObjectCoreExtensions:>: def off
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:110:Shell::Extensions::ObjectCoreExtensions:-: :off
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:111:Shell::Extensions::ObjectCoreExtensions:<: end
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:272:main:>: def tracing(on_or_off)
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:273:main:-: conf.use_tracer = on_or_off.on_off_to_bool
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:162:Shell::Extensions::Symbol:>: def on_off_to_bool
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:163:Shell::Extensions::Symbol:-: to_s.on_off_to_bool
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:149:Shell::Extensions::String:>: def on_off_to_bool
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:150:Shell::Extensions::String:-: case self
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:154:Shell::Extensions::String:-: false
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:158:Shell::Extensions::String:<: end
#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:164:Shell::Extensions::Symbol:<: end
tracing is off
=> nil
chef >
Debug Examples
The following examples show how to use chef-shell.
"Hello World"
This example shows how to run chef-shell in standalone mode. (For
chef-solo or Chef Infra Client modes, you would need to run chef-shell
using the -s
or -z
command line options, and then take into
consideration the necessary configuration settings.)
When Chef Infra Client is installed using RubyGems or a package manager,
chef-shell should already be installed. When Chef Infra Client is run
from a git clone, it will be located in chef/bin/chef shell
. To start
chef-shell, just run it without any options. You’ll see the loading
message, then the banner, and then the chef-shell prompt:
bin/chef-shell
loading configuration: none (standalone session)
Session type: standalone
Loading.............done.
Welcome to the chef-shell 15.8.23
For usage see https://docs.chef.io/chef_shell.html
run `help' for help, `exit' or ^D to quit.
chef (15.8.23)>
(Use the help command to print a list of supported commands.) Use the recipe_mode command to switch to recipe context:
chef > recipe_mode
chef:recipe_mode >
Typing is evaluated in the same context as recipes. Create a file resource:
chef:recipe_mode > file "/tmp/ohai2u_shef"
=> #< Chef::Resource::File:0x1b691ac
@enclosing_provider=nil,
@resource_name=:file,
@before=nil,
@supports={},
@backup=5,
@allowed_actions=[:nothing, :create, :delete, :touch, :create_if_missing],
@only_if=nil,
@noop=nil,
@collection=#< Chef::ResourceCollection:0x1b9926c
@insert_after_idx=nil,
@resources_by_name={"file[/tmp/ohai2u_shef]"=>0},
@resources=[#< Chef::Resource::File:0x1b691ac ...>]>,
@updated=false,
@provider=nil,
@node=< Chef::Node:0xdeeaae
@name="eigenstate.local">,
@recipe_name=nil,
@not_if=nil,
@name="/tmp/ohai2u_shef",
@action="create",
@path="/tmp/ohai2u_shef",
@source_line="/Users/username/ruby/chef/chef/(irb#1) line 1",
@params={},
@actions={},
@cookbook_name=nil,
@ignore_failure=false>
(The previous example was formatted for presentation.) At this point,
chef-shell has created the resource and put it in the run-list, but not
yet created the file. To initiate a Chef Infra Client run, use the
run_chef
command:
chef:recipe_mode > run_chef
[Fri, 15 Jan 2020 10:42:47 -0800] DEBUG: Processing file[/tmp/ohai2u_shef]
[Fri, 15 Jan 2020 10:42:47 -0800] DEBUG: file[/tmp/ohai2u_shef] using Chef::Provider::File
[Fri, 15 Jan 2020 10:42:47 -0800] INFO: Creating file[/tmp/ohai2u_shef] at /tmp/ohai2u_shef
=> true
chef-shell can also switch to the same context as attribute files. Set an attribute with the following syntax:
chef:recipe_mode > attributes_mode
chef:attributes > default[:hello] = "ohai2u-again"
=> "ohai2u-again"
chef:attributes >
Switch back to recipe_mode context and use the attributes:
chef:attributes > recipe_mode
=> :attributes
chef:recipe_mode > file "/tmp/#{node.hello}"
Now, run Chef Infra Client again:
chef:recipe_mode > run_chef
[Fri, 15 Jan 2020 10:53:22 -0800] DEBUG: Processing file[/tmp/ohai2u_shef]
[Fri, 15 Jan 2020 10:53:22 -0800] DEBUG: file[/tmp/ohai2u_shef] using Chef::Provider::File
[Fri, 15 Jan 2020 10:53:22 -0800] DEBUG: Processing file[/tmp/ohai2u-again]
[Fri, 15 Jan 2020 10:53:22 -0800] DEBUG: file[/tmp/ohai2u-again] using Chef::Provider::File
[Fri, 15 Jan 2020 10:53:22 -0800] INFO: Creating file[/tmp/ohai2u-again] at /tmp/ohai2u-again
=> true
chef:recipe_mode >
Because the first resource (file[/tmp/ohai2u_shef]
) is still in the
run-list, it gets executed again. And because that file already exists,
Chef Infra Client doesn’t attempt to re-create it. Finally, the files
were created using the ls
method:
chef:recipe_mode > ls("/tmp").grep(/ohai/)
=> ["ohai2u-again", "ohai2u_shef"]
Shell Tutorial
Get Specific Nodes
To get a list of nodes using a recipe named postfix
use
search(:node,"recipe:postfix")
. To get a list of nodes using a
sub-recipe named delivery
, use chef-shell. For example:
search(:node, 'recipes:postfix\:\:delivery')
Note
Single (’ ‘) vs. double (" “) is important. This is because a backslash () needs to be included in the string, instead of having Ruby interpret it as an escape.
Examples
The following examples demonstrate various approaches for using the breakpoint resource in recipes:
A recipe without a breakpoint
yum_key node['yum']['elrepo']['key'] do
url node['yum']['elrepo']['key_url']
action :add
end
yum_repository 'elrepo' do
description 'ELRepo.org Community Enterprise Linux Extras Repository'
key node['yum']['elrepo']['key']
mirrorlist node['yum']['elrepo']['url']
includepkgs node['yum']['elrepo']['includepkgs']
exclude node['yum']['elrepo']['exclude']
action :create
end
The same recipe with breakpoints
In the following example, the name of each breakpoint is an arbitrary string.
breakpoint "before yum_key node['yum']['repo_name']['key']" do
action :break
end
yum_key node['yum']['repo_name']['key'] do
url node['yum']['repo_name']['key_url']
action :add
end
breakpoint "after yum_key node['yum']['repo_name']['key']" do
action :break
end
breakpoint "before yum_repository 'repo_name'" do
action :break
end
yum_repository 'repo_name' do
description 'description'
key node['yum']['repo_name']['key']
mirrorlist node['yum']['repo_name']['url']
includepkgs node['yum']['repo_name']['includepkgs']
exclude node['yum']['repo_name']['exclude']
action :create
end
breakpoint "after yum_repository 'repo_name'" do
action :break
end
In the previous examples, the names are used to indicate if the breakpoint is before or after a resource and also to specify which resource it is before or after.
build_essential resource
build_essential resource pageUse the build_essential resource to install the packages required for compiling C software from source.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the build_essential resource is:
build_essential 'name' do
raise_if_unsupported true, false # default value: false
action Symbol # defaults to :install if not specified
end
where:
build_essential
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.raise_if_unsupported
is the property available to this resource.
Nameless
This resource can be nameless. Add the resource itself to your recipe to get the default behavior:
build_essential
will behave the same as:
build_essential 'install tools'
Actions
The build_essential resource has the following actions:
:install
- Install build essential packages. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:upgrade
- Upgrade the Xcode CLI Tools on macOS hosts. New in Chef Infra Client 16
Properties
The build_essential resource has the following properties:
raise_if_unsupported
- Ruby Type: true, false | Default Value:
false
Raise a hard error on platforms where this resource is unsupported.
New in Chef Infra Client 15.5
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the build_essential resource in recipes:
Install compilation packages:
build_essential
Install compilation packages during the compilation phase:
build_essential 'Install compilation tools' do
compile_time true
end
Upgrade compilation packages on macOS systems:
build_essential 'Install compilation tools' do
action :upgrade
end
cab_package resource
cab_package resource pageUse the cab_package resource to install or remove Microsoft Windows cabinet (.cab) packages.
New in Chef Infra Client 12.15.
Syntax
The full syntax for all of the properties that are available to the cab_package resource is:
cab_package 'name' do
options String, Array
package_name String
source String # default value: The package name.
timeout String, Integer
version String
action Symbol # defaults to :install if not specified
end
where:
cab_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.options
,package_name
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The cab_package resource has the following actions:
:install
- Install a cabinet package. If a version is specified, install the specified version of the package. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove a cabinet package.
Properties
The cab_package resource has the following properties:
options
- Ruby Type: String, Array
One (or more) additional command options that are passed to the command.
package_name
- Ruby Type: String
An optional property to set the package name if it differs from the resource block’s name.
source
- Ruby Type: String | Default Value:
The package name.
The local file path or URL for the CAB package.
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String
The version of a package to be installed or upgraded.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the cab_package resource in recipes:
Using local path in source
cab_package 'Install .NET 3.5 sp1 via KB958488' do
source 'C:\Users\xyz\AppData\Local\Temp\Windows6.1-KB958488-x64.cab'
action :install
end
cab_package 'Remove .NET 3.5 sp1 via KB958488' do
source 'C:\Users\xyz\AppData\Local\Temp\Windows6.1-KB958488-x64.cab'
action :remove
end
Using URL in source
cab_package 'Install .NET 3.5 sp1 via KB958488' do
source 'https://s3.amazonaws.com/my_bucket/Windows6.1-KB958488-x64.cab'
action :install
end
cab_package 'Remove .NET 3.5 sp1 via KB958488' do
source 'https://s3.amazonaws.com/my_bucket/Temp\Windows6.1-KB958488-x64.cab'
action :remove
end
chef_acl resource
chef_acl resource pageUse the chef_acl resource to interact with access control lists (ACLs) that exist on the Chef Infra Server.
Syntax
The syntax for using the chef_acl resource in a recipe is as follows:
chef_acl 'name' do
attribute 'value' # see properties section below
...
action :action # see actions section below
end
where:
chef_acl
tells Chef Infra Client to use theChef::Provider::ChefAcl
provider during a Chef Infra Client runname
is the name of the resource block; when thepath
property is not specified as part of a recipe,name
is also the name of the Chef Infra Client.attribute
is zero (or more) of the properties that are available for this resourceaction
identifies which steps Chef Infra Client will take to bring the node into the desired state
Actions
The chef_acl resource has the following actions:
:create
- (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The chef_acl resource has the following properties:
chef_server
The URL for the Chef Infra Server.
complete
Use to specify if this resource defines a chef-client completely. When
true
, any property not specified by this resource will be reset to default property values.
ignore_failure
- Ruby Type: true, false | Default Value:
false
Continue running a recipe if a resource fails for any reason.
notifies
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
notifies
is:notifies :action, 'resource[name]', :timer
path
A path to a directory in the chef-repo against which the ACL is applied. For example:
nodes
,nodes/*
,nodes/my_node
,*/*
,**
,roles/base
,data/secrets
,cookbooks/apache2
,/users/*
, and so on.
raw_json
Chef Infra Client as JSON data. For example:
{ "clientname": "client_name", "orgname": "org_name", "validator": false, "certificate": "-----BEGIN CERTIFICATE-----\n ... 1234567890abcdefghijklmnopq\n ... -----END CERTIFICATE-----\n", "name": "node_name" }
recursive
Use to apply changes to child objects. Use
:on_change
to apply changes to child objects only if the parent object changes. Set totrue
to apply changes even if the parent object does not change. Set tofalse
to prevent any changes. Default value::on_change
.
remove_rights
Use to remove rights. For example:
remove_rights :read, :users => 'jkeiser', :groups => [ 'admins', 'users' ]
or:
remove_rights [ :create, :read ], :users => [ 'jkeiser', 'adam' ]
or:
remove_rights :all, :users => [ 'jkeiser', 'adam' ]
rights
Use to add rights. Syntax:
:right, :right => 'user', :groups => [ 'group', 'group']
. For example:rights :read, :users => 'jkeiser', :groups => [ 'admins', 'users' ]
or:
rights [ :create, :read ], :users => [ 'jkeiser', 'adam' ]
or:
rights :all, :users => 'jkeiser'
subscribes
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may listen to another resource, and then take action if the state of the resource being listened to changes. Specify a
'resource[name]'
, the:action
to be taken, and then the:timer
for that action.Note that
subscribes
does not apply the specified action to the resource that it listens to - for example:file '/etc/nginx/ssl/example.crt' do mode '0600' owner 'root' end service 'nginx' do subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately end
In this case the
subscribes
property reloads thenginx
service whenever its certificate file, located under/etc/nginx/ssl/example.crt
, is updated.subscribes
does not make any changes to the certificate file itself, it merely listens for a change to the file, and executes the:reload
action for its resource (in this examplenginx
) when a change is detected.If the other resource does not exist, the subscription will not raise an error. Contrast this with the stricter semantics of
notifies
, which will raise an error if the other resource does not exist.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
subscribes
is:subscribes :action, 'resource[name]', :timer
Examples
This resource does not have any examples.
chef_client resource
chef_client resource pageUse the chef_client resource to create clients on your Chef Infra Server from within Chef Infra cookbook code.
Syntax
The syntax for using the chef_client resource in a recipe is as follows:
chef_client 'name' do
attribute 'value' # see properties section below
...
action :action # see actions section below
end
where:
chef_client
tells Chef Infra Client to use theChef::Provider::ChefClient
provider during a Chef Infra Client runname
is the name of the resource block; when thename
property is not specified as part of a recipe,name
is also the name of the Chef Infra Clientattribute
is zero (or more) of the properties that are available for this resourceaction
identifies which steps Chef Infra Client will take to bring the node into the desired state
Actions
The chef_client resource has the following actions:
:create
- (default) Use to create a chef-client.
:delete
- Use to delete a chef-client.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:regenerate_keys
- Use to regenerate the RSA public key for a chef-client.
Properties
The chef_client resource has the following properties:
admin
Use to specify whether Chef Infra Client is an API client.
chef_server
The URL for the Chef Infra Server.
complete
Use to specify if this resource defines a chef-client completely. When
true
, any property not specified by this resource will be reset to default property values.
ignore_failure
- Ruby Type: true, false | Default Value:
false
Continue running a recipe if a resource fails for any reason.
name
The name of Chef Infra Client.
notifies
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
notifies
is:notifies :action, 'resource[name]', :timer
output_key_format
Use to specify the format of a public key. Possible values:
pem
,der
, oropenssh
. Default value:openssh
.
output_key_path
Use to specify the path to the location in which a public key will be written.
raw_json
Chef Infra Client as JSON data. For example:
{ "clientname": "client_name", "orgname": "org_name", "validator": false, "certificate": "-----BEGIN CERTIFICATE-----\n ... 1234567890abcdefghijklmnopq\n ... -----END CERTIFICATE-----\n", "name": "node_name" }
source_key
Use to copy a public or private key, but apply a different
format
andpassword
. Use in conjunction withsource_key_pass_phrase
andsource_key_path
.
source_key_pass_phrase
The pass phrase for the public key. Use in conjunction with
source_key
andsource_key_path
.
source_key_path
The path to the public key. Use in conjunction with
source_key
andsource_key_pass_phrase
.
subscribes
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may listen to another resource, and then take action if the state of the resource being listened to changes. Specify a
'resource[name]'
, the:action
to be taken, and then the:timer
for that action.Note that
subscribes
does not apply the specified action to the resource that it listens to - for example:file '/etc/nginx/ssl/example.crt' do mode '0600' owner 'root' end service 'nginx' do subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately end
In this case the
subscribes
property reloads thenginx
service whenever its certificate file, located under/etc/nginx/ssl/example.crt
, is updated.subscribes
does not make any changes to the certificate file itself, it merely listens for a change to the file, and executes the:reload
action for its resource (in this examplenginx
) when a change is detected.If the other resource does not exist, the subscription will not raise an error. Contrast this with the stricter semantics of
notifies
, which will raise an error if the other resource does not exist.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
subscribes
is:subscribes :action, 'resource[name]', :timer
validator
Use to specify if Chef Infra Client is a chef-validator.
Examples
This resource does not have any examples.
chef_client_config resource
chef_client_config resource pageUse the chef_client_config resource to create a client.rb file in the Chef Infra Client configuration directory. See the client.rb docs for more details on options available in the client.rb configuration file.
New in Chef Infra Client 16.6.
Syntax
The full syntax for all of the properties that are available to the chef_client_config resource is:
chef_client_config 'name' do
additional_config String
chef_license String
chef_server_url String
config_directory String
data_collector_server_url String
data_collector_token String
event_loggers Array # default value: []
exception_handlers Array # default value: []
file_backup_path String
file_cache_path String
file_staging_uses_destdir String
formatters Array # default value: []
ftp_proxy String
group String
http_proxy String
https_proxy String
log_level Symbol
log_location String, Symbol
minimal_ohai true, false
named_run_list String
no_proxy String, Array # default value: []
node_name String
ohai_disabled_plugins Array # default value: []
ohai_optional_plugins Array # default value: []
pid_file String
policy_group String
policy_name String
policy_persist_run_list true, false
report_handlers Array # default value: []
rubygems_url String, Array
ssl_verify_mode Symbol, String
start_handlers Array # default value: []
user String
action Symbol # defaults to :create if not specified
end
where:
chef_client_config
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.additional_config
,chef_license
,chef_server_url
,config_directory
,data_collector_server_url
,data_collector_token
,event_loggers
,exception_handlers
,file_backup_path
,file_cache_path
,file_staging_uses_destdir
,formatters
,ftp_proxy
,group
,http_proxy
,https_proxy
,log_level
,log_location
,minimal_ohai
,named_run_list
,no_proxy
,node_name
,ohai_disabled_plugins
,ohai_optional_plugins
,pid_file
,policy_group
,policy_name
,policy_persist_run_list
,report_handlers
,rubygems_url
,ssl_verify_mode
,start_handlers
, anduser
are the properties available to this resource.
Actions
The chef_client_config resource has the following actions:
:create
- Create a client.rb config file and folders for configuring Chef Infra Client. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove a client.rb config file for configuring Chef Infra Client.
Properties
The chef_client_config resource has the following properties:
additional_config
- Ruby Type: String
Additional text to add at the bottom of the client.rb config. This can be used to run custom Ruby or to add less common config options
chef_license
- Ruby Type: StringAllowed Values:
"accept", "accept-no-persist", "accept-silent"
Accept the Chef EULA
chef_server_url
- Ruby Type: String |
REQUIRED
The URL for the Chef Infra Server.
config_directory
- Ruby Type: String | Default Value:
`/etc/chef/` on *nix-like systems and `C:\chef\` on Windows
The directory to store the client.rb in.
data_collector_server_url
- Ruby Type: String
The data collector URL (typically automate) to send node, converge, and compliance data.
Note
If possible, use Chef Infra Server to do all data collection reporting, as this removes the need to distribute tokens to individual nodes.
New in Chef Infra Client 17.8
data_collector_token
- Ruby Type: String
The data collector token to interact with the data collector server URL (Automate).
Note
If possible, use Chef Infra Server to do all data collection reporting, as this removes the need to distribute tokens to individual nodes.
New in Chef Infra Client 17.8
event_loggers
- Ruby Type: Array | Default Value:
[]
exception_handlers
- Ruby Type: Array | Default Value:
[]
An array of hashes that contain a exception handler class and the arguments to pass to that class on initialization. The hash should include
class
andargument
keys whereclass
is a String andargument
is an array of quoted String values. For example:[{'class' => 'MyHandler', %w('"argument1"', '"argument2"')}]
file_backup_path
- Ruby Type: String
The location in which backup files are stored. If this value is empty, backup files are stored in the directory of the target file
file_cache_path
- Ruby Type: String
The location in which cookbooks (and other transient data) files are stored when they are synchronized. This value can also be used in recipes to download files with the
remote_file
resource.
file_staging_uses_destdir
- Ruby Type: String
How file staging (via temporary files) is done. When
true
, temporary files are created in the directory in which files will reside. Whenfalse
, temporary files are created underENV['TMP']
formatters
- Ruby Type: Array | Default Value:
[]
Client logging formatters to load.
ftp_proxy
- Ruby Type: String
The proxy server to use for FTP connections.
group
- Ruby Type: String
The group that should own the client.rb file and the configuration directory if it needs to be created.
Note
The configuration directory will not be created if it already exists, which allows you to further control the setup of that directory outside of this resource.
http_proxy
- Ruby Type: String
The proxy server to use for HTTP connections.
https_proxy
- Ruby Type: String
The proxy server to use for HTTPS connections.
log_level
- Ruby Type: SymbolAllowed Values:
:auto, :debug, :fatal, :info, :trace, :warn
The level of logging performed by the Chef Infra Client.
log_location
- Ruby Type: String, Symbol
The location to save logs to. This can either by a path to a log file on disk
:syslog
to log to Syslog,:win_evt
to log to the Windows Event Log, or'STDERR'
/'STDOUT'
to log to the *nix text streams.
minimal_ohai
- Ruby Type: true, false
Run a minimal set of Ohai plugins providing data necessary for the execution of Chef Infra Client’s built-in resources. Setting this to true will skip many large and time consuming data sets such as
cloud
orpackages
. Setting this this to true may break cookbooks that assume all Ohai data will be present.
named_run_list
- Ruby Type: String
A specific named runlist defined in the node’s applied Policyfile, which the should be used when running Chef Infra Client.
no_proxy
- Ruby Type: String, Array | Default Value:
[]
A comma-separated list or an array of URLs that do not need a proxy.
node_name
- Ruby Type: String | Default Value:
The `node.name` value reported by Chef Infra Client.
The name of the node. This configuration sets the
node.name
value used in cookbooks and theclient_name
value used when authenticating to a Chef Infra Server to determine what configuration to apply.Note
By default this configuration uses the
node.name
value which would be set during bootstrap. Hard coding this value in theclient.rb
config avoids logic within Chef Infra Server that performs DNS lookups and may fail in the event of a DNS outage. To skip this default value and instead use the built-in Chef Infra Server logic, set this property tonil
ohai_disabled_plugins
- Ruby Type: Array | Default Value:
[]
Ohai plugins that should be disabled in order to speed up the Chef Infra Client run and reduce the size of node data sent to Chef Infra Client
ohai_optional_plugins
- Ruby Type: Array | Default Value:
[]
Optional Ohai plugins that should be enabled to provide additional Ohai data for use in cookbooks.
pid_file
- Ruby Type: String
The location in which a process identification number (pid) is saved. An executable, when started as a daemon, writes the pid to the specified file.
policy_group
- Ruby Type: String
The name of a
policy group
that exists on the Chef Infra Server.policy_name
must also be specified when setting this property.
policy_name
- Ruby Type: String
The name of a policy, as identified by the
name
setting in a Policyfile.rb file.policy_group
when setting this property.
policy_persist_run_list
- Ruby Type: true, false
Override run lists defined in a Policyfile with the
run_list
defined on the Chef Infra Server.New in Chef Infra Client 17.3
report_handlers
- Ruby Type: Array | Default Value:
[]
An array of hashes that contain a report handler class and the arguments to pass to that class on initialization. The hash should include
class
andargument
keys whereclass
is a String andargument
is an array of quoted String values. For example:[{'class' => 'MyHandler', %w('"argument1"', '"argument2"')}]
rubygems_url
- Ruby Type: String, Array
The location to source rubygems. It can be set to a string or array of strings for URIs to set as rubygems sources. This allows individuals to set up an internal mirror of rubygems for airgapped environments.
New in Chef Infra Client 17.11
ssl_verify_mode
- Ruby Type: Symbol, StringAllowed Values:
:verify_none, :verify_peer
Set the verify mode for HTTPS requests.
- Use :verify_none for no validation of SSL certificates.
- Use :verify_peer for validation of all SSL certificates, including the Chef Infra Server connections, S3 connections, and any HTTPS remote_file resource URLs used in Chef Infra Client runs. This is the recommended setting.
start_handlers
- Ruby Type: Array | Default Value:
[]
An array of hashes that contain a report handler class and the arguments to pass to that class on initialization. The hash should include
class
andargument
keys whereclass
is a String andargument
is an array of quoted String values. For example:[{'class' => 'MyHandler', %w('"argument1"', '"argument2"')}]
user
- Ruby Type: String
The user that should own the client.rb file and the configuration directory if it needs to be created.
Note
The configuration directory will not be created if it already exists, which allows you to further control the setup of that directory outside of this resource.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the chef_client_config resource in recipes:
Bare minimum Chef Infra Client client.rb:
The absolute minimum configuration necessary for a node to communicate with the Chef Infra Server is the URL of the Chef Infra Server. All other configuration options either have values at the server side (Policyfiles, Roles, Environments, etc) or have default values determined at client startup.
chef_client_config 'Create client.rb' do
chef_server_url 'https://chef.example.dmz'
end
More complex Chef Infra Client client.rb:
chef_client_config 'Create client.rb' do
chef_server_url 'https://chef.example.dmz'
log_level :info
log_location :syslog
http_proxy 'proxy.example.dmz'
https_proxy 'proxy.example.dmz'
no_proxy %w(internal.example.dmz)
end
Adding additional config content to the client.rb:
This resource aims to provide common configuration options. Some configuration options are missing and some users may want to use arbitrary Ruby code within their configuration. For this we offer an additional_config
property that can be used to add any configuration or code to the bottom of the client.rb
file. Also keep in mind that within the configuration directory is a client.d
directory where you can put additional .rb
files containing configuration options. These can be created using file
or template
resources within your cookbooks as necessary.
chef_client_config 'Create client.rb' do
chef_server_url 'https://chef.example.dmz'
additional_config <<~CONFIG
# Extra config code to safely load a gem into the client run.
# Since the config is Ruby you can run any Ruby code you want via the client.rb.
# It's a great way to break things, so be careful
begin
require 'aws-sdk'
rescue LoadError
Chef::Log.warn "Failed to load aws-sdk."
end
CONFIG
end
Setup two report handlers in the client.rb:
chef_client_config 'Create client.rb' do
chef_server_url 'https://chef.example.dmz'
report_handlers [
{
'class' => 'ReportHandler1Class',
'arguments' => ["'FirstArgument'", "'SecondArgument'"],
},
{
'class' => 'ReportHandler2Class',
'arguments' => ["'FirstArgument'", "'SecondArgument'"],
},
]
end
Report directly to the Chef Automate data collector endpoint.
chef_client_config 'Create client.rb' do
chef_server_url 'https://chef.example.dmz'
data_collector_server_url 'https://automate.example.dmz'
data_collector_token 'TEST_TOKEN_TEST'
end
chef_client_cron resource
chef_client_cron resource pageUse the chef_client_cron resource to setup the Chef Infra Client to run as a cron job. This resource will also create the specified log directory if it doesn’t already exist.
New in Chef Infra Client 16.0.
Syntax
The full syntax for all of the properties that are available to the chef_client_cron resource is:
chef_client_cron 'name' do
accept_chef_license true, false # default value: false
append_log_file true, false # default value: true
chef_binary_path String # default value: "/opt/chef/bin/chef-client"
comment String
config_directory String # default value: "/etc/chef"
daemon_options Array # default value: []
day Integer, String # default value: "*"
environment Hash # default value: {}
hour Integer, String # default value: "*"
job_name String # default value: "chef-client"
log_directory String
log_file_name String # default value: "client.log"
mailto String
minute Integer, String # default value: "0,30"
month Integer, String # default value: "*"
nice Integer, String
splay Integer, String # default value: 300
user String # default value: "root"
weekday Integer, String # default value: "*"
action Symbol # defaults to :add if not specified
end
where:
chef_client_cron
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.accept_chef_license
,append_log_file
,chef_binary_path
,comment
,config_directory
,daemon_options
,day
,environment
,hour
,job_name
,log_directory
,log_file_name
,mailto
,minute
,month
,nice
,splay
,user
, andweekday
are the properties available to this resource.
Actions
The chef_client_cron resource has the following actions:
:add
- Add a cron job to run Chef Infra Client. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove a cron job for Chef Infra Client.
Properties
The chef_client_cron resource has the following properties:
accept_chef_license
- Ruby Type: true, false | Default Value:
false
Accept the Chef Online Master License and Services Agreement. See https://www.chef.io/online-master-agreement
append_log_file
- Ruby Type: true, false | Default Value:
true
Append to the log file instead of overwriting the log file on each run.
chef_binary_path
- Ruby Type: String | Default Value:
/opt/chef/bin/chef-client
The path to the chef-client binary.
comment
- Ruby Type: String
A comment to place in the cron.d file.
config_directory
- Ruby Type: String | Default Value:
/etc/chef
The path of the config directory.
daemon_options
- Ruby Type: Array | Default Value:
[]
An array of options to pass to the chef-client command.
day
- Ruby Type: Integer, String | Default Value:
*
The day of month at which Chef Infra Client is to run (1 - 31) or a cron pattern such as ‘1,7,14,21,28’.
environment
- Ruby Type: Hash | Default Value:
{}
A Hash containing additional arbitrary environment variables under which the cron job will be run in the form of
({'ENV_VARIABLE' => 'VALUE'})
.
hour
- Ruby Type: Integer, String | Default Value:
*
The hour at which Chef Infra Client is to run (0 - 23) or a cron pattern such as ‘0,12’.
job_name
- Ruby Type: String | Default Value:
chef-client
The name of the cron job to create.
log_directory
- Ruby Type: String | Default Value:
/Library/Logs/Chef on macOS and /var/log/chef otherwise
The path of the directory to create the log file in.
log_file_name
- Ruby Type: String | Default Value:
client.log
The name of the log file to use.
mailto
- Ruby Type: String
The e-mail address to e-mail any cron task failures to.
minute
- Ruby Type: Integer, String | Default Value:
0,30
The minute at which Chef Infra Client is to run (0 - 59) or a cron pattern such as ‘0,30’.
month
- Ruby Type: Integer, String | Default Value:
*
The month in the year on which Chef Infra Client is to run (1 - 12, jan-dec, or *).
nice
- Ruby Type: Integer, String
The process priority to run the chef-client process at. A value of -20 is the highest priority and 19 is the lowest priority.
New in Chef Infra Client 16.5
splay
- Ruby Type: Integer, String | Default Value:
300
A random number of seconds between 0 and X to add to interval so that all chef-client commands don’t execute at the same time.
user
- Ruby Type: String | Default Value:
root
The name of the user that Chef Infra Client runs as.
weekday
- Ruby Type: Integer, String | Default Value:
*
The day of the week on which Chef Infra Client is to run (0-7, mon-sun, or *), where Sunday is both 0 and 7.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the chef_client_cron resource in recipes:
Setup Chef Infra Client to run using the default 30 minute cadence:
chef_client_cron 'Run Chef Infra Client as a cron job'
Run Chef Infra Client twice a day:
chef_client_cron 'Run Chef Infra Client every 12 hours' do
minute 0
hour '0,12'
end
Run Chef Infra Client with extra options passed to the client:
chef_client_cron 'Run an override recipe' do
daemon_options ['--override-runlist mycorp_base::default']
end
chef_client_launchd resource
chef_client_launchd resource pageUse the chef_client_launchd resource to configure the Chef Infra Client to run on a schedule on macOS systems.
New in Chef Infra Client 16.5.
Syntax
The full syntax for all of the properties that are available to the chef_client_launchd resource is:
chef_client_launchd 'name' do
accept_chef_license true, false # default value: false
chef_binary_path String # default value: "/opt/chef/bin/chef-client"
config_directory String # default value: "/etc/chef"
daemon_options Array # default value: []
environment Hash # default value: {}
interval Integer, String # default value: 30
log_directory String # default value: "/Library/Logs/Chef"
log_file_name String # default value: "client.log"
low_priority_io true, false # default value: true
nice Integer, String
splay Integer, String # default value: 300
user String # default value: "root"
working_directory String # default value: "/var/root"
action Symbol # defaults to :enable if not specified
end
where:
chef_client_launchd
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.accept_chef_license
,chef_binary_path
,config_directory
,daemon_options
,environment
,interval
,log_directory
,log_file_name
,low_priority_io
,nice
,splay
,user
, andworking_directory
are the properties available to this resource.
Actions
The chef_client_launchd resource has the following actions:
:disable
- Disable running Chef Infra Client on a schedule using launchd
:enable
- Enable running Chef Infra Client on a schedule using launchd. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The chef_client_launchd resource has the following properties:
accept_chef_license
- Ruby Type: true, false | Default Value:
false
Accept the Chef Online Master License and Services Agreement. See https://www.chef.io/online-master-agreement
chef_binary_path
- Ruby Type: String | Default Value:
/opt/chef/bin/chef-client
The path to the chef-client binary.
config_directory
- Ruby Type: String | Default Value:
/etc/chef
The path of the config directory.
daemon_options
- Ruby Type: Array | Default Value:
[]
An array of options to pass to the chef-client command.
environment
- Ruby Type: Hash | Default Value:
{}
A Hash containing additional arbitrary environment variables under which the launchd daemon will be run in the form of
({'ENV_VARIABLE' => 'VALUE'})
.
interval
- Ruby Type: Integer, String | Default Value:
30
Time in minutes between Chef Infra Client executions.
log_directory
- Ruby Type: String | Default Value:
/Library/Logs/Chef
The path of the directory to create the log file in.
log_file_name
- Ruby Type: String | Default Value:
client.log
The name of the log file to use.
low_priority_io
- Ruby Type: true, false | Default Value:
true
Run the chef-client process with low priority disk IO
nice
- Ruby Type: Integer, String
The process priority to run the chef-client process at. A value of -20 is the highest priority and 19 is the lowest priority.
splay
- Ruby Type: Integer, String | Default Value:
300
A random number of seconds between 0 and X to add to interval so that all chef-client commands don’t execute at the same time.
user
- Ruby Type: String | Default Value:
root
The name of the user that Chef Infra Client runs as.
working_directory
- Ruby Type: String | Default Value:
/var/root
The working directory to run the Chef Infra Client from.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the chef_client_launchd resource in recipes:
Set the Chef Infra Client to run on a schedule:
chef_client_launchd 'Setup the Chef Infra Client to run every 30 minutes' do
interval 30
action :enable
end
Disable the Chef Infra Client running on a schedule:
chef_client_launchd 'Prevent the Chef Infra Client from running on a schedule' do
action :disable
end
chef_client_scheduled_task resource
chef_client_scheduled_task resource pageUse the chef_client_scheduled_task resource to setup the Chef Infra Client to run as a Windows scheduled task. This resource will also create the specified log directory if it doesn’t already exist.
New in Chef Infra Client 16.0.
Syntax
The full syntax for all of the properties that are available to the chef_client_scheduled_task resource is:
chef_client_scheduled_task 'name' do
accept_chef_license true, false # default value: false
chef_binary_path String # default value: "C:/opscode/chef/bin/chef-client"
config_directory String # default value: "/etc/chef"
daemon_options Array # default value: []
frequency String # default value: "minute"
frequency_modifier Integer, String # default value: "30 if frequency is 'minute', 1 otherwise"
log_directory String # default value: "CONFIG_DIRECTORY/log"
log_file_name String # default value: "client.log"
password String
priority Integer # default value: 7
run_on_battery true, false # default value: true
splay Integer, String # default value: 300
start_date String
start_time String
task_name String # default value: "chef-client"
use_consistent_splay true, false # default value: false
user String # default value: "System"
action Symbol # defaults to :add if not specified
end
where:
chef_client_scheduled_task
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.accept_chef_license
,chef_binary_path
,config_directory
,daemon_options
,frequency
,frequency_modifier
,log_directory
,log_file_name
,password
,priority
,run_on_battery
,splay
,start_date
,start_time
,task_name
,use_consistent_splay
, anduser
are the properties available to this resource.
Actions
The chef_client_scheduled_task resource has the following actions:
:add
- Add a Windows Scheduled Task that runs Chef Infra Client. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove a Windows Scheduled Task that runs Chef Infra Client.
Properties
The chef_client_scheduled_task resource has the following properties:
accept_chef_license
- Ruby Type: true, false | Default Value:
false
Accept the Chef Online Master License and Services Agreement. See https://www.chef.io/online-master-agreement
chef_binary_path
- Ruby Type: String | Default Value:
C:/opscode/chef/bin/chef-client
The path to the chef-client binary.
config_directory
- Ruby Type: String | Default Value:
/etc/chef
The path of the config directory.
daemon_options
- Ruby Type: Array | Default Value:
[]
An array of options to pass to the chef-client command.
frequency
- Ruby Type: String | Default Value:
minute
Allowed Values:"daily", "hourly", "minute", "monthly", "on_idle", "on_logon", "once", "onstart"
Frequency with which to run the task.
frequency_modifier
- Ruby Type: Integer, String | Default Value:
30 if frequency is 'minute', 1 otherwise
Numeric value to go with the scheduled task frequency
log_directory
- Ruby Type: String | Default Value:
CONFIG_DIRECTORY/log
The path of the directory to create the log file in.
log_file_name
- Ruby Type: String | Default Value:
client.log
The name of the log file to use.
password
- Ruby Type: String
The password for the user that Chef Infra Client runs as.
priority
- Ruby Type: Integer | Default Value:
7
Use to set Priority Levels range from 0 to 10.
New in Chef Infra Client 17.5
run_on_battery
- Ruby Type: true, false | Default Value:
true
Run the Chef Infra Client task when the system is on batteries.
splay
- Ruby Type: Integer, String | Default Value:
300
A random number of seconds between 0 and X to add to interval so that all chef-client commands don’t execute at the same time.
start_date
- Ruby Type: String
The start date for the task in m:d:Y format (ex: 12/17/2020).
start_time
- Ruby Type: String
The start time for the task in HH:mm format (ex: 14:00). If the frequency is minute default start time will be Time.now plus the frequency_modifier number of minutes.
task_name
- Ruby Type: String | Default Value:
chef-client
The name of the scheduled task to create.
use_consistent_splay
- Ruby Type: true, false | Default Value:
false
Always use the same random splay amount for each node to ensure consistent frequencies between chef-client execution.
New in Chef Infra Client 17.5
user
- Ruby Type: String | Default Value:
System
The name of the user that Chef Infra Client runs as.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the chef_client_scheduled_task resource in recipes:
Setup Chef Infra Client to run using the default 30 minute cadence:
chef_client_scheduled_task 'Run Chef Infra Client as a scheduled task'
Run Chef Infra Client on system start:
chef_client_scheduled_task 'Chef Infra Client on start' do
frequency 'onstart'
end
Run Chef Infra Client with extra options passed to the client:
chef_client_scheduled_task 'Run an override recipe' do
daemon_options ['--override-runlist mycorp_base::default']
end
Run Chef Infra Client daily at 01:00 am, specifying a named run-list:
chef_client_scheduled_task 'Run chef-client named run-list daily' do
frequency 'daily'
start_time '01:00'
daemon_options ['-n audit_only']
end
Run Chef Infra Client with a persistent delay on every run calculated once, similar to how chef_client_cron resource works:
chef_client_scheduled_task 'Run chef-client with persistent splay' do
use_consistent_splay true
end
chef_client_systemd_timer resource
chef_client_systemd_timer resource pageUse the chef_client_systemd_timer resource to setup the Chef Infra Client to run as a systemd timer.
New in Chef Infra Client 16.0.
Syntax
The full syntax for all of the properties that are available to the chef_client_systemd_timer resource is:
chef_client_systemd_timer 'name' do
accept_chef_license true, false # default value: false
chef_binary_path String # default value: "/opt/chef/bin/chef-client"
config_directory String # default value: "/etc/chef"
cpu_quota Integer, String
daemon_options Array # default value: []
delay_after_boot String # default value: "1min"
description String # default value: "Chef Infra Client periodic execution"
environment Hash # default value: {}
interval String # default value: "30min"
job_name String # default value: "chef-client"
run_on_battery true, false # default value: true
splay String # default value: "5min"
user String # default value: "root"
action Symbol # defaults to :add if not specified
end
where:
chef_client_systemd_timer
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.accept_chef_license
,chef_binary_path
,config_directory
,cpu_quota
,daemon_options
,delay_after_boot
,description
,environment
,interval
,job_name
,run_on_battery
,splay
, anduser
are the properties available to this resource.
Actions
The chef_client_systemd_timer resource has the following actions:
:add
- Add a systemd timer that runs Chef Infra Client. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove a systemd timer that runs Chef Infra Client.
Properties
The chef_client_systemd_timer resource has the following properties:
accept_chef_license
- Ruby Type: true, false | Default Value:
false
Accept the Chef Online Master License and Services Agreement. See https://www.chef.io/online-master-agreement
chef_binary_path
- Ruby Type: String | Default Value:
/opt/chef/bin/chef-client
The path to the chef-client binary.
config_directory
- Ruby Type: String | Default Value:
/etc/chef
The path of the config directory.
cpu_quota
- Ruby Type: Integer, String
The systemd CPUQuota to run the chef-client process with. This is a percentage value of the total CPU time available on the system. If the system has more than 1 core this may be a value greater than 100.
New in Chef Infra Client 16.5
daemon_options
- Ruby Type: Array | Default Value:
[]
An array of options to pass to the chef-client command.
delay_after_boot
- Ruby Type: String | Default Value:
1min
The time to wait after booting before the interval starts. This is expressed as a systemd time span such as
300seconds
,1hr
, or1m
. See https://www.freedesktop.org/software/systemd/man/systemd.time.html for a complete list of allowed time span values.
description
- Ruby Type: String | Default Value:
Chef Infra Client periodic execution
The description to add to the systemd timer. This will be displayed when running
systemctl status
for the timer.
environment
- Ruby Type: Hash | Default Value:
{}
A Hash containing additional arbitrary environment variables under which the systemd timer will be run in the form of
({'ENV_VARIABLE' => 'VALUE'})
.
interval
- Ruby Type: String | Default Value:
30min
The interval to wait between executions. This is expressed as a systemd time span such as
300seconds
,1hr
, or1m
. See https://www.freedesktop.org/software/systemd/man/systemd.time.html for a complete list of allowed time span values.
job_name
- Ruby Type: String | Default Value:
chef-client
The name of the system timer to create.
run_on_battery
- Ruby Type: true, false | Default Value:
true
Run the timer for Chef Infra Client if the system is on battery.
splay
- Ruby Type: String | Default Value:
5min
A interval between 0 and X to add to the interval so that all chef-client commands don’t execute at the same time. This is expressed as a systemd time span such as
300seconds
,1hr
, or1m
. See https://www.freedesktop.org/software/systemd/man/systemd.time.html for a complete list of allowed time span values.
user
- Ruby Type: String | Default Value:
root
The name of the user that Chef Infra Client runs as.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the chef_client_systemd_timer resource in recipes:
Setup Chef Infra Client to run using the default 30 minute cadence:
chef_client_systemd_timer 'Run Chef Infra Client as a systemd timer'
Run Chef Infra Client every 1 hour:
chef_client_systemd_timer 'Run Chef Infra Client every 1 hour' do
interval '1hr'
end
Run Chef Infra Client with extra options passed to the client:
chef_client_systemd_timer 'Run an override recipe' do
daemon_options ['--override-runlist mycorp_base::default']
end
chef_client_trusted_certificate resource
chef_client_trusted_certificate resource pageUse the chef_client_trusted_certificate resource to add certificates to Chef Infra Client’s trusted certificate directory. This allows the Chef Infra Client to communicate with internal encrypted resources without errors.
New in Chef Infra Client 16.5.
Syntax
The full syntax for all of the properties that are available to the chef_client_trusted_certificate resource is:
chef_client_trusted_certificate 'name' do
cert_name String # default value: 'name' unless specified
certificate String
action Symbol # defaults to :add if not specified
end
where:
chef_client_trusted_certificate
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.cert_name
andcertificate
are the properties available to this resource.
Actions
The chef_client_trusted_certificate resource has the following actions:
:add
- Add a trusted certificate to Chef Infra Client’s trusted certificate directory (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove a trusted certificate from Chef Infra Client’s trusted certificate directory
Properties
The chef_client_trusted_certificate resource has the following properties:
cert_name
- Ruby Type: String | Default Value:
The resource block's name
The name to use for the certificate file on disk. If not provided the name of the resource block will be used instead.
certificate
- Ruby Type: String |
REQUIRED
The text of the certificate file including the BEGIN/END comment lines.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the chef_client_trusted_certificate resource in recipes:
Trust a self signed certificate:
chef_client_trusted_certificate 'self-signed.badssl.com' do
certificate <<~CERT
-----BEGIN CERTIFICATE-----
MIIDeTCCAmGgAwIBAgIJAPziuikCTox4MA0GCSqGSIb3DQEBCwUAMGIxCzAJBgNV
BAYTAlVTMRMwEQYDVQQIDApDYWxpZm9ybmlhMRYwFAYDVQQHDA1TYW4gRnJhbmNp
c2NvMQ8wDQYDVQQKDAZCYWRTU0wxFTATBgNVBAMMDCouYmFkc3NsLmNvbTAeFw0x
OTEwMDkyMzQxNTJaFw0yMTEwMDgyMzQxNTJaMGIxCzAJBgNVBAYTAlVTMRMwEQYD
VQQIDApDYWxpZm9ybmlhMRYwFAYDVQQHDA1TYW4gRnJhbmNpc2NvMQ8wDQYDVQQK
DAZCYWRTU0wxFTATBgNVBAMMDCouYmFkc3NsLmNvbTCCASIwDQYJKoZIhvcNAQEB
BQADggEPADCCAQoCggEBAMIE7PiM7gTCs9hQ1XBYzJMY61yoaEmwIrX5lZ6xKyx2
PmzAS2BMTOqytMAPgLaw+XLJhgL5XEFdEyt/ccRLvOmULlA3pmccYYz2QULFRtMW
hyefdOsKnRFSJiFzbIRMeVXk0WvoBj1IFVKtsyjbqv9u/2CVSndrOfEk0TG23U3A
xPxTuW1CrbV8/q71FdIzSOciccfCFHpsKOo3St/qbLVytH5aohbcabFXRNsKEqve
ww9HdFxBIuGa+RuT5q0iBikusbpJHAwnnqP7i/dAcgCskgjZjFeEU4EFy+b+a1SY
QCeFxxC7c3DvaRhBB0VVfPlkPz0sw6l865MaTIbRyoUCAwEAAaMyMDAwCQYDVR0T
BAIwADAjBgNVHREEHDAaggwqLmJhZHNzbC5jb22CCmJhZHNzbC5jb20wDQYJKoZI
hvcNAQELBQADggEBAGlwCdbPxflZfYOaukZGCaxYK6gpincX4Lla4Ui2WdeQxE95
w7fChXvP3YkE3UYUE7mupZ0eg4ZILr/A0e7JQDsgIu/SRTUE0domCKgPZ8v99k3A
vka4LpLK51jHJJK7EFgo3ca2nldd97GM0MU41xHFk8qaK1tWJkfrrfcGwDJ4GQPI
iLlm6i0yHq1Qg1RypAXJy5dTlRXlCLd8ufWhhiwW0W75Va5AEnJuqpQrKwl3KQVe
wGj67WWRgLfSr+4QG1mNvCZb2CkjZWmxkGPuoP40/y7Yu5OFqxP5tAjj4YixCYTW
EVA0pmzIzgBg+JIe3PdRy27T0asgQW/F4TY61Yk=
-----END CERTIFICATE-----
CERT
end
chef_container resource
chef_container resource pageUse the chef_container resource to interact with container objects that exist on the Chef Infra Server.
Syntax
The syntax for using the chef_container resource in a recipe is as follows:
chef_container 'name' do
attribute 'value' # see properties section below
...
action :action # see actions section below
end
where:
chef_container
tells Chef Infra Client to use theChef::Provider::ChefContainer
provider during a Chef Infra Client runname
is the name of the resource blockattribute
is zero (or more) of the properties that are available for this resourceaction
identifies which steps Chef Infra Client will take to bring the node into the desired state
Actions
The chef_container resource has the following actions:
:create
- (default)
:delete
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The chef_container resource has the following properties:
chef_server
The URL for the Chef Infra Server.
ignore_failure
- Ruby Type: true, false | Default Value:
false
Continue running a recipe if a resource fails for any reason.
name
The name of the container.
notifies
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
notifies
is:notifies :action, 'resource[name]', :timer
subscribes
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may listen to another resource, and then take action if the state of the resource being listened to changes. Specify a
'resource[name]'
, the:action
to be taken, and then the:timer
for that action.Note that
subscribes
does not apply the specified action to the resource that it listens to - for example:file '/etc/nginx/ssl/example.crt' do mode '0600' owner 'root' end service 'nginx' do subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately end
In this case the
subscribes
property reloads thenginx
service whenever its certificate file, located under/etc/nginx/ssl/example.crt
, is updated.subscribes
does not make any changes to the certificate file itself, it merely listens for a change to the file, and executes the:reload
action for its resource (in this examplenginx
) when a change is detected.If the other resource does not exist, the subscription will not raise an error. Contrast this with the stricter semantics of
notifies
, which will raise an error if the other resource does not exist.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
subscribes
is:subscribes :action, 'resource[name]', :timer
Examples
This resource does not have any examples.
chef_data_bag resource
chef_data_bag resource pageData bags store global variables as JSON data. Data bags are indexed for searching and can be loaded by a cookbook or accessed during a search.
Use the chef_data_bag resource to manage data bags.
Syntax
The syntax for using the chef_data_bag resource in a recipe is as follows:
chef_data_bag 'name' do
attribute 'value' # see properties section below
...
action :action # see actions section below
end
where:
chef_data_bag
tells Chef Infra Client to use theChef::Provider::ChefDataBag
provider during a Chef Infra Client runname
is the name of the resource block and also the name of the data bagattribute
is zero (or more) of the properties that are available for this resourceaction
identifies which steps Chef Infra Client will take to bring the node into the desired state
Actions
The chef_data_bag resource has the following actions:
:create
- (default) Use to create a data bag.
:delete
- Use to delete a data bag.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The chef_data_bag resource has the following properties:
chef_server
The URL for the Chef Infra Server.
ignore_failure
- Ruby Type: true, false | Default Value:
false
Continue running a recipe if a resource fails for any reason.
name
The name of the data bag.
notifies
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
notifies
is:notifies :action, 'resource[name]', :timer
subscribes
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may listen to another resource, and then take action if the state of the resource being listened to changes. Specify a
'resource[name]'
, the:action
to be taken, and then the:timer
for that action.Note that
subscribes
does not apply the specified action to the resource that it listens to - for example:file '/etc/nginx/ssl/example.crt' do mode '0600' owner 'root' end service 'nginx' do subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately end
In this case the
subscribes
property reloads thenginx
service whenever its certificate file, located under/etc/nginx/ssl/example.crt
, is updated.subscribes
does not make any changes to the certificate file itself, it merely listens for a change to the file, and executes the:reload
action for its resource (in this examplenginx
) when a change is detected.If the other resource does not exist, the subscription will not raise an error. Contrast this with the stricter semantics of
notifies
, which will raise an error if the other resource does not exist.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
subscribes
is:subscribes :action, 'resource[name]', :timer
Examples
This resource does not have any examples.
chef_data_bag_item resource
chef_data_bag_item resource pageA data bag is a container of related data bag items, where each
individual data bag item is a JSON file. knife can load a data bag item
by specifying the name of the data bag to which the item belongs and
then the filename of the data bag item. The only structural requirement
of a data bag item is that it must have an id
:
{
/* This is a supported comment style */
// This style is also supported
"id": "ITEM_NAME",
"key": "value"
}
where
key
andvalue
are thekey:value
pair for each additional attribute within the data bag item/* ... */
and// ...
show two ways to add comments to the data bag item
Use the chef_data_bag_item resource to manage data bag items.
Syntax
The syntax for using the chef_data_bag_item resource in a recipe is as follows:
chef_data_bag_item 'name' do
attribute 'value' # see properties section below
...
action :action # see actions section below
end
where:
chef_data_bag_item
tells Chef Infra Client to use theChef::Provider::ChefDataBagItem
provider during a Chef Infra Client runname
is the name of the resource block and also the name of the data bag itemattribute
is zero (or more) of the properties that are available for this resourceaction
identifies which steps Chef Infra Client will take to bring the node into the desired state
Actions
The chef_data_bag_item resource has the following actions:
:create
- (default) Use to create a data bag item.
:delete
- Use to delete a data bag item.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The chef_data_bag_item resource has the following properties:
chef_server
The URL for the Chef Infra Server.
complete
Use to specify if this resource defines a data bag item completely. When
true
, any property not specified by this resource will be reset to default property values.
encrypt
Use to specify whether encryption is used for a data bag item.
encryption_version
The minimum required version of data bag encryption. Possible values:
0
,1
,2
, and3
. When all of the machines in an organization are running chef-client version 13.0.113 (or higher), it is recommended that this value be set to3
.
ignore_failure
- Ruby Type: true, false | Default Value:
false
Continue running a recipe if a resource fails for any reason.
notifies
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
notifies
is:notifies :action, 'resource[name]', :timer
raw_data
Use to create a data bag from a local file from
./data_bags/bag_name/file
.
raw_json
The data bag item as JSON data. For example:
{ "id": "adam", "real_name": "Adam Brent Jacob" }
subscribes
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may listen to another resource, and then take action if the state of the resource being listened to changes. Specify a
'resource[name]'
, the:action
to be taken, and then the:timer
for that action.Note that
subscribes
does not apply the specified action to the resource that it listens to - for example:file '/etc/nginx/ssl/example.crt' do mode '0600' owner 'root' end service 'nginx' do subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately end
In this case the
subscribes
property reloads thenginx
service whenever its certificate file, located under/etc/nginx/ssl/example.crt
, is updated.subscribes
does not make any changes to the certificate file itself, it merely listens for a change to the file, and executes the:reload
action for its resource (in this examplenginx
) when a change is detected.If the other resource does not exist, the subscription will not raise an error. Contrast this with the stricter semantics of
notifies
, which will raise an error if the other resource does not exist.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
subscribes
is:subscribes :action, 'resource[name]', :timer
Examples
This resource does not have any examples.
chef_environment resource
chef_environment resource pageAn environment is a way to map an organization’s real-life workflow to what can be configured and managed when using Chef Infra. This mapping is accomplished by setting attributes and pinning cookbooks at the environment level. With environments, you can change cookbook configurations depending on the system’s designation. For example, by designating different staging and production environments, you can then define the correct URL of a database server for each environment. Environments also allow organizations to move new cookbook releases from staging to production with confidence by stepping releases through testing environments before entering production.
Use the chef_environment resource to manage environments.
Syntax
The syntax for using the chef_environment resource in a recipe is as follows:
chef_environment 'name' do
attribute 'value' # see properties section below
...
action :action # see actions section below
end
where:
chef_environment
tells Chef Infra Client to use theChef::Provider::ChefEnvironment
provider during a Chef Infra Client runname
is the name of the resource block; when thename
property is not specified as part of a recipe,name
is also the name of the environmentattribute
is zero (or more) of the properties that are available for this resourceaction
identifies which steps Chef Infra Client will take to bring the node into the desired state
Actions
The chef_environment resource has the following actions:
:create
- (default) Use to create an environment.
:delete
- Use to delete an environment.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The chef_environment resource has the following properties:
chef_server
The URL for the Chef Infra Server.
complete
Use to specify if this resource defines an environment completely. When
true
, any property not specified by this resource will be reset to default property values.
cookbook_versions
The cookbook versions used with the environment. Default value:
{}
.
default_attributes
A
default
attribute is automatically reset at the start of every Chef Infra Client run and has the lowest attribute precedence. Usedefault
attributes as often as possible in cookbooks.Default value:
{}
.
description
The description of the environment. This value populates the description field for the environment on the Chef Infra Server.
ignore_failure
- Ruby Type: true, false | Default Value:
false
Continue running a recipe if a resource fails for any reason.
name
The name of the environment.
notifies
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
notifies
is:notifies :action, 'resource[name]', :timer
override_attributes
An
override
attribute is automatically reset at the start of every Chef Infra Client run and has a higher attribute precedence thandefault
,force_default
, andnormal
attributes. Anoverride
attribute is most often specified in a recipe, but can be specified in an attribute file, for a role, and/or for an environment. A cookbook should be authored so that it usesoverride
attributes only when required.Default value:
{}
.
raw_json
The environment as JSON data. For example:
{ "name":"backend", "description":"", "cookbook_versions":{}, "json_class":"Chef::Environment", "chef_type":"environment", "default_attributes":{}, "override_attributes":{} }
subscribes
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may listen to another resource, and then take action if the state of the resource being listened to changes. Specify a
'resource[name]'
, the:action
to be taken, and then the:timer
for that action.Note that
subscribes
does not apply the specified action to the resource that it listens to - for example:file '/etc/nginx/ssl/example.crt' do mode '0600' owner 'root' end service 'nginx' do subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately end
In this case the
subscribes
property reloads thenginx
service whenever its certificate file, located under/etc/nginx/ssl/example.crt
, is updated.subscribes
does not make any changes to the certificate file itself, it merely listens for a change to the file, and executes the:reload
action for its resource (in this examplenginx
) when a change is detected.If the other resource does not exist, the subscription will not raise an error. Contrast this with the stricter semantics of
notifies
, which will raise an error if the other resource does not exist.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
subscribes
is:subscribes :action, 'resource[name]', :timer
Examples
This resource does not have any examples.
chef_gem resource
chef_gem resource pageUse the chef_gem resource to install a gem only for the instance of Ruby that is dedicated to the Chef Infra Client. When a gem is installed from a local file, it must be added to the node using the remote_file or cookbook_file resources.
The chef_gem resource works with all of the same properties and options as the gem_package resource, but does not
accept the gem_binary
property because it always uses the CurrentGemEnvironment
under which the chef-client
is
running. In addition to performing actions similar to the gem_package resource, the chef_gem resource does the
following:
- Runs its actions immediately, before convergence, allowing a gem to be used in a recipe immediately after it is installed.
- Runs
Gem.clear_paths
after the action, ensuring that gem is aware of changes so that it can be required immediately after it is installed.
Warning
The chef_gem and gem_package resources are both used to install Ruby gems. For any machine on which Chef Infra Client is installed, there are two instances of Ruby. One is the standard, system-wide instance of Ruby and the other is a dedicated instance that is available only to Chef Infra Client. Use the chef_gem resource to install gems into the instance of Ruby that is dedicated to Chef Infra Client. Use the gem_package resource to install all other gems (i.e. install gems system-wide).
Syntax
The full syntax for all of the properties that are available to the chef_gem resource is:
chef_gem 'name' do
clear_sources true, false
gem_binary String
include_default_source true, false
options String, Hash, Array
package_name String
source String, Array
timeout String, Integer
version String
action Symbol # defaults to :install if not specified
end
where:
chef_gem
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.clear_sources
,gem_binary
,include_default_source
,options
,package_name
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The chef_gem resource has the following actions:
:install
- Install a gem. If a version is specified, install the specified version of the gem. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:purge
- Purge a gem. This action typically removes the configuration files as well as the gem.
:reconfig
- Reconfigure a gem. This action requires a response file.
:remove
- Remove a gem.
:upgrade
- Install a gem and ensure that a gem is the latest version.
Properties
The chef_gem resource has the following properties:
clear_sources
- Ruby Type: true, false | Default Value:
false unless `clear_gem_sources` set to true in the `client.rb` config.
Set to
true
to download a gem from the path specified by thesource
property (and not from RubyGems).
gem_binary
- Ruby Type: String | Default Value:
The `gem` binary included with Chef Infra Client.
The path of a gem binary to use for the installation. By default, the same version of Ruby that is used by Chef Infra Client will be used.
include_default_source
- Ruby Type: true, false
Set to
false
to not includeChef::Config[:rubygems_url]
in the sources.New in Chef Client 13.0
options
- Ruby Type: String, Hash, Array
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.
package_name
- Ruby Type: String
An optional property to set the package name if it differs from the resource block’s name.
source
- Ruby Type: String, Array
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.
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String
The version of a package to be installed or upgraded.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the chef_gem resource in recipes:
Compile time vs. converge time installation of gems
To install a gem while Chef Infra Client is configuring the node (the converge phase), set the compile_time
property to false
:
chef_gem 'loofah' do
compile_time false
action :install
end
To install a gem while the resource collection is being built (the compile phase), set the compile_time
property to true
:
chef_gem 'loofah' do
compile_time true
action :install
end
Install MySQL gem into Chef Infra Client*
apt_update
build_essential 'install compilation tools' do
compile_time true
end
chef_gem 'mysql'
chef_group resource
chef_group resource pageUse the chef_group resource to interact with group objects that exist on the Chef server.
Syntax
The syntax for using the chef_group resource in a recipe is as follows:
chef_group 'name' do
attribute 'value' # see properties section below
...
action :action # see actions section below
end
where:
chef_group
tells Chef Infra Client to use theChef::Provider::ChefGroup
provider during a Chef Infra Client runname
is the name of the resource blockattribute
is zero (or more) of the properties that are available for this resourceaction
identifies which steps Chef Infra Client will take to bring the node into the desired state
Actions
The chef_group resource has the following actions:
:create
- (default)
:delete
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The chef_group resource has the following properties:
chef_server
The URL for the Chef server.
clients
…
complete
Use to specify if this resource defines a chef-client completely. When
true
, any property not specified by this resource will be reset to default property values.
groups
…
ignore_failure
- Ruby Type: true, false | Default Value:
false
Continue running a recipe if a resource fails for any reason.
notifies
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
notifies
is:notifies :action, 'resource[name]', :timer
raw_json
The group as JSON data. For example:
{ :groupname => "chef" }
remove_clients
…
remove_groups
…
remove_users
…
subscribes
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may listen to another resource, and then take action if the state of the resource being listened to changes. Specify a
'resource[name]'
, the:action
to be taken, and then the:timer
for that action.Note that
subscribes
does not apply the specified action to the resource that it listens to - for example:file '/etc/nginx/ssl/example.crt' do mode '0600' owner 'root' end service 'nginx' do subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately end
In this case the
subscribes
property reloads thenginx
service whenever its certificate file, located under/etc/nginx/ssl/example.crt
, is updated.subscribes
does not make any changes to the certificate file itself, it merely listens for a change to the file, and executes the:reload
action for its resource (in this examplenginx
) when a change is detected.If the other resource does not exist, the subscription will not raise an error. Contrast this with the stricter semantics of
notifies
, which will raise an error if the other resource does not exist.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
subscribes
is:subscribes :action, 'resource[name]', :timer
users
…
Examples
This resource does not have any examples.
chef_handler resource
chef_handler resource pageUse the chef_handler resource to enable handlers during a Chef Infra Client run. The resource allows arguments to be passed to Chef Infra Client, which then applies the conditions defined by the custom handler to the node attribute data collected during a Chef Infra Client run, and then processes the handler based on that data. The chef_handler resource is typically defined early in a node’s run-list (often being the first item). This ensures that all of the handlers will be available for the entire Chef Infra Client run.
New in Chef Infra Client 14.0.
Handler Types
There are three types of handlers:
- exception
An exception handler is used to identify situations that have caused a Chef Infra Client run to fail. An exception handler can be loaded at the start of a Chef Infra Client run by adding a recipe that contains the chef_handler resource to a node’s run-list. An exception handler runs when the
failed?
property for therun_status
object returnstrue
.- report
A report handler is used when a Chef Infra Client run succeeds and reports back on certain details about that Chef Infra Client run. A report handler can be loaded at the start of a Chef Infra Client run by adding a recipe that contains the chef_handler resource to a node’s run-list. A report handler runs when the
success?
property for therun_status
object returnstrue
.- start
A start handler is used to run events at the beginning of a Chef Infra Client run. A start handler can be loaded at the start of a Chef Infra Client run by adding the start handler to the
start_handlers
setting in the client.rb file or by installing the gem that contains the start handler by using the chef_gem resource in a recipe in the chef-client cookbook. (A start handler may not be loaded using thechef_handler
resource.)
Exception / Report
Exception and report handlers are used to trigger certain behaviors in response to specific situations, typically identified during a Chef Infra Client run.
- An exception handler is used to trigger behaviors when a defined aspect of a Chef Infra Client run fails.
- A report handler is used to trigger behaviors when a defined aspect of a Chef Infra Client run is successful.
Both types of handlers can be used to gather data about a Chef Infra Client run and can provide rich levels of data about all types of usage, which can be used later for trending and analysis across the entire organization.
Exception and report handlers are made available to a Chef Infra Client run in one of the following ways:
- By adding the chef_handler resource to a recipe, and then adding that recipe to the run-list for a node. (The chef_handler resource is available from the chef_handler cookbook.)
- By adding the handler to one of the following settings in the node’s
client.rb file:
exception_handlers
and/orreport_handlers
The chef_handler resource allows exception and report handlers to be enabled from within recipes, which can then added to the run-list for any node on which the exception or report handler should run. The chef_handler resource is available from the chef_handler cookbook.
To use the chef_handler resource in a recipe, add code similar to the following:
chef_handler 'name_of_handler' do
source '/path/to/handler/handler_name'
action :enable
end
For example, a handler for Growl needs to be enabled at the beginning of a Chef Infra Client run:
chef_gem 'chef-handler-growl'
and then is activated in a recipe by using the chef_handler resource:
chef_handler 'Chef::Handler::Growl' do
source 'chef/handler/growl'
action :enable
end
Start
A start handler is not loaded into a Chef Infra Client run from a
recipe, but is instead listed in the client.rb file using the
start_handlers
attribute. The start handler must be installed on the
node and be available to Chef Infra Client before the start of a Chef
Infra Client run. Use the chef-client cookbook to install the start
handler.
Start handlers are made available to a Chef Infra Client run in one of the following ways:
- By adding a start handler to the chef-client cookbook, which installs the handler on the node so that it is available to Chef Infra Client at the start of a Chef Infra Client run
- By adding the handler to one of the following settings in the node’s
client.rb file:
start_handlers
The chef-client cookbook can be configured to automatically install and configure gems that are required by a start handler. For example:
node.override['chef_client']['load_gems']['chef-reporting'] = {
require_name: 'chef_reporting',
action: :install,
}
node.override['chef_client']['config']['start_handlers'] = [
{
class: 'Chef::Reporting::StartHandler',
arguments: [],
},
]
include_recipe 'chef-client::config'
Syntax
A chef_handler resource block enables handlers during a chef-client
run. Two handlers—JsonFile
and ErrorReport
—are built into Chef:
chef_handler 'Chef::Handler::JsonFile' do
source 'chef/handler/json_file'
arguments :path => '/var/chef/reports'
action :enable
end
and:
chef_handler 'Chef::Handler::ErrorReport' do
source 'chef/handler/error_report'
action :enable
end
show how to enable those handlers in a recipe.
The full syntax for all of the properties that are available to the chef_handler resource is:
chef_handler 'name' do
arguments Array, Hash # default value: []
class_name String # default value: 'name' unless specified
source String
type Hash # default value: {"report"=>true, "exception"=>true}
action Symbol # defaults to :enable if not specified
end
where:
chef_handler
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.arguments
,class_name
,source
, andtype
are the properties available to this resource.
Actions
The chef_handler resource has the following actions:
:disable
- Disables the handler for the current Chef Infra Client run on the current node.
:enable
- Enables the handler for the current Chef Infra Client run on the current node. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The chef_handler resource has the following properties:
arguments
- Ruby Type: Array, Hash | Default Value:
[]
An array of arguments that are passed to the initializer for the handler class. For example:
arguments :key1 => ''val1''
or:
arguments [:key1 => ''val1'', :key2 => ''val2'']
class_name
- Ruby Type: String | Default Value:
The resource block's name
The name of the handler class. This can be module name-spaced.
source
- Ruby Type: String
The full path to the handler file. Can also be a gem path if the handler ships as part of a Ruby gem.
type
- Ruby Type: Hash | Default Value:
{"report"=>true, "exception"=>true}
The type of handler to register as, i.e. :report, :exception or both.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the chef_handler resource in recipes:
Enable the ‘MyHandler’ handler
The following example shows how to enable a fictional ‘MyHandler’ handler which is located on disk at /etc/chef/my_handler.rb
. The handler will be configured to run with Chef Infra Client and will be passed values to the handler’s initializer method:
chef_handler 'MyHandler' do
source '/etc/chef/my_handler.rb' # the file should already be at this path
arguments path: '/var/chef/reports'
action :enable
end
Enable handlers during the compile phase
chef_handler 'Chef::Handler::JsonFile' do
source 'chef/handler/json_file'
arguments path: '/var/chef/reports'
action :enable
compile_time true
end
Handle only exceptions
chef_handler 'Chef::Handler::JsonFile' do
source 'chef/handler/json_file'
arguments path: '/var/chef/reports'
type exception: true
action :enable
end
Cookbook Versions (a custom handler)
@juliandunn created a custom report handler that logs all of the cookbooks and cookbook versions that were used during a Chef Infra Client run, and then reports after the run is complete.
cookbook_versions.rb:
The following custom handler defines how cookbooks and cookbook versions that are used during a Chef Infra Client run will be compiled into a report using the Chef::Log
class in Chef Infra Client:
require 'chef/log'
module Chef
class CookbookVersionsHandler < Chef::Handler
def report
cookbooks = run_context.cookbook_collection
Chef::Log.info('Cookbooks and versions run: #{cookbooks.map {|x| x.name.to_s + ' ' + x.version }}')
end
end
end
default.rb:
The following recipe is added to the run-list for every node on which a list of cookbooks and versions will be generated as report output after every Chef Infra Client run.
cookbook_file '/etc/chef/cookbook_versions.rb' do
source 'cookbook_versions.rb'
action :create
end
chef_handler 'Chef::CookbookVersionsHandler' do
source '/etc/chef/cookbook_versions.rb'
type report: true
action :enable
end
This recipe will generate report output similar to the following:
[2013-11-26T03:11:06+00:00] INFO: Chef Infra Client Run complete in 0.300029878 seconds
[2013-11-26T03:11:06+00:00] INFO: Running report handlers
[2013-11-26T03:11:06+00:00] INFO: Cookbooks and versions run: ["cookbook_versions_handler 1.0.0"]
[2013-11-26T03:11:06+00:00] INFO: Report handlers complete
JsonFile Handler
The JsonFile handler is available from the chef_handler
cookbook and can be used with exceptions and reports. It serializes run status data to a JSON file. This handler may be enabled in one of the following ways.
By adding the following lines of Ruby code to either the client.rb file or the solo.rb file, depending on how Chef Infra Client is being run:
require 'chef/handler/json_file'
report_handlers << Chef::Handler::JsonFile.new(path: '/var/chef/reports')
exception_handlers << Chef::Handler::JsonFile.new(path: '/var/chef/reports')
By using the chef_handler
resource in a recipe, similar to the following:
chef_handler 'Chef::Handler::JsonFile' do
source 'chef/handler/json_file'
arguments path: '/var/chef/reports'
action :enable
end
After it has run, the run status data can be loaded and inspected via Interactive Ruby (IRb):
irb(main):002:0> require 'json' => true
irb(main):003:0> require 'chef' => true
irb(main):004:0> r = JSON.parse(IO.read('/var/chef/reports/chef-run-report-20110322060731.json')) => ... output truncated
irb(main):005:0> r.keys => ['end_time', 'node', 'updated_resources', 'exception', 'all_resources', 'success', 'elapsed_time', 'start_time', 'backtrace']
irb(main):006:0> r['elapsed_time'] => 0.00246
Register the JsonFile handler
chef_handler 'Chef::Handler::JsonFile' do
source 'chef/handler/json_file'
arguments path: '/var/chef/reports'
action :enable
end
ErrorReport Handler
The ErrorReport handler is built into Chef Infra Client and can be used for both exceptions and reports. It serializes error report data to a JSON file. This handler may be enabled in one of the following ways.
By adding the following lines of Ruby code to either the client.rb file or the solo.rb file, depending on how Chef Infra Client is being run:
require 'chef/handler/error_report'
report_handlers << Chef::Handler::ErrorReport.new
exception_handlers << Chef::Handler::ErrorReport.new
By using the chef_handler
resource in a recipe, similar to the following:
chef_handler 'Chef::Handler::ErrorReport' do
source 'chef/handler/error_report'
action :enable
end
chef_node resource
chef_node resource pageA node is any device—physical, virtual, cloud, network device, etc.—that is under management by Chef Infra.
Use the chef_node resource to manage nodes.
Syntax
The syntax for using the chef_node resource in a recipe is as follows:
chef_node 'name' do
attribute 'value' # see properties section below
...
action :action # see actions section below
end
where:
chef_node
tells Chef Infra Client to use theChef::Provider::ChefNode
provider during a Chef Infra Client runname
is the name of the resource blockattribute
is zero (or more) of the properties that are available for this resourceaction
identifies which steps Chef Infra Client will take to bring the node into the desired state
Actions
The chef_node resource has the following actions:
:create
- (default) Use to create a node.
:delete
- Use to delete a node.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The chef_node resource has the following properties:
automatic_attributes
An
automatic
attribute contains data that is identified by Ohai at the beginning of every Chef Infra Client run. Anautomatic
attribute cannot be modified and always has the highest attribute precedence.Default value:
{}
.
chef_environment
The Chef Infra Server environment in which this node should exist (or does exist).
chef_server
The URL for the Chef Infra Server.
complete
Use to specify if this resource defines a node completely. When
true
, any property not specified by this resource will be reset to default property values.
default_attributes
A
default
attribute is automatically reset at the start of every Chef Infra Client run and has the lowest attribute precedence. Usedefault
attributes as often as possible in cookbooks.Default value:
{}
.
ignore_failure
- Ruby Type: true, false | Default Value:
false
Continue running a recipe if a resource fails for any reason.
name
The unique identifier of the node.
normal_attributes
A
normal
attribute is a setting that persists in the node object. Anormal
attribute has a higher attribute precedence than adefault
attribute.Default value:
{}
.
notifies
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
notifies
is:notifies :action, 'resource[name]', :timer
override_attributes
An
override
attribute is automatically reset at the start of every Chef Infra Client run and has a higher attribute precedence thandefault
,force_default
, andnormal
attributes. Anoverride
attribute is most often specified in a recipe, but can be specified in an attribute file, for a role, and/or for an environment. A cookbook should be authored so that it usesoverride
attributes only when required.Default value:
{}
.
raw_json
The node as JSON data. For example:
{ "overrides": {}, "name": "latte", "chef_type": "node", "json_class": "Chef::Node", "attributes": { "hardware_type": "laptop" }, "run_list": [ "recipe[apache2]" ], "defaults": {} }
run_list
A comma-separated list of roles and/or recipes to be applied. Default value:
[]
. For example:["recipe[default]","recipe[apache2]"]
subscribes
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may listen to another resource, and then take action if the state of the resource being listened to changes. Specify a
'resource[name]'
, the:action
to be taken, and then the:timer
for that action.Note that
subscribes
does not apply the specified action to the resource that it listens to - for example:file '/etc/nginx/ssl/example.crt' do mode '0600' owner 'root' end service 'nginx' do subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately end
In this case the
subscribes
property reloads thenginx
service whenever its certificate file, located under/etc/nginx/ssl/example.crt
, is updated.subscribes
does not make any changes to the certificate file itself, it merely listens for a change to the file, and executes the:reload
action for its resource (in this examplenginx
) when a change is detected.If the other resource does not exist, the subscription will not raise an error. Contrast this with the stricter semantics of
notifies
, which will raise an error if the other resource does not exist.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
subscribes
is:subscribes :action, 'resource[name]', :timer
Examples
This resource does not have any examples.
chef_organization resource
chef_organization resource pageUse the chef_organization resource to interact with organization objects that exist on the Chef Infra Server.
Syntax
The syntax for using the chef_organization resource in a recipe is as follows:
chef_organization 'name' do
attribute 'value' # see attributes section below
...
action :action # see actions section below
end
where:
chef_organization
tells Chef Infra Client to use theChef::Provider::ChefOrganization
provider during a Chef Infra Client runname
is the name of the resource blockattribute
is zero (or more) of the attributes that are available for this resourceaction
identifies which steps Chef Infra Client will take to bring the node into the desired state
Actions
The chef_organization resource has the following actions:
:create
- (default)
:delete
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The chef_organization resource has the following properties:
chef_server
The URL for the Chef Infra Server.
complete
Use to specify if this resource defines an organization completely. When
true
, any property not specified by this resource will be reset to default property values.
full_name
The full name must begin with a non-white space character and must be between 1 and 1023 characters. For example:
Chef Software, Inc.
.
ignore_failure
- Ruby Type: true, false | Default Value:
false
Continue running a recipe if a resource fails for any reason.
invites
Use to specify a list of users to be invited to the organization. An invitation is sent to any user in this list who is not already a member of the organization.
members
Use to specify a list of users who MUST be members of the organization. These users will be added directly to the organization. The user who initiates this operation MUST also have permission to add users to the specified organization.
members_specified
Use to discover if a user is a member of an organization. Will return
true
if the user is a member.
name
The name must begin with a lower-case letter or digit, may only contain lower-case letters, digits, hyphens, and underscores, and must be between 1 and 255 characters. For example:
chef
.
notifies
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
notifies
is:notifies :action, 'resource[name]', :timer
raw_json
The organization as JSON data. For example:
{ "name": "chef", "full_name": "Chef Software, Inc", "guid": "f980d1asdfda0331235s00ff36862 ... }
remove_members
Use to remove the specified users from an organization. Invitations that have not been accepted will be cancelled.
subscribes
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may listen to another resource, and then take action if the state of the resource being listened to changes. Specify a
'resource[name]'
, the:action
to be taken, and then the:timer
for that action.Note that
subscribes
does not apply the specified action to the resource that it listens to - for example:file '/etc/nginx/ssl/example.crt' do mode '0600' owner 'root' end service 'nginx' do subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately end
In this case the
subscribes
property reloads thenginx
service whenever its certificate file, located under/etc/nginx/ssl/example.crt
, is updated.subscribes
does not make any changes to the certificate file itself, it merely listens for a change to the file, and executes the:reload
action for its resource (in this examplenginx
) when a change is detected.If the other resource does not exist, the subscription will not raise an error. Contrast this with the stricter semantics of
notifies
, which will raise an error if the other resource does not exist.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
subscribes
is:subscribes :action, 'resource[name]', :timer
Examples
This resource does not have any examples.
chef_role resource
chef_role resource pageA role is a way to define certain patterns and processes that exist across nodes in an organization as belonging to a single job function. Each role consists of zero (or more) attributes and a run-list. Each node can have zero (or more) roles assigned to it. When a role is run against a node, the configuration details of that node are compared against the attributes of the role, and then the contents of that role’s run-list are applied to the node’s configuration details. When a Chef Infra Client runs, it merges its own attributes and run-lists with those contained within each assigned role.
Use the chef_role resource to manage roles.
Syntax
The syntax for using the chef_role resource in a recipe is as follows:
chef_role 'name' do
attribute 'value' # see properties section below
...
action :action # see actions section below
end
where:
chef_role
tells Chef Infra Client to use theChef::Provider::ChefRole
provider during a Chef Infra Client runname
is the name of the resource block; when thename
property is not specified as part of a recipe,name
is also the name of the roleattribute
is zero (or more) of the properties that are available for this resourceaction
identifies which steps Chef Infra Client will take to bring the node into the desired state
Actions
The chef_role resource has the following actions:
:create
- (default) Use to create a role.
:delete
- Use to delete a role.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The chef_role resource has the following properties:
chef_server
The URL for the Chef Infra Server.
complete
Use to specify if this resource defines a role completely. When
true
, any property not specified by this resource will be reset to default property values.
default_attributes
A
default
attribute is automatically reset at the start of every Chef Infra Client run and has the lowest attribute precedence. Usedefault
attributes as often as possible in cookbooks.Default value:
{}
.
description
The description of the role. This value populates the description field for the role on the Chef Infra Server.
env_run_lists
The environment-specific run-list for a role. Default value:
[]
. For example:["env_run_lists[webserver]"]
ignore_failure
- Ruby Type: true, false | Default Value:
false
Continue running a recipe if a resource fails for any reason.
name
The name of the role.
notifies
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
notifies
is:notifies :action, 'resource[name]', :timer
override_attributes
An
override
attribute is automatically reset at the start of every Chef Infra Client run and has a higher attribute precedence thandefault
,force_default
, andnormal
attributes. Anoverride
attribute is most often specified in a recipe, but can be specified in an attribute file, for a role, and/or for an environment. A cookbook should be authored so that it usesoverride
attributes only when required.Default value:
{}
.
raw_json
The role as JSON data. For example:
{ "name": "webserver", "chef_type": "role", "json_class": "Chef::Role", "default_attributes": {}, "description": "A webserver", "run_list": [ "recipe[apache2]" ], "override_attributes": {} }
run_list
A comma-separated list of roles and/or recipes to be applied. Default value:
[]
. For example:["recipe[default]","recipe[apache2]"]
subscribes
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may listen to another resource, and then take action if the state of the resource being listened to changes. Specify a
'resource[name]'
, the:action
to be taken, and then the:timer
for that action.Note that
subscribes
does not apply the specified action to the resource that it listens to - for example:file '/etc/nginx/ssl/example.crt' do mode '0600' owner 'root' end service 'nginx' do subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately end
In this case the
subscribes
property reloads thenginx
service whenever its certificate file, located under/etc/nginx/ssl/example.crt
, is updated.subscribes
does not make any changes to the certificate file itself, it merely listens for a change to the file, and executes the:reload
action for its resource (in this examplenginx
) when a change is detected.If the other resource does not exist, the subscription will not raise an error. Contrast this with the stricter semantics of
notifies
, which will raise an error if the other resource does not exist.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
subscribes
is:subscribes :action, 'resource[name]', :timer
Examples
This resource does not have any examples.
chef_sleep resource
chef_sleep resource pageUse the chef_sleep resource to pause (sleep) for a number of seconds during a Chef Infra Client run. Only use this resource when a command or service exits successfully but is not ready for the next step in a recipe.
New in Chef Infra Client 15.5.
Syntax
The full syntax for all of the properties that are available to the chef_sleep resource is:
chef_sleep 'name' do
seconds String, Integer # default value: 'name' unless specified
action Symbol # defaults to :sleep if not specified
end
where:
chef_sleep
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.seconds
is the property available to this resource.
Actions
The chef_sleep resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:sleep
- Pause the Chef Infra Client run for a specified number of seconds. (default)
Properties
The chef_sleep resource has the following properties:
seconds
- Ruby Type: String, Integer | Default Value:
The resource block's name
The number of seconds to sleep.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the chef_sleep resource in recipes:
Sleep for 10 seconds:
chef_sleep '10'
Sleep for 10 seconds with a descriptive resource name for logging:
chef_sleep 'wait for the service to start' do
seconds 10
end
Use a notification from another resource to sleep only when necessary:
service 'Service that is slow to start and reports as started' do
service_name 'my_database'
action :start
notifies :sleep, 'chef_sleep[wait for service start]'
end
chef_sleep 'wait for service start' do
seconds 30
action :nothing
end
chef_user resource
chef_user resource pageUse the chef_user resource to manage users.
Syntax
The syntax for using the chef_user resource in a recipe is as follows:
chef_user 'value' # see properties section below
...
action :action # see actions section below
end
where:
chef_user
tells Chef Infra Client to use theChef::Provider::ChefUser
provider during a Chef Infra Client runname
is the name of the resource block; when thename
property is not specified as part of a recipe,name
is also the name of the userattribute
is zero (or more) of the properties that are available for this resourceaction
identifies which steps Chef Infra Client will take to bring the node into the desired state
Actions
The chef_user resource has the following actions:
:create
- (default) Use to create a user.
:delete
- Use to delete a user.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The chef_user resource has the following properties:
admin
Create a client as an admin client. This is required for any user to access Chef as an administrator.
chef_server
The URL for the Chef Infra Server.
complete
Use to specify if this resource defines a user completely. When
true
, any property not specified by this resource will be reset to default property values.
email
The email address for the user.
external_authentication_uid
…
ignore_failure
- Ruby Type: true, false | Default Value:
false
Continue running a recipe if a resource fails for any reason.
name
The name of the user.
notifies
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
notifies
is:notifies :action, 'resource[name]', :timer
output_key_format
Use to specify the format of a public key. Possible values:
pem
,der
, oropenssh
. Default value:openssh
.
output_key_path
Use to specify the path to the location in which a public key will be written.
raw_json
The user as JSON data. For example:
{ "name": "Robert Forster" }
recovery_authentication_enabled
…
source_key
Use to copy a public or private key, but apply a different
format
andpassword
. Use in conjunction withsource_key_pass_phrase
andsource_key_path
.
source_key_pass_phrase
The pass phrase for the public key. Use in conjunction with
source_key
andsource_key_path
.
source_key_path
The path to the public key. Use in conjunction with
source_key
andsource_key_pass_phrase
.
subscribes
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may listen to another resource, and then take action if the state of the resource being listened to changes. Specify a
'resource[name]'
, the:action
to be taken, and then the:timer
for that action.Note that
subscribes
does not apply the specified action to the resource that it listens to - for example:file '/etc/nginx/ssl/example.crt' do mode '0600' owner 'root' end service 'nginx' do subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately end
In this case the
subscribes
property reloads thenginx
service whenever its certificate file, located under/etc/nginx/ssl/example.crt
, is updated.subscribes
does not make any changes to the certificate file itself, it merely listens for a change to the file, and executes the:reload
action for its resource (in this examplenginx
) when a change is detected.If the other resource does not exist, the subscription will not raise an error. Contrast this with the stricter semantics of
notifies
, which will raise an error if the other resource does not exist.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
subscribes
is:subscribes :action, 'resource[name]', :timer
Examples
This resource does not have any examples.
chef_vault_secret resource
chef_vault_secret resource pageUse the chef_vault_secret resource to store secrets in Chef Vault items. Where possible and relevant, this resource attempts to map behavior and functionality to the knife vault sub-commands.
New in Chef Infra Client 16.0.
Syntax
The full syntax for all of the properties that are available to the chef_vault_secret resource is:
chef_vault_secret 'name' do
admins String, Array
clients String, Array
data_bag String
environment String
id String # default value: 'name' unless specified
raw_data Hash, Mash (Hash-like) # default value: {}
search String # default value: "*:*"
action Symbol # defaults to :create if not specified
end
where:
chef_vault_secret
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.admins
,clients
,data_bag
,environment
,id
,raw_data
, andsearch
are the properties available to this resource.
Actions
The chef_vault_secret resource has the following actions:
:create
- Creates the item, or updates it if it already exists. (default)
:create_if_missing
- Calls the create action unless it exists.
:delete
- Deletes the item and the item’s keys (‘id’_keys).
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The chef_vault_secret resource has the following properties:
admins
- Ruby Type: String, Array |
REQUIRED
A list of admin users who should have access to the item. Corresponds to the ‘admin’ option when using the chef-vault knife plugin. Can be specified as a comma separated string or an array.
clients
- Ruby Type: String, Array
A search query for the nodes’ API clients that should have access to the item.
data_bag
- Ruby Type: String |
REQUIRED
The data bag that contains the item.
environment
- Ruby Type: String
The Chef environment of the data if storing per environment values.
id
- Ruby Type: String | Default Value:
The resource block's name
The name of the data bag item if it differs from the name of the resource block
raw_data
- Ruby Type: Hash, Mash (Hash-like) | Default Value:
{}
The raw data, as a Ruby Hash, that will be stored in the item.
search
- Ruby Type: String | Default Value:
*:*
Search query that would match the same used for the clients, gets stored as a field in the item.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the chef_vault_secret resource in recipes:
To create a ‘foo’ item in an existing ‘bar’ data bag:
chef_vault_secret 'foo' do
data_bag 'bar'
raw_data({ 'auth' => 'baz' })
admins 'jtimberman'
search '*:*'
end
To allow multiple admins access to an item:
chef_vault_secret 'root-password' do
admins 'jtimberman,paulmooring'
data_bag 'secrets'
raw_data({ 'auth' => 'DoNotUseThisPasswordForRoot' })
search '*:*'
end
chocolatey_config resource
chocolatey_config resource pageUse the chocolatey_config resource to add or remove Chocolatey configuration keys.
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 to your node’s run list.
New in Chef Infra Client 14.3.
Syntax
The full syntax for all of the properties that are available to the chocolatey_config resource is:
chocolatey_config 'name' do
config_key String # default value: 'name' unless specified
value String
action Symbol # defaults to :set if not specified
end
where:
chocolatey_config
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.config_key
andvalue
are the properties available to this resource.
Actions
The chocolatey_config resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:set
- Sets a Chocolatey config value. (default)
:unset
- Unsets a Chocolatey config value.
Properties
The chocolatey_config resource has the following properties:
config_key
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the config key name if it differs from the resource block’s name.
value
- Ruby Type: String
The value to set.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the chocolatey_config resource in recipes:
Set the Chocolatey cacheLocation config:
chocolatey_config 'Set cacheLocation config' do
config_key 'cacheLocation'
value 'C:\temp\choco'
end
Unset a Chocolatey config:
chocolatey_config 'BogusConfig' do
action :unset
end
chocolatey_feature resource
chocolatey_feature resource pageUse the chocolatey_feature resource to enable and disable Chocolatey features.
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 to your node’s run list.
New in Chef Infra Client 15.1.
Syntax
The full syntax for all of the properties that are available to the chocolatey_feature resource is:
chocolatey_feature 'name' do
feature_name String # default value: 'name' unless specified
action Symbol # defaults to :enable if not specified
end
where:
chocolatey_feature
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.feature_name
is the property available to this resource.
Actions
The chocolatey_feature resource has the following actions:
:disable
- Disables a named Chocolatey feature.
:enable
- Enables a named Chocolatey feature. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The chocolatey_feature resource has the following properties:
feature_name
- Ruby Type: String | Default Value:
The resource block's name
The name of the Chocolatey feature to enable or disable.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the chocolatey_feature resource in recipes:
Enable the checksumFiles Chocolatey feature
chocolatey_feature 'checksumFiles' do
action :enable
end
Disable the checksumFiles Chocolatey feature
chocolatey_feature 'checksumFiles' do
action :disable
end
chocolatey_installer resource
chocolatey_installer resource pageUse the chocolatey_installer resource to install the Chocolatey package manager. Use the chocolatey_feature resource to customize your install and the chocolatey_package resource to install packages.
New in Chef Infra Client 18.4.
Syntax
The full syntax for all of the properties that are available to the chocolatey_installer resource is:
chocolatey_installer 'name' do
chocolatey_version String
download_url String
ignore_proxy true, false # default value: false
proxy_password String
proxy_url String
proxy_user String
use_native_unzip true, false # default value: false
action Symbol # defaults to :install if not specified
end
where:
chocolatey_installer
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.chocolatey_version
,download_url
,ignore_proxy
,proxy_password
,proxy_url
,proxy_user
, anduse_native_unzip
are the properties available to this resource.
Actions
The chocolatey_installer resource has the following actions:
:install
- Installs Chocolatey package manager (default).
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:uninstall
- Uninstall Chocolatey package manager.
:upgrade
- Upgrades the Chocolatey package manager.
Properties
The chocolatey_installer resource has the following properties:
chocolatey_version
- Ruby Type: String
Specifies a target version of Chocolatey to install. By default, the latest stable version is installed. This will use the value in
$env:ChocolateyVersion
by default if that environment variable is present. This parameter is ignored if you setdownload_url
.
download_url
- Ruby Type: String
The URL to download Chocolatey from. This sets the value of
$env:ChocolateyDownloadUrl
and causes the installer to choose an alternate download location. If this is not set, this resource downloads Chocolatey from the official Chocolatey community repository. You can set a path to achocolatey.nupkg
file for offline installation.
ignore_proxy
- Ruby Type: true, false | Default Value:
false
If set, this overrides any configured proxy, proxy environment variables, or parameters. This is enabled if set to a value other than ‘false’ or ‘0’.
proxy_password
- Ruby Type: String
The password used to connect to the proxy server with. If set, you must also set
proxy_user
.
proxy_url
- Ruby Type: String
Specifies the proxy URL to use during the download.
proxy_user
- Ruby Type: String
The username used to connect to the proxy server with. If set, you must also set
proxy_password
.
use_native_unzip
- Ruby Type: true, false | Default Value:
false
If
true
, this resource uses built-in Windows decompression tools instead of 7zip when unpacking the downloaded NuPkg file. This parameter is ignored in PowerShell 5+ in favour of using theExpand-Archive
built-in PowerShell cmdlet directly.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the chocolatey_installer resource in recipes:
Install Chocolatey
chocolatey_installer 'latest' do
action :install
end
Uninstall Chocolatey
chocolatey_installer 'Some random verbiage' do
action :uninstall
end
Install Chocolatey with Parameters
chocolatey_installer 'latest' do
action :install
download_url "https://www.contoso.com/foo"
chocolatey_version '2.12.24'
end
chocolatey_installer 'latest' do
action :install
download_url "c:\foooo.nupkg"
chocolatey_version '2.12.24'
end
Upgrade Chocolatey with Parameters
chocolatey_installer 'latest' do
action :upgrade
chocolatey_version '2.12.24'
end
chocolatey_package resource
chocolatey_package resource pageUse 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 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.
New in Chef Infra Client 12.7.
Syntax
The full syntax for all of the properties that are available to the chocolatey_package resource is:
chocolatey_package 'name' do
bulk_query true, false # default value: false
list_options String
options String, Array
package_name String, Array
password String
returns Integer, Array # default value: [0, 2]
source String
timeout String, Integer
use_choco_list true, false # default value: false
user String
version String, Array
action Symbol # defaults to :install if not specified
end
where:
chocolatey_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.bulk_query
,list_options
,options
,package_name
,password
,returns
,source
,timeout
,use_choco_list
,user
, andversion
are the properties available to this resource.
Actions
The chocolatey_package resource has the following actions:
:install
- Install a package. If a version is specified, install the specified version of the package. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:purge
- Purge a package. This action typically removes the configuration files as well as the package.
:remove
- Remove a package.
:upgrade
- Install a package and ensure that a package is the latest version.
Properties
The chocolatey_package resource has the following properties:
bulk_query
- Ruby Type: true, false | Default Value:
false
Whether to bulk query the Chocolatey server. This makes the provider list all packages instead of doing individual queries.
list_options
- Ruby Type: String
One (or more) additional list options that are passed to the command.
New in Chef Infra Client 15.3
options
- Ruby Type: String, Array
One (or more) additional options that are passed to the command.
package_name
- Ruby Type: String, Array
The name of the package. Default value: the name of the resource block.
password
- Ruby Type: String
The password to authenticate to the source.
New in Chef Infra Client 15.3
returns
- Ruby Type: Integer, Array | Default Value:
[0, 2]
The exit code(s) returned by the
choco
command that indicate a successful action. See Chocolatey Exit Codes for a complete list of exit codes used by Chocolatey.New in Chef Client 12.18
source
- Ruby Type: String
The optional path to a package on the local file system.
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
use_choco_list
- Ruby Type: true, false | Default Value:
false
Whether to use
choco list
for getting locally installed packages instead of querying for NuGet package files. This defaults tofalse
since reading the package data is faster.
user
- Ruby Type: String
The username to authenticate feeds.
New in Chef Infra Client 15.3
version
- Ruby Type: String, Array
The version of a package to be installed or upgraded.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the chocolatey_package resource in recipes:
Install a Chocolatey package:
chocolatey_package 'name of package' do
action :install
end
Install a package with options with Chocolatey’s --checksum
option:
chocolatey_package 'name of package' do
options '--checksum 1234567890'
action :install
end
chocolatey_source resource
chocolatey_source resource pageUse the chocolatey_source resource to add, remove, enable, or disable Chocolatey sources.
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 to your node’s run list.
New in Chef Infra Client 14.3.
Syntax
The full syntax for all of the properties that are available to the chocolatey_source resource is:
chocolatey_source 'name' do
admin_only true, false # default value: false
allow_self_service true, false # default value: false
bypass_proxy true, false # default value: false
cert String
cert_password String
password String
priority Integer # default value: 0
source String
source_name String # default value: 'name' unless specified
username String
action Symbol # defaults to :add if not specified
end
where:
chocolatey_source
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.admin_only
,allow_self_service
,bypass_proxy
,cert
,cert_password
,password
,priority
,source
,source_name
, andusername
are the properties available to this resource.
Actions
The chocolatey_source resource has the following actions:
:add
- Adds a Chocolatey source (default)
:disable
- Disables a Chocolatey source. New in Chef Infra Client 15.1.
:enable
- Enables a Chocolatey source. New in Chef Infra Client 15.1.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Removes a Chocolatey source.
Properties
The chocolatey_source resource has the following properties:
admin_only
- Ruby Type: true, false | Default Value:
false
Whether or not to set the source to be accessible to only admins.
New in Chef Infra Client 15.1
allow_self_service
- Ruby Type: true, false | Default Value:
false
Whether or not to set the source to be used for self service.
New in Chef Infra Client 15.1
bypass_proxy
- Ruby Type: true, false | Default Value:
false
Whether or not to bypass the system’s proxy settings to access the source.
cert
- Ruby Type: String
The certificate to use when authenticating against the source
New in Chef Infra Client 17.7
cert_password
- Ruby Type: String
The password for the certificate to use when authenticating against the source
New in Chef Infra Client 17.7
password
- Ruby Type: String
The password to use when authenticating against the source
New in Chef Infra Client 17.7
priority
- Ruby Type: Integer | Default Value:
0
The priority level of the source.
source
- Ruby Type: String
The source URL.
source_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the source name if it differs from the resource block’s name.
username
- Ruby Type: String
The username to use when authenticating against the source
New in Chef Infra Client 17.7
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the chocolatey_source resource in recipes:
Add a Chocolatey source
chocolatey_source 'MySource' do
source 'http://example.com/something'
action :add
end
Remove a Chocolatey source
chocolatey_source 'MySource' do
action :remove
end
cookbook_file resource
cookbook_file resource pageUse the cookbook_file resource to transfer files from a
sub-directory of COOKBOOK_NAME/files/
to a specified path located on a
host that is running Chef Infra Client. The file is selected according
to file specificity, which allows different source files to be used
based on the hostname, host platform (operating system, distro, or as
appropriate), or platform version. Files that are located in the
COOKBOOK_NAME/files/default
sub-directory may be used on any platform.
During a Chef Infra Client run, the checksum for each local file is calculated and then compared against the checksum for the same file as it currently exists in the cookbook on the Chef Infra Server. A file isn’t transferred when the checksums match. Only files that require an update are transferred from the Chef Infra Server to a node.
Syntax
A cookbook_file resource block manages files by using files that
exist within a cookbook’s /files
directory. For example, to write the
home page for an Apache website:
cookbook_file '/var/www/customers/public_html/index.php' do
source 'index.php'
owner 'web_admin'
group 'web_admin'
mode '0755'
action :create
end
where:
'/var/www/customers/public_html/index.php'
is path to the file to be created'index.php'
is a file in the/files
directory in a cookbook that is used to create that file (the contents of the file in the cookbook will become the contents of the file on the node)owner
,group
, andmode
define the permissions
The full syntax for all of the properties that are available to the cookbook_file resource is:
cookbook_file 'name' do
atomic_update true, false
backup Integer, false # default value: 5
cookbook String
force_unlink true, false # default value: false
group String, Integer
inherits true, false
manage_symlink_source true, false
mode String, Integer
owner String, Integer
path String # default value: 'name' unless specified
rights Hash
source String, Array
verify String, Block
action Symbol # defaults to :create if not specified
end
where:
cookbook_file
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.atomic_update
,backup
,checksum
,content
,cookbook
,deny_rights
,force_unlink
,manage_symlink_source
,path
,rights
, andsource
are the properties available to this resource.
Actions
The cookbook_file resource has the following actions:
:create
- (default) Create a file. If a file already exists (but does not match), update that file to match.
:create_if_missing
- Create a file only if the file does not exist. When the file exists, nothing happens.
:delete
- Delete a file.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:touch
- Touch a file. This updates the access (atime) and file modification
Properties
The cookbook_file resource has the following properties:
atomic_update
- Ruby Type: true, false | Default Value:
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.
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 theclient.rb
file.
backup
- Ruby Type: Integer, false | Default Value:
5
The number of backups to be kept in
/var/chef/backup
(for UNIX- and Linux-based platforms) orC:/chef/backup
(for the Microsoft Windows platform). Set tofalse
to prevent backups from being kept.
cookbook
- Ruby Type: String | Default Value:
The current cookbook name
The cookbook in which a file is located (if it is not located in the current cookbook).
force_unlink
- Ruby Type: true, false | Default Value:
false
How Chef Infra 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 Chef Infra Client to delete the non-file target and replace it with the specified file. Set tofalse
for Chef Infra Client to raise an error.
group
- Ruby Type: Integer, String
A string or ID that identifies the group owner by group name or SID, including fully qualified group names such as
domain\group
orgroup@domain
. If this value is not specified, existing groups remain unchanged and new group assignments use the defaultPOSIX
group (if available).
inherits
- Ruby Type: true, false | Default Value:
true
Microsoft Windows only. Whether a file inherits rights from its parent directory.
manage_symlink_source
- Ruby Type: true, false | Default Value:
true
(with warning) Change the behavior of the file resource if it is pointed at a symlink. When this value is set to
true
, Chef Infra 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 tofalse
, Chef Infra Client will follow the symlink and will manage the permissions and content of symlink’s target file. The default behavior istrue
, but emits a warning that the default value will be changed tofalse
in a future version; setting this explicitly totrue
orfalse
suppresses this warning.
mode
- Ruby Type: Integer, String
If
mode
is not specified and if the file already exists, the existing mode on the file is used. Ifmode
is not specified, the file does not exist, and the:create
action is specified, Chef Infra Client assumes a mask value of'0777'
and then applies the umask for the system on which the file is to be created to themask
value. For example, if the umask on a system is'022'
, Chef Infra Client uses the default value of'0755'
.The behavior is different depending on the platform.
UNIX- and Linux-based systems: A quoted 3-5 character string that defines the octal mode that is passed to chmod. For example:
'755'
,'0755'
, or00755
. If the value is specified as a quoted string, it works exactly as if thechmod
command was passed. If the value is specified as an integer, prepend a zero (0
) to the value to ensure that it is interpreted as an octal number. For example, to assign read, write, and execute rights for all users, use'0777'
or'777'
; for the same rights, plus the sticky bit, use01777
or'1777'
.Microsoft Windows: A quoted 3-5 character string that defines the octal mode that is translated into rights for Microsoft Windows security. For example:
'755'
,'0755'
, or00755
. Values up to'0777'
are allowed (no sticky bits) and mean the same in Microsoft Windows as they do in UNIX, where4
equalsGENERIC_READ
,2
equalsGENERIC_WRITE
, and1
equalsGENERIC_EXECUTE
. This property cannot be used to set:full_control
. This property has no effect if not specified, but when it andrights
are both specified, the effects are cumulative.
owner
- Ruby Type: Integer, String
A string or ID that identifies the group owner by user name or SID, including fully qualified user names such as
domain\user
oruser@domain
. If this value is not specified, existing owners remain unchanged and new owner assignments use the current user (when necessary).
path
- Ruby Type: String | Default Value:
The resource block's name
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 Infra Client process. This path can vary from system to system. Therefore, using a path that begins with a forward slash/
is not recommended.
rights
- Ruby Type: Integer, String
Microsoft Windows only. The permissions for users and groups in a Microsoft Windows environment. For example:
rights <permissions>, <principal>, <options>
where<permissions>
specifies the rights granted to the principal,<principal>
is the group or user name, and<options>
is a Hash with one (or more) advanced rights options.
source
- Ruby Type: String, Array | Default Value:
The resource block's name.
The name of the file in
COOKBOOK_NAME/files/default
or the path to a file located inCOOKBOOK_NAME/files
. The path must include the file name and its extension. This can be used to distribute specific files depending upon files depending upon the platform used - see File Specificity for more information.'
verify
- Ruby Type: String, Block
A block or a string that returns
true
orfalse
. A string, whentrue
is executed as a system command.A block is arbitrary Ruby defined within the resource block by using the
verify
property. When a block istrue
, Chef Infra Client will continue to update the file as appropriate.For example, this should return
true
:cookbook_file '/tmp/baz' do verify { 1 == 1 } end
This should return
true
:cookbook_file '/etc/nginx.conf' do verify 'nginx -t -c %{path}' end
This should return
true
:cookbook_file '/tmp/bar' do verify { 1 == 1} end
And this should return
true
:cookbook_file '/tmp/foo' do verify do |path| true end end
Whereas, this should return
false
:cookbook_file '/tmp/turtle' do verify '/usr/bin/false' end
If a string or a block return
false
, the Chef Infra Client run will stop and an error is returned.
Atomic File Updates
Atomic updates are used with file-based resources to help ensure that file updates can be made when updating a binary or if disk space runs out.
Atomic updates are enabled by default. They can be managed globally
using the file_atomic_update
setting in the client.rb
file. They can
be managed for each resource using the atomic_update
property
that is available with the cookbook_file, file,
remote_file, and template resources.
Note
On certain platforms, and after a file has been moved into place, Chef
Infra Client may modify file permissions to support features specific to
those platforms. On platforms with SELinux enabled, Chef Infra Client
will fix up the security contexts after a file has been moved into the
correct location by running the restorecon
command. On the Microsoft
Windows platform, Chef Infra Client will create files so that ACL
inheritance works as expected.
Windows File Security
To support Windows security, the template, file, remote_file, cookbook_file, directory, and remote_directory resources support the use of inheritance and access control lists (ACLs) within recipes. Access Control Lists (ACLs)The rights
property can be used in a recipe to manage access control
lists (ACLs), which allow permissions to be given to multiple users and
groups. Use the rights
property can be used as many times as
necessary; Chef Infra Client will apply them to the file or directory as
required. The syntax for the rights
property is as follows:
rights permission, principal, option_type => value
where
permission
Use to specify which rights are granted to the
principal
. The possible values are::read
,:write
,read_execute
,:modify
,:full_control
, or an integer.Integers used for permissions must match the following list FileSystemRights Enum fields.
These permissions are cumulative. If
:write
is specified, then it includes:read
. If:full_control
is specified, then it includes both:write
and:read
.(For those who know the Windows API:
:read
corresponds toGENERIC_READ
;:write
corresponds toGENERIC_WRITE
;:read_execute
corresponds toGENERIC_READ
andGENERIC_EXECUTE
;:modify
corresponds toGENERIC_WRITE
,GENERIC_READ
,GENERIC_EXECUTE
, andDELETE
;:full_control
corresponds toGENERIC_ALL
, which allows a user to change the owner and other metadata about a file.)principal
Use to specify a group or user. The principal can be specified by either name or SID. When using name, this is identical to what is entered in the login box for Windows, such as
user_name
,domain\user_name
, oruser_name@fully_qualified_domain_name
. When using a SID, you may use either the standard string representation of a SID (S-R-I-S-S) or one of the SDDL string constants. Chef Infra Client does not need to know if a principal is a user or a group.option_type
A hash that contains advanced rights options. For example, the rights to a directory that only applies to the first level of children might look something like:
rights :write, 'domain\group_name', :one_level_deep => true
.Possible option types:
:applies_to_children
Specify how permissions are applied to children. Possible values:
true
to inherit both child directories and files;false
to not inherit any child directories or files;:containers_only
to inherit only child directories (and not files);:objects_only
to recursively inherit files (and not child directories).:applies_to_self
Indicates whether a permission is applied to the parent directory. Possible values:
true
to apply to the parent directory or file and its children;false
to not apply only to child directories and files.:one_level_deep
Indicates the depth to which permissions will be applied. Possible values:
true
to apply only to the first level of children;false
to apply to all children.
For example:
resource 'x.txt' do
rights :read, 'S-1-1-0'
rights :write, 'domain\group'
rights :full_control, 'group_name_or_user_name'
rights :full_control, 'user_name', applies_to_children: true
end
or:
rights :read, %w(Administrators Everyone)
rights :full_control, 'Users', applies_to_children: true
rights :write, 'Sally', applies_to_children: :containers_only, applies_to_self: false, one_level_deep: true
Some other important things to know when using the rights
attribute:
- Only inherited rights remain. All existing explicit rights on the object are removed and replaced.
- If rights are not specified, nothing will be changed. Chef Infra Client does not clear out the rights on a file or directory if rights are not specified.
- Changing inherited rights can be expensive. Windows will propagate rights to all children recursively due to inheritance. This is a normal aspect of Windows, so consider the frequency with which this type of action is necessary and take steps to control this type of action if performance is the primary consideration.
Use the deny_rights
property to deny specific rights to specific
users. The ordering is independent of using the rights
property. For
example, it doesn’t matter if rights are granted to everyone is placed
before or after deny_rights :read, ['Julian', 'Lewis']
, both Julian
and Lewis will be unable to read the document. For example:
resource 'x.txt' do
rights :read, 'Everyone'
rights :write, 'domain\group'
rights :full_control, 'group_name_or_user_name'
rights :full_control, 'user_name', applies_to_children: true
deny_rights :read, %w(Julian Lewis)
end
or:
deny_rights :full_control, ['Sally']
By default, a file or directory inherits rights from its parent
directory. Most of the time this is the preferred behavior, but
sometimes it may be necessary to take steps to more specifically control
rights. The inherits
property can be used to specifically tell Chef
Infra Client to apply (or not apply) inherited rights from its parent
directory.
For example, the following example specifies the rights for a directory:
directory 'C:\mordor' do
rights :read, 'MORDOR\Minions'
rights :full_control, 'MORDOR\Sauron'
end
and then the following example specifies how to use inheritance to deny access to the child directory:
directory 'C:\mordor\mount_doom' do
rights :full_control, 'MORDOR\Sauron'
inherits false # Sauron is the only person who should have any sort of access
end
If the deny_rights
permission were to be used instead, something could
slip through unless all users and groups were denied.
Another example also shows how to specify rights for a directory:
directory 'C:\mordor' do
rights :read, 'MORDOR\Minions'
rights :full_control, 'MORDOR\Sauron'
rights :write, 'SHIRE\Frodo' # Who put that there I didn't put that there
end
but then not use the inherits
property to deny those rights on a child
directory:
directory 'C:\mordor\mount_doom' do
deny_rights :read, 'MORDOR\Minions' # Oops, not specific enough
end
Because the inherits
property is not specified, Chef Infra Client will
default it to true
, which will ensure that security settings for
existing files remain unchanged.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
File Specificity
A cookbook is frequently designed to work across many platforms and is often required to distribute a specific file to a specific platform. A cookbook can be designed to support the distribution of files across platforms, while ensuring that the correct file ends up on each system.
The pattern for file specificity depends on two things: the lookup path and the source attribute. The first pattern that matches is used:
/host-\$fqdn/\$source
/\$platform-\$platform_version/\$source
/\$platform/\$source
/default/\$source
/\$source
Use an array with the source
attribute to define an explicit lookup
path. For example:
file '/conf.py' do
source ['#{node.chef_environment}.py', 'conf.py']
end
The following example emulates the entire file specificity pattern by defining it as an explicit path:
file '/conf.py' do
source %W(
host-#{node['fqdn']}/conf.py
#{node['platform']}-#{node['platform_version']}/conf.py
#{node['platform']}/conf.py
default/conf.py
)
end
A cookbook may have a /files
directory structure like this:
files/
host-foo.example.com
ubuntu-20.04
ubuntu-20
ubuntu
redhat-8.2
redhat-7.8
...
default
and a resource that looks something like the following:
cookbook_file '/usr/local/bin/apache2_module_conf_generate.pl' do
source 'apache2_module_conf_generate.pl'
mode '0755'
owner 'root'
group 'root'
end
This resource is matched in the same order as the /files
directory
structure. For a node that is running Ubuntu 20.04, the second item
would be the matching item and the location to which the file identified
in the cookbook_file resource would be distributed:
host-foo.example.com/apache2_module_conf_generate.pl
ubuntu-20.04/apache2_module_conf_generate.pl
ubuntu-20/apache2_module_conf_generate.pl
ubuntu/apache2_module_conf_generate.pl
default/apache2_module_conf_generate.pl
If the apache2_module_conf_generate.pl
file was located in the
cookbook directory under files/host-foo.example.com/
, the specified
file(s) would only be copied to the machine with the domain name
foo.example.com.
Host Notation
The naming of folders within cookbook directories must literally match
the host notation used for file specificity matching. For example, if a
host is named foo.example.com
, the folder must be named
host-foo.example.com
.
Examples
The following examples demonstrate various approaches for using the cookbook_file resource in recipes:
Transfer a file
cookbook_file 'file.txt' do
mode '0755'
end
Handle cookbook_file and package resources in the same recipe
When a cookbook_file resource and a package resource are both
called from within the same recipe, use the flush_cache
attribute to
dump the in-memory Yum cache, and then use the repository immediately to
ensure that the correct package is installed:
cookbook_file '/etc/yum.repos.d/custom.repo' do
source 'custom'
mode '0755'
end
package 'only-in-custom-repo' do
action :install
flush_cache [ :before ]
end
Install repositories from a file, trigger a command, and force the internal cache to reload
The following example shows how to install new Yum repositories from a file, where the installation of the repository triggers a creation of the Yum cache that forces the internal cache for Chef Infra Client to reload:
execute 'create-yum-cache' do
command 'yum -q makecache'
action :nothing
end
ruby_block 'reload-internal-yum-cache' do
block do
Chef::Provider::Package::Yum::YumCache.instance.reload
end
action :nothing
end
cookbook_file '/etc/yum.repos.d/custom.repo' do
source 'custom'
mode '0755'
notifies :run, 'execute[create-yum-cache]', :immediately
notifies :create, 'ruby_block[reload-internal-yum-cache]', :immediately
end
Use a case statement
The following example shows how a case statement can be used to handle a situation where an application needs to be installed on multiple platforms, but where the install directories are different paths, depending on the platform:
cookbook_file 'application.pm' do
path case node['platform']
when 'centos','redhat'
'/usr/lib/version/1.2.3/dir/application.pm'
when 'arch'
'/usr/share/version/core_version/dir/application.pm'
else
'/etc/version/dir/application.pm'
end
source "application-#{node['languages']['perl']['version']}.pm"
owner 'root'
group 'root'
mode '0755'
end
Manage dotfiles
The following example shows using the directory and cookbook_file resources to manage dotfiles. The dotfiles are defined by a JSON data structure similar to:
"files": {
".zshrc": {
"mode": '0755',
"source": "dot-zshrc"
},
".bashrc": {
"mode": '0755',
"source": "dot-bashrc"
},
".bash_profile": {
"mode": '0755',
"source": "dot-bash_profile"
},
}
and then the following resources manage the dotfiles:
if u.has_key?('files')
u['files'].each do |filename, file_data|
directory "#{home_dir}/#{File.dirname(filename)}" do
recursive true
mode '0755'
end if file_data['subdir']
cookbook_file "#{home_dir}/#{filename}" do
source "#{u['id']}/#{file_data['source']}"
owner 'u['id']'
group 'group_id'
mode 'file_data['mode']'
ignore_failure true
backup 0
end
end
cron resource
cron resource pageUse 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 Chef Infra Client 14.4 or later and can also be found in the cron cookbook) for previous Chef Infra Client releases.
Syntax
The full syntax for all of the properties that are available to the cron resource is:
cron 'name' do
command String
day Integer, String # default value: "*"
environment Hash # default value: {}
home String
hour Integer, String # default value: "*"
mailto String
minute Integer, String # default value: "*"
month Integer, String # default value: "*"
path String
shell String
time Symbol
time_out Hash # default value: {}
user String # default value: "root"
weekday Integer, String, Symbol # default value: "*"
action Symbol # defaults to :create if not specified
end
where:
cron
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.command
,day
,environment
,home
,hour
,mailto
,minute
,month
,path
,shell
,time
,time_out
,user
, andweekday
are the properties available to this resource.
Actions
The cron resource has the following actions:
:create
- Create an entry in a cron table file (crontab). If an entry already exists (but does not match), update that entry to match. (default)
:delete
- Delete an entry from a cron table file (crontab).
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The cron resource has the following properties:
command
- Ruby Type: String |
REQUIRED
The command to be run, or the path to a file that contains the command to be run.
day
- Ruby Type: Integer, String | Default Value:
*
The day of month at which the cron entry should run (
1 - 31
).
environment
- Ruby Type: Hash | Default Value:
{}
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.
home
- Ruby Type: String
Set the
HOME
environment variable.
hour
- Ruby Type: Integer, String | Default Value:
*
The hour at which the cron entry is to run (
0 - 23
).
mailto
- Ruby Type: String
Set the
MAILTO
environment variable.
minute
- Ruby Type: Integer, String | Default Value:
*
The minute at which the cron entry should run (
0 - 59
).
month
- Ruby Type: Integer, String | Default Value:
*
The month in the year on which a cron entry is to run (
1 - 12
,jan-dec
, or*
).
path
- Ruby Type: String
Set the
PATH
environment variable.
shell
- Ruby Type: String
Set the
SHELL
environment variable.
time
- Ruby Type: SymbolAllowed Values:
:annually, :daily, :hourly, :midnight, :monthly, :reboot, :weekly, :yearly
A time interval.
time_out
- Ruby Type: Hash | Default Value:
{}
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)
New in Chef Infra Client 15.7
user
- Ruby Type: String | Default Value:
root
The name of the user that runs the command. If the user property is changed, the original user for the crontab program continues to run until that crontab program is deleted. This property is not applicable on the AIX platform.
weekday
- Ruby Type: Integer, String, Symbol | Default Value:
*
The day of the week on which this entry is to run (
0-7
,mon-sun
,monday-sunday
, or*
), where Sunday is both0
and7
.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the cron resource in recipes:
Run a program at a specified interval
cron 'noop' do
hour '5'
minute '0'
command '/bin/true'
end
Run an entry if a folder exists
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.
cron 'name_of_cron_entry' do
minute '0'
hour '8'
weekday '6'
mailto 'admin@example.com'
action :create
end
Run once a week
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:
cron 'name_of_cron_entry' do
minute '0'
hour '20'
day '*'
month '11'
weekday '1-5'
action :create
end
cron_access resource
cron_access resource pageUse 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.
New in Chef Infra Client 14.4.
Syntax
The full syntax for all of the properties that are available to the cron_access resource is:
cron_access 'name' do
user String # default value: 'name' unless specified
action Symbol # defaults to :allow if not specified
end
where:
cron_access
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.user
is the property available to this resource.
Actions
The cron_access resource has the following actions:
:allow
- Add the user to the cron.allow file. (default)
:deny
- Add the user to the cron.deny file.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The cron_access resource has the following properties:
user
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the user name if it differs from the resource block’s name.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the cron_access resource in recipes:
Add the mike user to cron.allow
cron_access 'mike'
Add the mike user to cron.deny
cron_access 'mike' do
action :deny
end
Specify the username with the user property
cron_access 'Deny the jenkins user access to cron for security purposes' do
user 'jenkins'
action :deny
end
cron_d resource
cron_d resource pageUse the cron_d resource to manage cron job files in the /etc/cron.d
directory.
Warning
Chef Infra Client also ships with the cron resource for managing the monolithic /etc/crontab
file on platforms that lack cron.d support. See the cron resource for information on using that resource.
New in Chef Infra Client 14.4.
Syntax
A cron_d resource block manages cron.d files. For example, to get a weekly cookbook report from the Chef Supermarket:
cron_d 'cookbooks_report' do
action :create
minute '0'
hour '0'
weekday '1'
user 'getchef'
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(' ')
end
The full syntax for all of the properties that are available to the cron_d resource is:
cron_d 'name' do
command String
comment String
cron_name String # default value: 'name' unless specified
day Integer, String # default value: "*"
environment Hash # default value: {}
home String
hour Integer, String # default value: "*"
mailto String
minute Integer, String # default value: "*"
mode String, Integer # default value: "0600"
month Integer, String # default value: "*"
path String
predefined_value String
random_delay Integer
shell String
time_out Hash # default value: {}
user String # default value: "root"
weekday Integer, String, Symbol # default value: "*"
action Symbol # defaults to :create if not specified
end
where:
cron_d
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.command
,comment
,cron_name
,day
,environment
,home
,hour
,mailto
,minute
,mode
,month
,path
,predefined_value
,random_delay
,shell
,time_out
,user
, andweekday
are the properties available to this resource.
Actions
The cron_d resource has the following actions:
:create
- (default)
:create_if_missing
- Add a cron definition file to
/etc/cron.d
, but do not update an existing file. :delete
- Remove a cron definition file from
/etc/cron.d
if it exists. :nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The cron_d resource has the following properties:
command
- Ruby Type: String |
REQUIRED
The command to be run, or the path to a file that contains the command to be run.
comment
- Ruby Type: String
A comment to place in the cron.d file.
cron_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the cron name if it differs from the resource block’s name.
day
- Ruby Type: Integer, String | Default Value:
*
The day of month at which the cron entry should run (
1 - 31
).
environment
- Ruby Type: Hash | Default Value:
{}
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.
home
- Ruby Type: String
Set the
HOME
environment variable.
hour
- Ruby Type: Integer, String | Default Value:
*
The hour at which the cron entry is to run (
0 - 23
).
mailto
- Ruby Type: String
Set the
MAILTO
environment variable.
minute
- Ruby Type: Integer, String | Default Value:
*
The minute at which the cron entry should run (
0 - 59
).
mode
- Ruby Type: String, Integer | Default Value:
0600
The octal mode of the generated crontab file.
month
- Ruby Type: Integer, String | Default Value:
*
The month in the year on which a cron entry is to run (
1 - 12
,jan-dec
, or*
).
path
- Ruby Type: String
Set the
PATH
environment variable.
predefined_value
- Ruby Type: StringAllowed Values:
"@annually", "@daily", "@hourly", "@midnight", "@monthly", "@reboot", "@weekly", "@yearly"
Schedule your cron job with one of the special predefined value instead of ** * pattern.
random_delay
- Ruby Type: Integer
Set the
RANDOM_DELAY
environment variable in the cron.d file.
shell
- Ruby Type: String
Set the
SHELL
environment variable.
time_out
- Ruby Type: Hash | Default Value:
{}
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)
New in Chef Infra Client 15.7
user
- Ruby Type: String | Default Value:
root
The name of the user that runs the command.
weekday
- Ruby Type: Integer, String, Symbol | Default Value:
*
The day of the week on which this entry is to run (
0-7
,mon-sun
,monday-sunday
, or*
), where Sunday is both0
and7
.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the cron_d resource in recipes:
Run a program on the fifth hour of the day
cron_d 'noop' do
hour '5'
minute '0'
command '/bin/true'
end
Run an entry if a folder exists
cron_d '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 an entry every Saturday, 8:00 AM
cron_d 'name_of_cron_entry' do
minute '0'
hour '8'
weekday '6'
mailto 'admin@example.com'
command '/bin/true'
action :create
end
Run an entry at 8:00 PM, every weekday (Monday through Friday), but only in November
cron_d 'name_of_cron_entry' do
minute '0'
hour '20'
day '*'
month '11'
weekday '1-5'
command '/bin/true'
action :create
end
Remove a cron job by name:
cron_d 'job_to_remove' do
action :delete
end
csh resource
csh resource pageUse the csh resource to execute scripts using the csh interpreter. This resource may also use any of the actions and properties that are available to the execute resource. 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.
Syntax
The full syntax for all of the properties that are available to the csh resource is:
csh 'name' do
code String
command String, Array # default value: 'name' unless specified
creates String
cwd String
default_env true, false # default value: false
domain String
elevated true, false # default value: false
environment Hash
flags String
group String, Integer
input String
interpreter String
live_stream true, false # default value: false
login true, false # default value: false
password String
returns Integer, Array # default value: 0
timeout Integer, String, Float # default value: 3600
user String, Integer
action Symbol # defaults to :run if not specified
end
where:
csh
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.code
,command
,creates
,cwd
,default_env
,domain
,elevated
,environment
,flags
,group
,input
,interpreter
,live_stream
,login
,password
,returns
,timeout
, anduser
are the properties available to this resource.
Actions
The csh resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:run
- Run a command. (default)
Properties
The csh resource has the following properties:
code
- Ruby Type: String |
REQUIRED
A quoted string of code to be executed.
creates
- Ruby Type: String
Prevent a command from creating a file when that file already exists.
cwd
- Ruby Type: String
The current working directory from which the command will be run.
environment
- Ruby Type: Hash
A Hash of environment variables in the form of
({'ENV_VARIABLE' => 'VALUE'})
. Note: These variables must exist for a command to be run successfully.
flags
- Ruby Type: String
One or more command line flags that are passed to the interpreter when a command is invoked.
group
- Ruby Type: String, Integer
The group name or group ID that must be changed before running a command.
returns
- Ruby Type: Integer, Array | Default Value:
0
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.
timeout
- Ruby Type: Integer, String, Float | Default Value:
3600
The amount of time (in seconds) a command is to wait before timing out.
user
- Ruby Type: String, Integer
The user name or user ID that should be changed before running a command.
umask
- Ruby Type: String, Integer
The file mode creation mask, or umask.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
This resource does not have any examples.
directory resource
directory resource pageUse the directory resource to manage a directory, which is a hierarchy of folders that comprises all of the information stored on a computer. The root directory is the top-level, under which the rest of the directory is organized. The directory resource uses the name property to specify the path to a location in a directory. Typically, permission to access that location in the directory is required.
Syntax
A directory resource block declares a directory and the permissions needed on that directory. For example:
directory '/etc/apache2' do
owner 'root'
group 'root'
mode '0755'
action :create
end
The full syntax for all of the properties that are available to the directory resource is:
directory 'name' do
group String, Integer
inherits true, false
mode String, Integer
owner String, Integer
path String # defaults to 'name' if not specified
recursive true, false
rights Hash
action Symbol # defaults to :create if not specified
end
where:
directory
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.group
,mode
,owner
,path
, andrecursive
are the properties available to this resource.
Actions
The directory resource has the following actions:
:create
- Create a directory. If a directory already exists (but does not match), update that directory to match. (default)
:delete
- Delete a directory.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The directory resource has the following properties:
group
- Ruby Type: Integer, String
A string or ID that identifies the group owner by group name or SID, including fully qualified group names such as
domain\group
orgroup@domain
. If this value is not specified, existing groups remain unchanged and new group assignments use the defaultPOSIX
group (if available).
inherits
- Ruby Type: true, false | Default Value:
true
Microsoft Windows only. Whether a file inherits rights from its parent directory.
mode
- Ruby Type: Integer, String
A quoted 3-5 character string that defines the octal mode. For example:
'755'
,'0755'
, or00755
. Ifmode
is not specified and if the directory already exists, the existing mode on the directory is used. Ifmode
is not specified, the directory does not exist, and the:create
action is specified, Chef Infra Client assumes a mask value of'0777'
, and then applies the umask for the system on which the directory is to be created to themask
value. For example, if the umask on a system is'022'
, Chef Infra Client uses the default value of'0755'
.The behavior is different depending on the platform.
UNIX- and Linux-based systems: A quoted 3-5 character string that defines the octal mode that is passed to chmod. For example:
'755'
,'0755'
, or00755
. If the value is specified as a quoted string, it works exactly as if thechmod
command was passed. If the value is specified as an integer, prepend a zero (0
) to the value to ensure that it is interpreted as an octal number. For example, to assign read, write, and execute rights for all users, use'0777'
or'777'
; for the same rights, plus the sticky bit, use01777
or'1777'
.Microsoft Windows: A quoted 3-5 character string that defines the octal mode that is translated into rights for Microsoft Windows security. For example:
'755'
,'0755'
, or00755
. Values up to'0777'
are allowed (no sticky bits) and mean the same in Microsoft Windows as they do in UNIX, where4
equalsGENERIC_READ
,2
equalsGENERIC_WRITE
, and1
equalsGENERIC_EXECUTE
. This property cannot be used to set:full_control
. This property has no effect if not specified, but when it andrights
are both specified, the effects are cumulative.
owner
- Ruby Type: Integer, String
A string or ID that identifies the group owner by user name or SID, including fully qualified user names such as
domain\user
oruser@domain
. If this value is not specified, existing owners remain unchanged and new owner assignments use the current user (when necessary).
path
- Ruby Type: String | Default Value:
The resource block's name
The path to the directory. Using a fully qualified path is recommended, but is not always required. Default value: the
name
of the resource block. See “Syntax” section above for more information.
recursive
- Ruby Type: true, false | Default Value:
false
Create parent directories recursively, or delete directory and all children recursively. For the owner, group, and mode properties, the value of this property applies only to the leaf directory.
rights
- Ruby Type: Integer, String
Microsoft Windows only. The permissions for users and groups in a Microsoft Windows environment. For example:
rights <permissions>, <principal>, <options>
where<permissions>
specifies the rights granted to the principal,<principal>
is the group or user name, and<options>
is a Hash with one (or more) advanced rights options.
Recursive Directories
The remote_directory resource can be used to recursively create the
path outside of remote directory structures, but the permissions of
those outside paths are not managed. This is because the recursive
attribute only applies group
, mode
, and owner
attribute values to
the remote directory itself and any inner directories the resource
copies.
A directory structure:
/foo
/bar
/baz
The following example shows a way create a file in the /baz
directory:
remote_directory '/foo/bar/baz' do
owner 'root'
group 'root'
mode '0755'
action :create
end
But with this example, the group
, mode
, and owner
attribute values
will only be applied to /baz
. Which is fine, if that’s what you want.
But most of the time, when the entire /foo/bar/baz
directory structure
is not there, you must be explicit about each directory. For example:
%w( /foo /foo/bar /foo/bar/baz ).each do |path|
remote_directory path do
owner 'root'
group 'root'
mode '0755'
end
end
This approach will create the correct hierarchy—/foo
, then /bar
in
/foo
, and then /baz
in /bar
—and also with the correct attribute
values for group
, mode
, and owner
.
Windows File Security
To support Windows security, the template, file, remote_file, cookbook_file, directory, and remote_directory resources support the use of inheritance and access control lists (ACLs) within recipes. Access Control Lists (ACLs)The rights
property can be used in a recipe to manage access control
lists (ACLs), which allow permissions to be given to multiple users and
groups. Use the rights
property can be used as many times as
necessary; Chef Infra Client will apply them to the file or directory as
required. The syntax for the rights
property is as follows:
rights permission, principal, option_type => value
where
permission
Use to specify which rights are granted to the
principal
. The possible values are::read
,:write
,read_execute
,:modify
,:full_control
, or an integer.Integers used for permissions must match the following list FileSystemRights Enum fields.
These permissions are cumulative. If
:write
is specified, then it includes:read
. If:full_control
is specified, then it includes both:write
and:read
.(For those who know the Windows API:
:read
corresponds toGENERIC_READ
;:write
corresponds toGENERIC_WRITE
;:read_execute
corresponds toGENERIC_READ
andGENERIC_EXECUTE
;:modify
corresponds toGENERIC_WRITE
,GENERIC_READ
,GENERIC_EXECUTE
, andDELETE
;:full_control
corresponds toGENERIC_ALL
, which allows a user to change the owner and other metadata about a file.)principal
Use to specify a group or user. The principal can be specified by either name or SID. When using name, this is identical to what is entered in the login box for Windows, such as
user_name
,domain\user_name
, oruser_name@fully_qualified_domain_name
. When using a SID, you may use either the standard string representation of a SID (S-R-I-S-S) or one of the SDDL string constants. Chef Infra Client does not need to know if a principal is a user or a group.option_type
A hash that contains advanced rights options. For example, the rights to a directory that only applies to the first level of children might look something like:
rights :write, 'domain\group_name', :one_level_deep => true
.Possible option types:
:applies_to_children
Specify how permissions are applied to children. Possible values:
true
to inherit both child directories and files;false
to not inherit any child directories or files;:containers_only
to inherit only child directories (and not files);:objects_only
to recursively inherit files (and not child directories).:applies_to_self
Indicates whether a permission is applied to the parent directory. Possible values:
true
to apply to the parent directory or file and its children;false
to not apply only to child directories and files.:one_level_deep
Indicates the depth to which permissions will be applied. Possible values:
true
to apply only to the first level of children;false
to apply to all children.
For example:
resource 'x.txt' do
rights :read, 'S-1-1-0'
rights :write, 'domain\group'
rights :full_control, 'group_name_or_user_name'
rights :full_control, 'user_name', applies_to_children: true
end
or:
rights :read, %w(Administrators Everyone)
rights :full_control, 'Users', applies_to_children: true
rights :write, 'Sally', applies_to_children: :containers_only, applies_to_self: false, one_level_deep: true
Some other important things to know when using the rights
attribute:
- Only inherited rights remain. All existing explicit rights on the object are removed and replaced.
- If rights are not specified, nothing will be changed. Chef Infra Client does not clear out the rights on a file or directory if rights are not specified.
- Changing inherited rights can be expensive. Windows will propagate rights to all children recursively due to inheritance. This is a normal aspect of Windows, so consider the frequency with which this type of action is necessary and take steps to control this type of action if performance is the primary consideration.
Use the deny_rights
property to deny specific rights to specific
users. The ordering is independent of using the rights
property. For
example, it doesn’t matter if rights are granted to everyone is placed
before or after deny_rights :read, ['Julian', 'Lewis']
, both Julian
and Lewis will be unable to read the document. For example:
resource 'x.txt' do
rights :read, 'Everyone'
rights :write, 'domain\group'
rights :full_control, 'group_name_or_user_name'
rights :full_control, 'user_name', applies_to_children: true
deny_rights :read, %w(Julian Lewis)
end
or:
deny_rights :full_control, ['Sally']
By default, a file or directory inherits rights from its parent
directory. Most of the time this is the preferred behavior, but
sometimes it may be necessary to take steps to more specifically control
rights. The inherits
property can be used to specifically tell Chef
Infra Client to apply (or not apply) inherited rights from its parent
directory.
For example, the following example specifies the rights for a directory:
directory 'C:\mordor' do
rights :read, 'MORDOR\Minions'
rights :full_control, 'MORDOR\Sauron'
end
and then the following example specifies how to use inheritance to deny access to the child directory:
directory 'C:\mordor\mount_doom' do
rights :full_control, 'MORDOR\Sauron'
inherits false # Sauron is the only person who should have any sort of access
end
If the deny_rights
permission were to be used instead, something could
slip through unless all users and groups were denied.
Another example also shows how to specify rights for a directory:
directory 'C:\mordor' do
rights :read, 'MORDOR\Minions'
rights :full_control, 'MORDOR\Sauron'
rights :write, 'SHIRE\Frodo' # Who put that there I didn't put that there
end
but then not use the inherits
property to deny those rights on a child
directory:
directory 'C:\mordor\mount_doom' do
deny_rights :read, 'MORDOR\Minions' # Oops, not specific enough
end
Because the inherits
property is not specified, Chef Infra Client will
default it to true
, which will ensure that security settings for
existing files remain unchanged.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the directory resource in recipes:
Create a directory
directory '/tmp/something' do
owner 'root'
group 'root'
mode '0755'
action :create
end
Create a directory in Microsoft Windows
directory "C:\\tmp\\something" do
rights :full_control, "DOMAIN\\User"
inherits false
action :create
end
or:
directory 'C:\tmp\something' do
rights :full_control, 'DOMAIN\User'
inherits false
action :create
end
Note
The difference between the two previous examples is the single- versus
double-quoted strings, where if the double quotes are used, the backslash character
(\
) must be escaped using the Ruby escape character (which is a
backslash).
Create a directory recursively:
%w{dir1 dir2 dir3}.each do |dir|
directory "/tmp/mydirs/#{dir}" do
mode '0755'
owner 'root'
group 'root'
action :create
recursive true
end
end
Delete a directory:
directory '/tmp/something' do
recursive true
action :delete
end
Set directory permissions using a variable
The following example
shows how read/write/execute permissions can be
set using a variable named
user_home
, and then for owners and groups
on any matching node:
user_home = "/#{node[:matching_node][:user]}"
directory user_home do
owner 'node[:matching_node][:user]'
group 'node[:matching_node][:group]'
mode '0755'
action :create
end
where matching_node
represents
a type of node. For example, if the
user_home
variable specified {node[:nginx]...}
,
a recipe might look
similar to:
user_home = "/#{node[:nginx][:user]}"
directory user_home do
owner 'node[:nginx][:user]'
group 'node[:nginx][:group]'
mode '0755'
action :create
end
Set directory permissions for a specific type of node
The following example shows how permissions can be set for the
/certificates
directory on any node that is running Nginx. In this
example, permissions are being set for the owner
and group
properties as root
, and then read/write permissions are granted to the
root.
directory "#{node[:nginx][:dir]}/shared/certificates" do
owner 'root'
group 'root'
mode '0755'
recursive true
end
Reload the configuration
The following example shows how to reload the configuration of a chef-client using the remote_file resource to:
- using an if statement to check whether the plugins on a node are the latest versions
- identify the location from which Ohai plugins are stored
- using the
notifies
property and a ruby_block resource to trigger an update (if required) and to then reload the client.rb file.
directory 'node[:ohai][:plugin_path]' do
owner 'chef'
recursive true
end
ruby_block 'reload_config' do
block do
Chef::Config.from_file('/etc/chef/client.rb')
end
action :nothing
end
if node[:ohai].key?(:plugins)
node[:ohai][:plugins].each do |plugin|
remote_file node[:ohai][:plugin_path] +"/#{plugin}" do
source plugin
owner 'chef'
notifies :run, 'ruby_block[reload_config]', :immediately
end
end
end
Manage dotfiles
The following example shows using the directory and cookbook_file resources to manage dotfiles. The dotfiles are defined by a JSON data structure similar to:
"files": {
".zshrc": {
"mode": '0755',
"source": "dot-zshrc"
},
".bashrc": {
"mode": '0755',
"source": "dot-bashrc"
},
".bash_profile": {
"mode": '0755',
"source": "dot-bash_profile"
},
}
and then the following resources manage the dotfiles:
if u.has_key?('files')
u['files'].each do |filename, file_data|
directory "#{home_dir}/#{File.dirname(filename)}" do
recursive true
mode '0755'
end if file_data['subdir']
cookbook_file "#{home_dir}/#{filename}" do
source "#{u['id']}/#{file_data['source']}"
owner 'u['id']'
group 'group_id'
mode 'file_data['mode']'
ignore_failure true
backup 0
end
end
dmg_package resource
dmg_package resource pageUse the dmg_package resource to install a package from a .dmg file. The resource will retrieve the dmg file from a remote URL, mount it using macOS’ hdidutil
, copy the application (.app directory) to the specified destination (/Applications
), and detach the image using hdiutil
. The dmg file will be stored in the Chef::Config[:file_cache_path]
.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the dmg_package resource is:
dmg_package 'name' do
accept_eula true, false # default value: false
allow_untrusted true, false # default value: false
app String # default value: 'name' unless specified
checksum String
destination String # default value: "/Applications"
dmg_name String # default value: The value passed for the application name.
dmg_passphrase String
file String
headers Hash
owner String, Integer
package_id String
source String
type String # default value: "app"
volumes_dir String # default value: The value passed for the application name.
action Symbol # defaults to :install if not specified
end
where:
dmg_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.accept_eula
,allow_untrusted
,app
,checksum
,destination
,dmg_name
,dmg_passphrase
,file
,headers
,owner
,package_id
,source
,type
, andvolumes_dir
are the properties available to this resource.
Actions
The dmg_package resource has the following actions:
:install
- Installs the application. (default)
Properties
The dmg_package resource has the following properties:
accept_eula
- Ruby Type: true, false | Default Value:
false
Specify whether to accept the EULA. Certain dmg files require acceptance of EULA before mounting.
allow_untrusted
- Ruby Type: true, false | Default Value:
false
Allow installation of packages that do not have trusted certificates.
app
- Ruby Type: String | Default Value:
The resource block's name
The name of the application as it appears in the
/Volumes
directory if it differs from the resource block’s name.
checksum
- Ruby Type: String
The sha256 checksum of the
.dmg
file to download.
destination
- Ruby Type: String | Default Value:
/Applications
The directory to copy the
.app
into.
dmg_name
- Ruby Type: String | Default Value:
The value passed for the application name.
The name of the
.dmg
file if it differs from that of the app, or if the name has spaces.
dmg_passphrase
- Ruby Type: String
Specify a passphrase to be used to decrypt the
.dmg
file during the mount process.
file
- Ruby Type: String
The absolute path to the
.dmg
file on the local system.
headers
- Ruby Type: Hash
Allows custom HTTP headers (like cookies) to be set on the
remote_file
resource.
owner
- Ruby Type: String, Integer
The user that should own the package installation.
package_id
- Ruby Type: String
The package ID that is registered with
pkgutil
when apkg
ormpkg
is installed.
source
- Ruby Type: String
The remote URL that is used to download the
.dmg
file, if specified.
type
- Ruby Type: String | Default Value:
app
Allowed Values:"app", "mpkg", "pkg"
The type of package.
volumes_dir
- Ruby Type: String | Default Value:
The value passed for the application name.
The directory under
/Volumes
where thedmg
is mounted if it differs from the name of the.dmg
file.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the dmg_package resource in recipes:
Install Google Chrome via the DMG package:
dmg_package 'Google Chrome' do
dmg_name 'googlechrome'
source 'https://dl-ssl.google.com/chrome/mac/stable/GGRM/googlechrome.dmg'
checksum '7daa2dc5c46d9bfb14f1d7ff4b33884325e5e63e694810adc58f14795165c91a'
action :install
end
Install VirtualBox from the .mpkg:
dmg_package 'Virtualbox' do
source 'http://dlc.sun.com.edgesuite.net/virtualbox/4.0.8/VirtualBox-4.0.8-71778-OSX.dmg'
type 'mpkg'
end
Install pgAdmin and automatically accept the EULA:
dmg_package 'pgAdmin3' do
source 'http://wwwmaster.postgresql.org/redir/198/h/pgadmin3/release/v1.12.3/osx/pgadmin3-1.12.3.dmg'
checksum '9435f79d5b52d0febeddfad392adf82db9df159196f496c1ab139a6957242ce9'
accept_eula true
end
dnf_package resource
dnf_package resource pageUse the dnf_package resource to install, upgrade, and remove packages with DNF for Fedora and RHEL 8+. The dnf_package resource is able to resolve provides data for packages much like DNF can do when it is run from the command line. This allows a variety of options for installing packages, like minimum versions, virtual provides and library names.
Note
New in Chef Infra Client 12.18.
Syntax
A dnf_package resource block manages a package on a node, typically by installing it. The simplest use of the dnf_package resource is:
dnf_package ''package_name''
which will install the named package using all of the default options
and the default action (:install
).
The full syntax for all of the properties that are available to the dnf_package resource is:
dnf_package 'name' do
allow_downgrade true, false # default value: true
arch String, Array
flush_cache Hash # default value: {"before"=>false, "after"=>false}
options String, Array
package_name String, Array
source String
timeout String, Integer
version String, Array
action Symbol # defaults to :install if not specified
end
where:
dnf_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.allow_downgrade
,arch
,flush_cache
,options
,package_name
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The dnf_package resource has the following actions:
:install
- Install a package. If a version is specified, install the specified version of the package. (default)
:lock
- Locks the DNF package to a specific version.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:purge
- Purge a package. This action typically removes the configuration files as well as the package.
:reconfig
- Change the installed package.
:remove
- Remove a package.
:unlock
- Unlocks the DNF package so that it can be upgraded to a newer version.
:upgrade
- Install a package and ensure that a package is the latest version.
Properties
The dnf_package resource has the following properties:
allow_downgrade
- Ruby Type: true, false | Default Value:
true
Allow downgrading a package to satisfy requested version requirements.
arch
- Ruby Type: String, Array
The architecture of the package to be installed or upgraded. This value can also be passed as part of the package name.
flush_cache
- Ruby Type: Hash | Default Value:
{"before"=>false, "after"=>false}
Flush the in-memory cache before or after a DNF operation that installs, upgrades, or removes a package. DNF automatically synchronizes remote metadata to a local cache. The Chef Infra Client creates a copy of the local cache, and then stores it in-memory during the Chef Infra Client run. The in-memory cache allows packages to be installed during the Chef Infra Client run without the need to continue synchronizing the remote metadata to the local cache while the Chef Infra Client run is in-progress.
dnf_package 'some_package' do #... flush_cache [ :before] #... end
Note
The
flush_cache
property does not flush the local DNF cache! Use DNF tools to clean the local DNF cache. For example:dnf clean metadata
dnf clean packages
dnf clean all
options
- Ruby Type: String, Array
One (or more) additional command options that are passed to the command.
package_name
- Ruby Type: String, Array
An optional property to set the package name if it differs from the resource block’s name.
source
- Ruby Type: String
The optional path to a package on the local file system.
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String, Array
The version of a package to be installed or upgraded. This property is ignored when using the
:upgrade
action.
Multiple Packages
A resource may specify multiple packages and/or versions for platforms that use Apt, Chocolatey, DNF, Homebrew, Pacman, or Zypper package managers. Specifying multiple packages and/or versions allows a single transaction to:
- Download the specified packages and versions using a single HTTP transaction
- Update or install multiple packages with a single resource during a Chef Infra Client run
For example, installing multiple packages:
package %w(package1 package2)
Installing multiple packages with versions:
package %w(package1 package2) do
version [ '1.3.4-2', '4.3.6-1']
end
Upgrading multiple packages:
package %w(package1 package2) do
action :upgrade
end
Removing multiple packages:
package %w(package1 package2) do
action :remove
end
Purging multiple packages:
package %w(package1 package2) do
action :purge
end
Notifications, using an implicit name:
package %w(package1 package2) do
action :nothing
end
log 'call a notification' do
notifies :install, 'package[package1, package2]', :immediately
end
Note
Notifications and subscriptions do not need to be updated when packages
and versions are added or removed from the package_name
or version
properties.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Multiple Packages
A resource may specify multiple packages and/or versions for platforms that use Apt, Chocolatey, DNF, Homebrew, Pacman, or Zypper package managers. Specifying multiple packages and/or versions allows a single transaction to:
- Download the specified packages and versions using a single HTTP transaction
- Update or install multiple packages with a single resource during a Chef Infra Client run
For example, installing multiple packages:
package %w(package1 package2)
Installing multiple packages with versions:
package %w(package1 package2) do
version [ '1.3.4-2', '4.3.6-1']
end
Upgrading multiple packages:
package %w(package1 package2) do
action :upgrade
end
Removing multiple packages:
package %w(package1 package2) do
action :remove
end
Purging multiple packages:
package %w(package1 package2) do
action :purge
end
Notifications, using an implicit name:
package %w(package1 package2) do
action :nothing
end
log 'call a notification' do
notifies :install, 'package[package1, package2]', :immediately
end
Note
Notifications and subscriptions do not need to be updated when packages
and versions are added or removed from the package_name
or version
properties.
Examples
The following examples demonstrate various approaches for using the dnf_package resource in recipes:
Install an exact version
dnf_package 'netpbm = 10.35.58-8.el5'
Install a minimum version
dnf_package 'netpbm >= 10.35.58-8.el5'
Install a minimum version using the default action
dnf_package 'netpbm'
To install a package
dnf_package 'netpbm' do
action :install
end
To install a partial minimum version
dnf_package 'netpbm >= 10'
To install a specific architecture
dnf_package 'netpbm' do
arch 'i386'
end
or:
dnf_package 'netpbm.x86_64'
To install a specific version-release
dnf_package 'netpbm' do
version '10.35.58-8.el5'
end
To install a specific version (even when older than the current)
dnf_package 'tzdata' do
version '2011b-1.el5'
end
Handle cookbook_file and dnf_package resources in the same recipe
When a cookbook_file resource and a dnf_package resource are
both called from within the same recipe, use the flush_cache
attribute
to dump the in-memory DNF cache, and then use the repository immediately
to ensure that the correct package is installed:
cookbook_file '/etc/yum.repos.d/custom.repo' do
source 'custom'
mode '0755'
end
dnf_package 'only-in-custom-repo' do
action :install
flush_cache [ :before ]
end
dpkg_package resource
dpkg_package resource pageUse the dpkg_package resource to manage packages for the dpkg platform. When a package is installed from a local file, it must be added to the node using the remote_file or cookbook_file resources.
Syntax
A dpkg_package resource block manages a package on a node, typically by installing it. The simplest use of the dpkg_package resource is:
ruby dpkg_package 'package_name'
which will install the named package using all of the default options and the default action (:install
).
The full syntax for all of the properties that are available to the dpkg_package resource is:
dpkg_package 'name' do
allow_downgrade true, false # default value: true
options String, Array
package_name String, Array
response_file String
response_file_variables Hash # default value: {}
source String, Array
timeout String, Integer
version String, Array
action Symbol # defaults to :install if not specified
end
where:
dpkg_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.allow_downgrade
,options
,package_name
,response_file
,response_file_variables
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The dpkg_package resource has the following actions:
:install
- Install a package. If a version is specified, install the specified version of the package. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:purge
- Purge a package. This action typically removes the configuration files as well as the package.
:remove
- Remove a package.
Properties
The dpkg_package resource has the following properties:
options
- Ruby Type: String, Array
One (or more) additional command options that are passed to the command.
package_name
- Ruby Type: String, Array
An optional property to set the package name if it differs from the resource block’s name.
response_file
- Ruby Type: String
The direct path to the file used to pre-seed a package.
response_file_variables
- Ruby Type: Hash | Default Value:
{}
A Hash of response file variables in the form of {‘VARIABLE’ => ‘VALUE’}.
source
- Ruby Type: String, Array
The path to a package in the local file system.
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String, Array
The version of a package to be installed or upgraded.
Multiple Packages
A resource may specify multiple packages and/or versions for platforms that use Apt, Chocolatey, DNF, Homebrew, Pacman, or Zypper package managers. Specifying multiple packages and/or versions allows a single transaction to:
- Download the specified packages and versions using a single HTTP transaction
- Update or install multiple packages with a single resource during a Chef Infra Client run
For example, installing multiple packages:
package %w(package1 package2)
Installing multiple packages with versions:
package %w(package1 package2) do
version [ '1.3.4-2', '4.3.6-1']
end
Upgrading multiple packages:
package %w(package1 package2) do
action :upgrade
end
Removing multiple packages:
package %w(package1 package2) do
action :remove
end
Purging multiple packages:
package %w(package1 package2) do
action :purge
end
Notifications, using an implicit name:
package %w(package1 package2) do
action :nothing
end
log 'call a notification' do
notifies :install, 'package[package1, package2]', :immediately
end
Note
Notifications and subscriptions do not need to be updated when packages
and versions are added or removed from the package_name
or version
properties.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Multiple Packages
A resource may specify multiple packages and/or versions for platforms that use Apt, Chocolatey, DNF, Homebrew, Pacman, or Zypper package managers. Specifying multiple packages and/or versions allows a single transaction to:
- Download the specified packages and versions using a single HTTP transaction
- Update or install multiple packages with a single resource during a Chef Infra Client run
For example, installing multiple packages:
package %w(package1 package2)
Installing multiple packages with versions:
package %w(package1 package2) do
version [ '1.3.4-2', '4.3.6-1']
end
Upgrading multiple packages:
package %w(package1 package2) do
action :upgrade
end
Removing multiple packages:
package %w(package1 package2) do
action :remove
end
Purging multiple packages:
package %w(package1 package2) do
action :purge
end
Notifications, using an implicit name:
package %w(package1 package2) do
action :nothing
end
log 'call a notification' do
notifies :install, 'package[package1, package2]', :immediately
end
Note
Notifications and subscriptions do not need to be updated when packages
and versions are added or removed from the package_name
or version
properties.
Examples
The following examples demonstrate various approaches for using the dpkg_package resource in recipes:
Install a package
dpkg_package 'wget_1.13.4-2ubuntu1.4_amd64.deb' do
source '/foo/bar/wget_1.13.4-2ubuntu1.4_amd64.deb'
action :install
end
dsc_resource resource
dsc_resource resource pageWindows PowerShell is a task-based command-line shell and scripting language developed by Microsoft. Windows PowerShell uses a document-oriented approach for managing Windows-based machines, similar to the approach that is used for managing Unix and Linux-based machines. Windows PowerShell is a tool-agnostic platform that supports using Chef for configuration management.
Desired State Configuration (DSC) is a feature of Windows PowerShell that provides a set of language extensions, cmdlets, and resources that can be used to declaratively configure software. DSC is similar to Chef, in that both tools are idempotent, take similar approaches to the concept of resources, describe the configuration of a system, and then take the steps required to do that configuration. The most important difference between Chef and DSC is that Chef uses Ruby and DSC is exposed as configuration data from within Windows PowerShell.
The dsc_resource resource allows any DSC resource to be used in a recipe, as well as any custom resources that have been added to your Windows PowerShell environment. Microsoft frequently adds new resources to the DSC resource collection.
Using the dsc_resource has the following requirements:
Windows Management Framework (WMF) 5.0 (or higher)
The dsc_resource resource can only use binary- or script-based resources. Composite DSC resources may not be used.
This is because composite resources aren’t “real” resources from the perspective of the Local Configuration Manager (LCM). Composite resources are used by the “configuration” keyword from the
PSDesiredStateConfiguration
module, and then evaluated in that context. When using DSC to create the configuration document (the Managed Object Framework (MOF) file) from the configuration command, the composite resource is evaluated. Any individual resources from that composite resource are written into the Managed Object Framework (MOF) document. As far as the Local Configuration Manager (LCM) is concerned, there is no such thing as a composite resource. Unless that changes, the dsc_resource resource and/orInvoke-DscResource
command cannot directly use them.
Warning
New in Chef Infra Client 12.2.
Syntax
A dsc_resource resource block allows DSC resources to be used in a
Chef recipe. For example, the DSC Archive
resource:
Archive ExampleArchive {
Ensure = "Present"
Path = "C:\Users\Public\Documents\example.zip"
Destination = "C:\Users\Public\Documents\ExtractionPath"
}
and then the same dsc_resource with Chef:
dsc_resource 'example' do
resource :archive
property :ensure, 'Present'
property :path, "C:\Users\Public\Documents\example.zip"
property :destination, "C:\Users\Public\Documents\ExtractionPath"
end```
The full syntax for all of the properties that are available to the dsc_resource resource is:
dsc_resource 'name' do
module_version String
reboot_action Symbol # default value: :nothing
timeout Integer
action Symbol # defaults to :run if not specified
end
where:
dsc_resource
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.module_version
,reboot_action
, andtimeout
are the properties available to this resource.
Actions
The dsc_resource resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:run
- (default)
Properties
The dsc_resource resource has the following properties:
module_name
- Ruby Type: String
The name of the module from which a DSC resource originates. If this property is not specified, it will be inferred.
module_version
- Ruby Type: String
The version number of the module to use. PowerShell 5.0.10018.0 (or higher) supports having multiple versions of a module installed. This should be specified along with the
module_name
property.New in Chef Client 12.21
property
- Ruby Type: String
A property from a Desired State Configuration (DSC) resource. Use this property multiple times, one for each property in the Desired State Configuration (DSC) resource. The format for this property must follow
property :dsc_property_name, "property_value"
for each DSC property added to the resource block. The:dsc_property_name
must be a symbol.Use the following Ruby types to define property_value:
Ruby PowerShell :array
Object[]
Chef::Util::Powershell:PSCredential
PSCredential
False
bool($false)
Fixnum
Integer
Float
Double
Hash
Hashtable
True
bool($true)
These are converted into the corresponding Windows PowerShell type during a Chef Infra Client run.
reboot_action
- Ruby Type: Symbol | Default Value:
:nothing
Allowed Values::nothing, :reboot_now, :request_reboot
Use to request an immediate reboot or to queue a reboot using the :reboot_now (immediate reboot) or :request_reboot (queued reboot) actions built into the reboot resource.
New in Chef Client 12.6
resource
- Ruby Type: Symbol
The name of the DSC resource. This value is case-insensitive and must be a symbol that matches the name of the DSC resource.
For built-in DSC resources, use the following values:
Value Description :archive
Use to unpack archive (.zip) files. :environment
Use to manage system environment variables. :file
Use to manage files and directories. :group
Use to manage local groups. :log
Use to log configuration messages. :package
Use to install and manage packages. :registry
Use to manage registry keys and registry key values. :script
Use to run PowerShell script blocks. :service
Use to manage services. :user
Use to manage local user accounts. :windowsfeature
Use to add or remove Windows features and roles. :windowsoptionalfeature
Use to configure Microsoft Windows optional features. :windowsprocess
Use to configure Windows processes. Any DSC resource may be used in a Chef recipe. For example, the DSC Resource Kit contains resources for configuring Active Directory components, such as
xADDomain
,xADDomainController
, andxADUser
. Assuming that these resources are available to Chef Infra Client, the corresponding values for theresource
attribute would be::xADDomain
,:xADDomainController
, andxADUser
.
timeout
- Ruby Type: Integer
The amount of time (in seconds) a command is to wait before timing out.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the dsc_resource resource in recipes:
Open a Zip file
dsc_resource 'example' do
resource :archive
property :ensure, 'Present'
property :path, 'C:\Users\Public\Documents\example.zip'
property :destination, 'C:\Users\Public\Documents\ExtractionPath'
end
Manage users and groups
dsc_resource 'demogroupadd' do
resource :group
property :groupname, 'demo1'
property :ensure, 'present'
end
dsc_resource 'useradd' do
resource :user
property :username, 'Foobar1'
property :fullname, 'Foobar1'
property :password, ps_credential('P@assword!')
property :ensure, 'present'
end
dsc_resource 'AddFoobar1ToUsers' do
resource :Group
property :GroupName, 'demo1'
property :MembersToInclude, ['Foobar1']
end
Create and register a windows service
The following example creates a windows service, defines it’s execution path, and prevents windows from starting the service in case the executable is not at the defined location:
dsc_resource 'NAME' do
resource :service
property :name, 'NAME'
property :startuptype, 'Disabled'
property :path, 'D:\\Sites\\Site_name\file_to_run.exe'
property :ensure, 'Present'
property :state, 'Stopped'
end
Create a test message queue
The following example creates a file on a node (based on one that is
located in a cookbook), unpacks the MessageQueue.zip
Windows
PowerShell module, and then uses the dsc_resource to ensure that
Message Queuing (MSMQ) sub-features are installed, a test queue is
created, and that permissions are set on the test queue:
cookbook_file 'cMessageQueue.zip' do
path "#{Chef::Config[:file_cache_path]}\\MessageQueue.zip"
action :create_if_missing
end
windows_zipfile "#{ENV['PROGRAMW6432']}\\WindowsPowerShell\\Modules" do
source "#{Chef::Config[:file_cache_path]}\\MessageQueue.zip"
action :unzip
end
dsc_resource 'install-sub-features' do
resource :windowsfeature
property :ensure, 'Present'
property :name, 'msmq'
property :IncludeAllSubFeature, true
end
dsc_resource 'create-test-queue' do
resource :cPrivateMsmqQueue
property :ensure, 'Present'
property :name, 'Test_Queue'
end
dsc_resource 'set-permissions' do
resource :cPrivateMsmqQueuePermissions
property :ensure, 'Present'
property :name, 'Test_Queue_Permissions'
property :QueueNames, 'Test_Queue'
property :ReadUsers, node['msmq']['read_user']
end
Example to show usage of module properties
dsc_resource 'test-cluster' do
resource :xCluster
module_name 'xFailOverCluster'
module_version '1.6.0.0'
property :name, 'TestCluster'
property :staticipaddress, '10.0.0.3'
property :domainadministratorcredential, ps_credential('abcd')
end
dsc_script resource
dsc_script resource pageWindows PowerShell is a task-based command-line shell and scripting language developed by Microsoft. Windows PowerShell uses a document-oriented approach for managing Windows-based machines, similar to the approach that is used for managing Unix and Linux-based machines. Windows PowerShell is a tool-agnostic platform that supports using Chef for configuration management.
Desired State Configuration (DSC) is a feature of Windows PowerShell that provides a set of language extensions, cmdlets, and resources that can be used to declaratively configure software. DSC is similar to Chef, in that both tools are idempotent, take similar approaches to the concept of resources, describe the configuration of a system, and then take the steps required to do that configuration. The most important difference between Chef and DSC is that Chef uses Ruby and DSC is exposed as configuration data from within Windows PowerShell.
Many DSC resources are comparable to built-in Chef Infra Client resources. For example, both DSC and Chef Infra Client
have file, package, and service resources. The dsc_script resource is most useful for those DSC resources that do not have a direct comparison to a
resource in Chef Infra Client, such as the DSC Archive resource, a custom DSC resource, an existing DSC script that performs an important
task, and so on. Use the dsc_script
resource to embed the code that defines a DSC configuration directly within a Chef Infra Client recipe.
Note
Windows PowerShell 4.0 is required for using the dsc_script resource with Chef Infra.
Note
The WinRM service must be enabled. (Use winrm quickconfig
to enable the service.)
Warning
The dsc_script resource may not be used in the same run-list with the dsc_resource. This is because the dsc_script resource requires that RefreshMode
in the Local Configuration Manager be set to Push
, whereas the dsc_resource resource requires it to be set to Disabled
.
Warning
The dsc_script resource is only available on 64-bit versions of Chef Infra Client.
Syntax
A dsc_script resource block embeds the code that defines a DSC configuration directly within a Chef recipe:
dsc_script 'get-dsc-resource-kit' do
code <<-EOH
Archive reskit
{
ensure = 'Present'
path = "#{Chef::Config[:file_cache_path]}\\DSCResourceKit620082014.zip"
destination = "#{ENV['PROGRAMW6432']}\\WindowsPowerShell\\Modules"
}
EOH
end
where
- the remote_file resource is first used to download the
DSCResourceKit620082014.zip
file.
where:
- the remote_file resource is first used to download the
DSCResourceKit620082014.zip
file.
The full syntax for all of the properties that are available to the dsc_script resource is:
dsc_script 'name' do
cwd String
environment Hash
flags Hash
timeout Integer
action Symbol # defaults to :run if not specified
end
where:
dsc_script
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.cwd
,environment
,flags
, andtimeout
are the properties available to this resource.
Actions
The dsc_script resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:run
- (default)
Properties
The dsc_script resource has the following properties:
code
- Ruby Type: String
The code for the DSC configuration script. This property may not be used in conjunction with the
command
property.
command
- Ruby Type: String
The path to a valid Windows PowerShell data file that contains the DSC configuration script. This data file must be capable of running independently of Chef and must generate a valid DSC configuration. This property may not be used in conjunction with the
code
property.
configuration_data
- Ruby Type: String
The configuration data for the DSC script. The configuration data must be a valid Windows PowerShell data file. This property may not be used in conjunction with the
configuration_data_script
property.
configuration_data_script
- Ruby Type: String
The path to a valid Windows PowerShell data file that also contains a node called
localhost
. This property may not be used in conjunction with theconfiguration_data
property.
configuration_name
- Ruby Type: String
The name of a valid Windows PowerShell cmdlet. The name may only contain letter (a-z, A-Z), number (0-9), and underscore (_) characters and should start with a letter. The name may not be null or empty. This property may not be used in conjunction with the
code
property.
cwd
- Ruby Type: String
The current working directory.
environment
- Ruby Type: Hash
A Hash of environment variables in the form of ({‘ENV_VARIABLE’ => ‘VALUE’}). (These variables must exist for a command to be run successfully).
flags
- Ruby Type: Hash
Pass parameters to the DSC script that is specified by the
command
property. Parameters are defined as key-value pairs, where the value of each key is the parameter to pass. This property may not be used in the same recipe as thecode
property. For example:flags ({ :EditorChoice => 'emacs', :EditorFlags => '--maximized' })
.
imports
- Ruby Type: Array
Warning
This property MUST be used with the
code
attribute.Use to import DSC resources from a module.
To import all resources from a module, specify only the module name:
imports 'module_name'
To import specific resources, specify the module name, and then specify the name for each resource in that module to import:
imports 'module_name', 'resource_name_a', 'resource_name_b', ...
For example, to import all resources from a module named
cRDPEnabled
:imports 'cRDPEnabled'
To import only the
PSHOrg_cRDPEnabled
resource:imports 'cRDPEnabled', 'PSHOrg_cRDPEnabled'
timeout
- Ruby Type: Integer
The amount of time (in seconds) a command is to wait before timing out.
ps_credential Helper
Use the ps_credential
helper to embed a PSCredential
object— a
set of security credentials, such as a user name or
password
—within a script, which allows that script to be run using security
credentials.
For example, assuming the CertificateID
is configured in the local
configuration manager, the SeaPower1@3
object is created and embedded
within the seapower-user
script:
dsc_script 'seapower-user' do
code <<-EOH
User AlbertAtom
{
UserName = 'AlbertAtom'
Password = #{ps_credential('SeaPower1@3')}
}
EOH
configuration_data <<-EOH
@{
AllNodes = @(
@{
NodeName = "localhost";
CertificateID = 'A8D1234559F349F7EF19104678908F701D4167'
}
)
}
EOH
end
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the dsc_script resource in recipes:
Specify DSC code directly
DSC data can be specified directly in a recipe:
dsc_script 'emacs' do
code <<-EOH
Environment 'texteditor'
{
Name = 'EDITOR'
Value = 'c:\\emacs\\bin\\emacs.exe'
}
EOH
end
Specify DSC code using a Windows PowerShell data file
Use the command
property to specify the path to a Windows PowerShell
data file. For example, the following Windows PowerShell script defines
the DefaultEditor
:
Configuration 'DefaultEditor'
{
Environment 'texteditor'
{
Name = 'EDITOR'
Value = 'c:\emacs\bin\emacs.exe'
}
}
Use the following recipe to specify the location of that data file:
dsc_script 'DefaultEditor' do
command 'c:\dsc_scripts\emacs.ps1'
end
Pass parameters to DSC configurations
If a DSC script contains configuration data that takes parameters, those
parameters may be passed using the flags
property. For example, the
following Windows PowerShell script takes parameters for the
EditorChoice
and EditorFlags
settings:
$choices = @{'emacs' = 'c:\emacs\bin\emacs';'vi' = 'c:\vim\vim.exe';'powershell' = 'powershell_ise.exe'}
Configuration 'DefaultEditor'
{
[CmdletBinding()]
param
(
$EditorChoice,
$EditorFlags = ''
)
Environment 'TextEditor'
{
Name = 'EDITOR'
Value = "$($choices[$EditorChoice]) $EditorFlags"
}
}
Use the following recipe to set those parameters:
dsc_script 'DefaultEditor' do
flags ({ :EditorChoice => 'emacs', :EditorFlags => '--maximized' })
command 'c:\dsc_scripts\editors.ps1'
end
Use custom configuration data
Configuration data in DSC scripts may be customized from a recipe. For example, scripts are typically customized to set the behavior for Windows PowerShell credential data types. Configuration data may be specified in one of three ways:
- By using the
configuration_data
attribute - By using the
configuration_data_script
attribute - By specifying the path to a valid Windows PowerShell data file
The following example shows how to specify custom configuration data
using the configuration_data
property:
dsc_script 'BackupUser' do
configuration_data <<-EOH
@{
AllNodes = @(
@{
NodeName = "localhost";
PSDscAllowPlainTextPassword = $true
})
}
EOH
code <<-EOH
$user = 'backup'
$password = ConvertTo-SecureString -String "YourPass$(random)" -AsPlainText -Force
$cred = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $user, $password
User $user
{
UserName = $user
Password = $cred
Description = 'Backup operator'
Ensure = "Present"
Disabled = $false
PasswordNeverExpires = $true
PasswordChangeRequired = $false
}
EOH
end
The following example shows how to specify custom configuration data
using the configuration_name
property. For example, the following
Windows PowerShell script defines the vi
configuration:
Configuration 'emacs'
{
Environment 'TextEditor'
{
Name = 'EDITOR'
Value = 'c:\emacs\bin\emacs.exe'
}
}
Configuration 'vi'
{
Environment 'TextEditor'
{
Name = 'EDITOR'
Value = 'c:\vim\bin\vim.exe'
}
}
Use the following recipe to specify that configuration:
dsc_script 'EDITOR' do
configuration_name 'vi'
command 'C:\dsc_scripts\editors.ps1'
end
Using DSC with other Chef resources
The dsc_script resource can be used with other resources. The
following example shows how to download a file using the
remote_file resource, and then uncompress it using the DSC
Archive
resource:
remote_file "#{Chef::Config[:file_cache_path]}\\DSCResourceKit620082014.zip" do
source 'http://gallery.technet.microsoft.com/DSC-Resource-Kit-All-c449312d/file/124481/1/DSC%20Resource%20Kit%20Wave%206%2008282014.zip'
end
dsc_script 'get-dsc-resource-kit' do
code <<-EOH
Archive reskit
{
ensure = 'Present'
path = "#{Chef::Config[:file_cache_path]}\\DSCResourceKit620082014.zip"
destination = "#{ENV['PROGRAMW6432']}\\WindowsPowerShell\\Modules"
}
EOH
end
execute resource
execute resource pageUse 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).
Syntax
An execute resource block typically executes a single command that is unique to the environment in which a recipe will run. Some execute resource commands are run by themselves, but often they are run in combination with other Chef resources. For example, a single command that is run by itself:
execute 'apache_configtest' do
command '/usr/sbin/apachectl configtest'
end
where:
'/usr/sbin/apachectl configtest'
is a command that tests if the configuration files for Apache are valid.Commands are often run in combination with other Chef resources. The following example shows the template resource run with the execute resource to add an entry to a LDAP Directory Interchange Format (LDIF) file:
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
where
'/tmp/something.ldif'
specifies the location of the file'something.ldif'
specifies template file from which/tmp/something.ldif
is created'slapadd < /tmp/something.ldif'
is the command that is run/var/lib/slapd/uid.bdb
prevents the execute resource block from running if that file already exists
The full syntax for all of the properties that are available to the execute resource is:
execute 'name' do
command String, Array # default value: 'name' unless specified
creates String
cwd String
default_env true, false # default value: false
domain String
elevated true, false # default value: false
environment Hash
group String, Integer
input String
live_stream true, false # default value: false
login true, false # default value: false
password String
returns Integer, Array # default value: 0
timeout Integer, String, Float # default value: 3600
user String, Integer
action Symbol # defaults to :run if not specified
end
where:
execute
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.command
,creates
,cwd
,default_env
,domain
,elevated
,environment
,group
,input
,live_stream
,login
,password
,returns
,timeout
, anduser
are the properties available to this resource.
Actions
The execute resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:run
- Run a command. (default)
Properties
The execute resource has the following properties:
command
- Ruby Type: String, Array | Default Value:
The resource block's name
An optional property to set the command to be executed if it differs from the resource block’s name.
Note
Use the execute resource to run a single command. Use multiple execute resource blocks to run multiple commands.
creates
- Ruby Type: String
Prevent a command from creating a file when that file already exists.
cwd
- Ruby Type: String
The current working directory from which the command will be run.
default_env
- Ruby Type: true, false | Default Value:
false
When
true
this enables ENV magic to add path_sanity to the PATH and force the locale to English+UTF-8 for parsing output.New in Chef Client 14.2
domain
- Ruby Type: String
Windows only: The domain of the user specified by the user property. If not specified, the username and password specified by the
user
andpassword
properties will be used to resolve that user against the domain in which the system running Chef Infra 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.New in Chef Client 12.21
elevated
- Ruby Type: true, false | Default Value:
false
Determines whether the script will run with elevated permissions to circumvent User Access Control (UAC) from interactively blocking the process. This will cause the process to be run under a batch login instead of an interactive login. The user running chef-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. Because this requires a login, the user and password properties are required.
New in Chef Client 13.3
environment
- Ruby Type: Hash
A Hash of environment variables in the form of
({'ENV_VARIABLE' => 'VALUE'})
. Note: These variables must exist for a command to be run successfully.
group
- Ruby Type: String, Integer
The group name or group ID that must be changed before running a command.
input
- Ruby Type: String
An optional property to set the input sent to the command as STDIN.
New in Chef Infra Client 16.2
live_stream
- Ruby Type: true, false | Default Value:
false
Send the output of the command run by this execute resource block to the Chef Infra Client event stream.
login
- Ruby Type: true, false | Default Value:
false
Use a login shell to run the commands instead of inheriting the existing execution environment.
New in Chef Infra Client 17.0
password
- Ruby Type: String
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.
New in Chef Client 12.21
returns
- Ruby Type: Integer, Array | Default Value:
0
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.
timeout
- Ruby Type: Integer, String, Float | Default Value:
3600
The amount of time (in seconds) a command is to wait before timing out.
user
- Ruby Type: String, Integer
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.
domain\user
oruser@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.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the execute resource in recipes:
Run a command upon notification:
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:
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:
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:
# 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.
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.
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.
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:
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
# 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.
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:
#{node['python']['binary']} distribute_setup.py #{::File.dirname(pip_binary)}/easy_install pip
Control a service using the execute resource:
Warning
Do something like this:
service 'tomcat' do
action :start
end
and NOT something like this:
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 Infra Language helper to find users:
The following example shows how to use the search
method in the Chef Infra Language to
search for users:
# 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:
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
an action immediately, use :immediately
:
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:
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:
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:
bash 'foo' do
code 'source /tmp/foo.sh'
end
Run a Knife command:
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:
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):
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:
# 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.
# 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
file resource
file resource pageUse 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.
Syntax
A file resource block manages files that exist on nodes. For example, to write the home page for an Apache website:
file '/var/www/customers/public_html/index.php' do
content '<html>This is a placeholder for the home page.</html>'
mode '0755'
owner 'web_admin'
group 'web_admin'
end
where:
'/var/www/customers/public_html/index.php'
is path to the file and also the filename to be managedcontent
defines the contents of the file
The full syntax for all of the properties that are available to the file resource is:
file 'name' do
atomic_update true, false
backup Integer, false # default value: 5
checksum String
content String
force_unlink true, false # default value: false
group Integer, String
inherits true, false # default value: true
manage_symlink_source true, false
mode Integer, String
owner Integer, String
path String # default value: 'name' unless specified
rights Integer, String
verify String, Block, Symbol
action Symbol # defaults to :create if not specified
end
where:
file
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.atomic_update
,backup
,checksum
,content
,force_unlink
,group
,inherits
,manage_symlink_source
,mode
,owner
,path
,rights
, andverify
are properties of this resource, with the Ruby type shown.
Actions
The file resource has the following actions:
:create
- (default) Create a file. If a file already exists (but does not match), update that file to match.
:create_if_missing
- Create a file only if the file does not exist. When the file exists, nothing happens.
:delete
- Delete a file.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:touch
- Touch a file. This updates the access (atime) and file modification (mtime) times for a file.
Properties
The file resource has the following properties:
atomic_update
- Ruby Type: true, false | Default Value:
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.
Perform atomic file updates on a per-resource basis.
Set to
true
for atomic file updates. Set tofalse
for non-atomic file updates.This setting overrides
file_atomic_update
, which is a global setting found in theclient.rb
file.
backup
- Ruby Type: Integer, false | Default Value:
5
The number of backups to be kept in
/var/chef/backup
(for UNIX- and Linux-based platforms) orC:/chef/backup
(for the Microsoft Windows platform).Set to
false
to prevent backups from being kept.
checksum
- Ruby Type: String
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.
content
- Ruby Type: String
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.
force_unlink
- Ruby Type: true, false | Default Value:
false
How Chef Infra 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 Chef Infra Client to delete the non-file target and replace it with the specified file. Set tofalse
for Chef Infra Client to raise an error.
group
- Ruby Type: Integer, String
A string or ID that identifies the group owner by group name or SID, including fully qualified group names such as
domain\group
orgroup@domain
.If this value is not specified, existing groups remain unchanged and new group assignments use the default
POSIX
group (if available).
inherits
- Ruby Type: true, false | Default Value:
true
Microsoft Windows only. Whether a file inherits rights from its parent directory.
manage_symlink_source
- Ruby Type: true, false | Default Value:
true
Change the behavior of the file resource if it is pointed at a symlink.
When this value is set to
true
, Chef Infra 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 tofalse
, Chef Infra Client 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 tofalse
in a future version; setting this explicitly totrue
orfalse
suppresses this warning.
mode
- Ruby Type: Integer, String
A quoted 3-5 character string that defines the octal mode. For example:
'755'
,'0755'
, or00755
.If
mode
is not specified and if the file already exists, the existing mode on the file is used. Ifmode
is not specified, the file does not exist, and the:create
action is specified, Chef Infra Client assumes a mask value of'0777'
and then applies the umask for the system on which the file is to be created to themask
value. For example, if the umask on a system is'022'
, Chef Infra Client uses the default value of'0755'
.The behavior is different depending on the platform.
UNIX- and Linux-based systems: A quoted 3-5 character string that defines the octal mode that is passed to chmod. For example:
'755'
,'0755'
, or00755
. If the value is specified as a quoted string, it works exactly as if thechmod
command was passed. If the value is specified as an integer, prepend a zero (0
) to the value to ensure that it is interpreted as an octal number. For example, to assign read, write, and execute rights for all users, use'0777'
or'777'
; for the same rights, plus the sticky bit, use01777
or'1777'
.Microsoft Windows: A quoted 3-5 character string that defines the octal mode that is translated into rights for Microsoft Windows security. For example:
'755'
,'0755'
, or00755
. Values up to'0777'
are allowed (no sticky bits) and mean the same in Microsoft Windows as they do in UNIX, where4
equalsGENERIC_READ
,2
equalsGENERIC_WRITE
, and1
equalsGENERIC_EXECUTE
.This property cannot be used to set
:full_control
. This property has no effect if not specified, but when it andrights
are both specified, the effects are cumulative.
owner
- Ruby Type: Integer, String
A string or ID that identifies the group owner by user name or SID, including fully qualified user names such as
domain\user
oruser@domain
.If this value is not specified, existing owners remain unchanged and new owner assignments use the current user (when necessary).
path
- Ruby Type: String | Default Value:
The resource block's name
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 Infra Client process. This path can vary from system to system. Therefore, using a path that begins with a forward slash/
is not recommended.
rights
- Ruby Type: Integer, String
Microsoft Windows only. The permissions for users and groups in a Microsoft Windows environment. For example:
rights <permissions>, <principal>, <options>
where<permissions>
specifies the rights granted to the principal,<principal>
is the group or user name, and<options>
is a Hash with one (or more) advanced rights options.
verify
- Ruby Type: String, Block, Symbol
Allows verification of a file’s contents before it is created. Creates a temporary file and then allows execution of commands or Ruby code. If this code evaluates to
true
, the file is created. If the code evaluates tofalse
, an error is raised.The types for this property are a block, string, or a symbol. When specified as a block, it returns
true
orfalse
. When specified as a string, it is executed as a system command. It returnstrue
if the command returns0
as its exit status code andfalse
if the command returns a non-zero exit status code. When using a built-in verifier symbol it returnstrue
if the verifier succeeds else it returnsfalse
.Currently suppported verifiers are
:yaml
,:json
and:systemd_unit
.Note
A block is arbitrary Ruby defined within the resource block by using the
verify
property. When a block returnstrue
, Chef Infra Client will continue to update the file as appropriate.'For example, this should return
true
:file '/tmp/baz' do verify { 1 == 1 } end
This should also return
true
:file '/etc/nginx.conf' do verify 'nginx -t -c %{path}' end
In this example, the
%{path}
portion of this command is expanded to the temporary location where a copy of the file to be created exists. This will use Nginx’s syntax checking feature to ensure the file is a valid Nginx configuration file before writing the file. An error will be raised if the executed command returns a non-zero exit status code.This should return
true
:file '/tmp/foo' do content "hello" verify do |path| open(path).read.include? "hello" end end
Whereas, this should return
false
:file '/tmp/foo' do content "goodbye" verify do |path| open(path).read.include? "hello" end end
When using one of the built-in symbols(
:json
,:yaml
,:systemd_unit
)This should return
true
:file 'foo.json' do content '{"foo": "bar"}' verify :json end
Whereas, this should return
false
:file 'foo.yaml' do content "--- foo: 'foo-" verify :yaml end
If a string, block or symbol returns
false
, the Chef Infra Client run will stop and an error is raised.
Atomic File Updates
Atomic updates are used with file-based resources to help ensure that file updates can be made when updating a binary or if disk space runs out.
Atomic updates are enabled by default. They can be managed globally
using the file_atomic_update
setting in the client.rb
file. They can
be managed for each resource using the atomic_update
property
that is available with the cookbook_file, file,
remote_file, and template resources.
Note
On certain platforms, and after a file has been moved into place, Chef
Infra Client may modify file permissions to support features specific to
those platforms. On platforms with SELinux enabled, Chef Infra Client
will fix up the security contexts after a file has been moved into the
correct location by running the restorecon
command. On the Microsoft
Windows platform, Chef Infra Client will create files so that ACL
inheritance works as expected.
Windows File Security
To support Windows security, the template, file, remote_file, cookbook_file, directory, and remote_directory resources support the use of inheritance and access control lists (ACLs) within recipes. Access Control Lists (ACLs)The rights
property can be used in a recipe to manage access control
lists (ACLs), which allow permissions to be given to multiple users and
groups. Use the rights
property can be used as many times as
necessary; Chef Infra Client will apply them to the file or directory as
required. The syntax for the rights
property is as follows:
rights permission, principal, option_type => value
where
permission
Use to specify which rights are granted to the
principal
. The possible values are::read
,:write
,read_execute
,:modify
,:full_control
, or an integer.Integers used for permissions must match the following list FileSystemRights Enum fields.
These permissions are cumulative. If
:write
is specified, then it includes:read
. If:full_control
is specified, then it includes both:write
and:read
.(For those who know the Windows API:
:read
corresponds toGENERIC_READ
;:write
corresponds toGENERIC_WRITE
;:read_execute
corresponds toGENERIC_READ
andGENERIC_EXECUTE
;:modify
corresponds toGENERIC_WRITE
,GENERIC_READ
,GENERIC_EXECUTE
, andDELETE
;:full_control
corresponds toGENERIC_ALL
, which allows a user to change the owner and other metadata about a file.)principal
Use to specify a group or user. The principal can be specified by either name or SID. When using name, this is identical to what is entered in the login box for Windows, such as
user_name
,domain\user_name
, oruser_name@fully_qualified_domain_name
. When using a SID, you may use either the standard string representation of a SID (S-R-I-S-S) or one of the SDDL string constants. Chef Infra Client does not need to know if a principal is a user or a group.option_type
A hash that contains advanced rights options. For example, the rights to a directory that only applies to the first level of children might look something like:
rights :write, 'domain\group_name', :one_level_deep => true
.Possible option types:
:applies_to_children
Specify how permissions are applied to children. Possible values:
true
to inherit both child directories and files;false
to not inherit any child directories or files;:containers_only
to inherit only child directories (and not files);:objects_only
to recursively inherit files (and not child directories).:applies_to_self
Indicates whether a permission is applied to the parent directory. Possible values:
true
to apply to the parent directory or file and its children;false
to not apply only to child directories and files.:one_level_deep
Indicates the depth to which permissions will be applied. Possible values:
true
to apply only to the first level of children;false
to apply to all children.
For example:
resource 'x.txt' do
rights :read, 'S-1-1-0'
rights :write, 'domain\group'
rights :full_control, 'group_name_or_user_name'
rights :full_control, 'user_name', applies_to_children: true
end
or:
rights :read, %w(Administrators Everyone)
rights :full_control, 'Users', applies_to_children: true
rights :write, 'Sally', applies_to_children: :containers_only, applies_to_self: false, one_level_deep: true
Some other important things to know when using the rights
attribute:
- Only inherited rights remain. All existing explicit rights on the object are removed and replaced.
- If rights are not specified, nothing will be changed. Chef Infra Client does not clear out the rights on a file or directory if rights are not specified.
- Changing inherited rights can be expensive. Windows will propagate rights to all children recursively due to inheritance. This is a normal aspect of Windows, so consider the frequency with which this type of action is necessary and take steps to control this type of action if performance is the primary consideration.
Use the deny_rights
property to deny specific rights to specific
users. The ordering is independent of using the rights
property. For
example, it doesn’t matter if rights are granted to everyone is placed
before or after deny_rights :read, ['Julian', 'Lewis']
, both Julian
and Lewis will be unable to read the document. For example:
resource 'x.txt' do
rights :read, 'Everyone'
rights :write, 'domain\group'
rights :full_control, 'group_name_or_user_name'
rights :full_control, 'user_name', applies_to_children: true
deny_rights :read, %w(Julian Lewis)
end
or:
deny_rights :full_control, ['Sally']
By default, a file or directory inherits rights from its parent
directory. Most of the time this is the preferred behavior, but
sometimes it may be necessary to take steps to more specifically control
rights. The inherits
property can be used to specifically tell Chef
Infra Client to apply (or not apply) inherited rights from its parent
directory.
For example, the following example specifies the rights for a directory:
directory 'C:\mordor' do
rights :read, 'MORDOR\Minions'
rights :full_control, 'MORDOR\Sauron'
end
and then the following example specifies how to use inheritance to deny access to the child directory:
directory 'C:\mordor\mount_doom' do
rights :full_control, 'MORDOR\Sauron'
inherits false # Sauron is the only person who should have any sort of access
end
If the deny_rights
permission were to be used instead, something could
slip through unless all users and groups were denied.
Another example also shows how to specify rights for a directory:
directory 'C:\mordor' do
rights :read, 'MORDOR\Minions'
rights :full_control, 'MORDOR\Sauron'
rights :write, 'SHIRE\Frodo' # Who put that there I didn't put that there
end
but then not use the inherits
property to deny those rights on a child
directory:
directory 'C:\mordor\mount_doom' do
deny_rights :read, 'MORDOR\Minions' # Oops, not specific enough
end
Because the inherits
property is not specified, Chef Infra Client will
default it to true
, which will ensure that security settings for
existing files remain unchanged.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the file resource in recipes:
Create a file
file '/tmp/something' do
owner 'root'
group 'root'
mode '0755'
action :create
end
Create a file in Microsoft Windows
To create a file in Microsoft Windows, be sure to add an escape
character—\
—before the backslashes in the paths:
file 'C:\\tmp\\something.txt' do
rights :read, 'Everyone'
rights :full_control, 'DOMAIN\\User'
action :create
end
Remove a file
file '/tmp/something' do
action :delete
end
Set file modes
file '/tmp/something' do
mode '0755'
end
Delete a repository using yum to scrub the cache
# 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
notifies :create, 'ruby_block[reload-internal-yum-cache]', :immediately
end
Add the value of a data bag item to a file
The following example shows how to get the contents of a data bag item
named impossible_things
, create a .pem file located at
some/directory/path/
, and then use the content
attribute to update
the contents of that file with the value of the impossible_things
data
bag item:
private_key = data_bag_item('impossible_things', private_key_name)['private_key']
file "some/directory/path/#{private_key_name}.pem" do
content private_key
owner 'root'
group 'group'
mode '0755'
end
Write a YAML file
The following example shows how to use the content
property to write a
YAML file:
file "#{app['deploy_to']}/shared/config/settings.yml" do
owner "app['owner']"
group "app['group']"
mode '0755'
content app.to_yaml
end
Write a string to a file
The following example specifies a directory, and then uses the content
property to add a string to the file created in that directory:
status_file = '/path/to/file/status_file'
file status_file do
owner 'root'
group 'root'
mode '0755'
content 'My favourite foremost coastal Antarctic shelf, oh Larsen B!'
end
Create a file from a copy
The following example shows how to copy a file from one directory to another, locally on a node:
file '/root/1.txt' do
content IO.read('/tmp/1.txt')
action :create
end
where the content
attribute uses the Ruby IO.read
method to get the
contents of the /tmp/1.txt
file.
freebsd_package resource
freebsd_package resource pageUse the freebsd_package resource to manage packages for the FreeBSD platform.
Note
Syntax
A freebsd_package resource block manages a package on a node, typically by installing it. The simplest use of the freebsd_package resource is:
freebsd_package 'package_name'
which will install the named package using all of the default options
and the default action (:install
).
The full syntax for all of the properties that are available to the freebsd_package resource is:
freebsd_package 'name' do
options String, Array
package_name String, Array
source String
timeout String, Integer
version String, Array
action Symbol # defaults to :install if not specified
end
where:
freebsd_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.options
,package_name
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The freebsd_package resource has the following actions:
:install
- (default) Install a package. If a version is specified, install the specified version of the package.
:remove
- Remove a package.
Properties
The freebsd_package resource has the following properties:
options
- Ruby Type: String, Array
One (or more) additional command options that are passed to the command.
package_name
- Ruby Type: String, Array
An optional property to set the package name if it differs from the resource block’s name.
source
- Ruby Type: String
The optional path to a package on the local file system.
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String, Array
The version of a package to be installed or upgraded.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the freebsd_package resource in recipes:
Install a package
freebsd_package 'name of package' do
action :install
end
gem_package resource
gem_package resource pageUse the gem_package resource to manage gem packages that are only included in recipes. When a gem is installed from a local file, it must be added to the node using the remote_file or cookbook_file resources.
Note
The gem_package resource must be specified as gem_package
and cannot be shortened to package
in a recipe.
Warning
The chef_gem and gem_package resources are both used to install Ruby gems. For any machine on which Chef Infra Client is installed, there are two instances of Ruby. One is the standard, system-wide instance of Ruby and the other is a dedicated instance that is available only to Chef Infra Client. Use the chef_gem resource to install gems into the instance of Ruby that is dedicated to Chef Infra Client. Use the gem_package resource to install all other gems (i.e. install gems system-wide).
Syntax
The full syntax for all of the properties that are available to the gem_package resource is:
gem_package 'name' do
clear_sources true, false
gem_binary String
include_default_source true, false
options String, Hash, Array
package_name String
source String, Array
timeout String, Integer
version String
action Symbol # defaults to :install if not specified
end
where:
gem_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.clear_sources
,gem_binary
,include_default_source
,options
,package_name
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The gem_package resource has the following actions:
:install
- Install a package. If a version is specified, install the specified version of the package. (default)
:purge
- Purge a package. This action typically removes the configuration files as well as the package.
:remove
- Remove a package.
:upgrade
- Install a package and/or ensure that a package is the latest version.
Properties
The gem_package resource has the following properties:
clear_sources
- Ruby Type: true, false | Default Value:
false unless `clear_gem_sources` set to true in the `client.rb` config.
Set to
true
to download a gem from the path specified by thesource
property (and not from RubyGems).
gem_binary
- Ruby Type: String
The path of a gem binary to use for the installation. By default, the same version of Ruby that is used by Chef Infra Client will be used.
include_default_source
- Ruby Type: true, false
Set to
false
to not includeChef::Config[:rubygems_url]
in the sources.New in Chef Client 13.0
options
- Ruby Type: String, Hash, Array
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.
package_name
- Ruby Type: String
An optional property to set the package name if it differs from the resource block’s name.
source
- Ruby Type: String, Array
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.
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String
The version of a package to be installed or upgraded.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the gem_package resource in recipes:
The following examples demonstrate various approaches for using the gem_package resource in recipes:
Install a gem file from the local file system
gem_package 'loofah' do
source '/tmp/loofah-2.7.0.gem'
action :install
end
Use the ignore_failure
common attribute
gem_package 'syntax' do
action :install
ignore_failure true
end
git resource
git resource pageUse 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.
Syntax
A git resource block manages source control resources that exist in a git repository:
git "#{Chef::Config[:file_cache_path]}/app_name" do
repository node[:app_name][:git_repository]
revision node[:app_name][:git_revision]
action :sync
end
The full syntax for all of the properties that are available to the git resource is:
git 'name' do
additional_remotes Hash # default value: {}
checkout_branch String
depth Integer
destination String # default value: 'name' unless specified
enable_checkout true, false # default value: true
enable_submodules true, false # default value: false
environment Hash
group String, Integer
remote String # default value: "origin"
repository String
revision String # default value: "HEAD"
ssh_wrapper String
timeout Integer
user String, Integer
action Symbol # defaults to :sync if not specified
end
where:
git
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.additional_remotes
,checkout_branch
,depth
,destination
,enable_checkout
,enable_submodules
,environment
,group
,remote
,repository
,revision
,ssh_wrapper
,timeout
, anduser
are the properties available to this resource.
Actions
The git resource has the following actions:
:checkout
- Clone or check out the source. When a checkout is available, this provider does nothing.
:export
- Export the source, excluding or removing any version control artifacts.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:sync
- (default) Update the source to the specified version, or get a new clone or checkout. This action causes a hard reset of the index and working tree, discarding any uncommitted changes.
Properties
The git resource has the following properties:
additional_remotes
- Ruby Type: Hash | Default Value:
{}
A Hash of additional remotes that are added to the git repository configuration.
checkout_branch
- Ruby Type: String
Do a one-time checkout from git or use when a branch in the upstream repository is named
deploy
. To prevent the git resource from attempting to check out master from master, setenable_checkout
tofalse
when using thecheckout_branch
property. Seerevision
.
depth
- Ruby Type: Integer
The number of past revisions to be included in the git shallow clone. Unless specified the default behavior will do a full clone.
destination
- Ruby Type: String | Default Value:
The resource block's name
The location path to which the source is to be cloned, checked out, or exported. Default value: the name of the resource block.
enable_checkout
- Ruby Type: true, false | Default Value:
true
Check out a repo from master. Set to
false
when using thecheckout_branch
attribute to prevent the git resource from attempting to check outmaster
frommaster
.
enable_submodules
- Ruby Type: true, false | Default Value:
false
Perform a sub-module initialization and update.
environment
- Ruby Type: Hash
A Hash of environment variables in the form of
({"ENV_VARIABLE" => "VALUE"})
. (These variables must exist for a command to be run successfully.)Note
The git provider automatically sets the
ENV['HOME']
andENV['GIT_SSH']
environment variables. To override this behavior and provide different values, addENV['HOME']
and/orENV['GIT_SSH']
to theenvironment
Hash.
group
- Ruby Type: String, Integer
The system group that will own the checked-out code.
remote
- Ruby Type: String | Default Value:
origin
The remote repository to use when synchronizing an existing clone.
repository
- Ruby Type: String
The URI of the code repository.
revision
- Ruby Type: String | Default Value:
HEAD
A branch, tag, or commit to be synchronized with git. This can be symbolic, like
HEAD
or it can be a source control management-specific revision identifier. Seecheckout_branch
.The value of the
revision
attribute may change over time. From one branch to another, to a tag, to a specific SHA for a commit, and then back to a branch. Therevision
attribute may even be changed in a way where history gets rewritten.Instead of tracking a specific branch or doing a headless checkout, Chef Infra Client maintains its own branch (via the git resource) that does not exist in the upstream repository. Chef Infra Client is then free to forcibly check out this branch to any commit without destroying the local history of an existing branch.
For example, to explicitly track an upstream repository’s master branch:
revision 'master'
Use the
git rev-parse
andgit ls-remote
commands to verify that Chef Infra Client is synchronizing commits correctly. (Chef Infra Client always runsgit ls-remote
on the upstream repository to verify the commit is made to the correct repository.)
ssh_wrapper
- Ruby Type: String
The path to the wrapper script used when running SSH with git. The
GIT_SSH
environment variable is set to this.
timeout
- Ruby Type: Integer
The amount of time (in seconds) to wait for a command to execute before timing out. When this property is specified using the deploy resource, the value of the
timeout
property is passed from the deploy resource to the git resource.
user
- Ruby Type: String, Integer | Default Value:
`HOME` environment variable of the user running chef-client
The system user that will own the checked-out code.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the git resource in recipes:
Use the git mirror
git '/opt/my_sources/couch' do
repository 'git://git.apache.org/couchdb.git'
revision 'master'
action :sync
end
Use different branches
To use different branches, depending on the environment of the node:
branch_name = if node.chef_environment == 'QA'
'staging'
else
'master'
end
git '/home/user/deployment' do
repository 'git@github.com:git_site/deployment.git'
revision branch_name
action :sync
user 'user'
group 'test'
end
Where the branch_name
variable is set to staging or master, depending on the environment of the node. Once this is determined, the branch_name
variable is used to set the revision for the repository. If the git status command is used after running the example above, it will return the branch name as deploy
, as this is the default value. Run Chef Infra Client in debug mode to verify that the correct branches are being checked out:
sudo chef-client -l debug
Install an application from git using bash
The following example shows how Bash can be used to install a plug-in for rbenv named ruby-build, which is located in git version source control. First, the application is synchronized, and then Bash changes its working directory to the location in which ruby-build is located, and then runs a command.
git "/Users/tsmith/.chef/cache/ruby-build" do
repository 'git://github.com/rbenv/ruby-build.git'
revision 'master'
action :sync
end
bash 'install_ruby_build' do
cwd "/Users/tsmith/.chef/cache/ruby-build"
user 'rbenv'
group 'rbenv'
code <<-EOH
./install.sh
EOH
environment 'PREFIX' => '/usr/local'
end
Notify a resource post-checkout
git "/Users/tsmith/.chef/cache/my_app" do
repository node['my_app']['git_repository']
revision node['my_app']['git_revision']
action :sync
notifies :run, 'bash[compile_my_app]', :immediately
end
Pass in environment variables
git '/opt/my_sources/couch' do
repository 'git://git.apache.org/couchdb.git'
revision 'master'
environment 'VAR' => 'whatever'
action :sync
end
group resource
group resource pageUse the group resource to manage a local group.
Syntax
The full syntax for all of the properties that are available to the group resource is:
group 'name' do
append true, false # default value: false
comment String
excluded_members String, Array # default value: []
gid String, Integer
group_name String # default value: 'name' unless specified
members String, Array # default value: []
non_unique true, false # default value: false
system true, false # default value: false
action Symbol # defaults to :create if not specified
end
where:
group
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.append
,comment
,excluded_members
,gid
,group_name
,members
,non_unique
, andsystem
are the properties available to this resource.
Actions
The group resource has the following actions:
:create
- (default) Create a group. If a group already exists (but does not match), update that group to match.
:manage
- Manage an existing group. This action does nothing if the group does not exist.
:modify
- Modify an existing group. This action raises an exception if the group does not exist.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove a group.
Properties
The group resource has the following properties:
append
- Ruby Type: true, false | Default Value:
false
How members should be appended and/or removed from a group. When true,
members
are appended andexcluded_members
are removed. Whenfalse
, group members are reset to the value of themembers
property.
comment
- Ruby Type: String
Specifies a comment to associate with the local group.
New in Chef Client 14.9
excluded_members
- Ruby Type: String, Array | Default Value:
[]
Remove users from a group. May only be used when
append
is set totrue
.
gid
- Ruby Type: String, Integer
The identifier for the group.
group_name
- Ruby Type: String | Default Value:
The resource block's name
The name of the group. Default value: the
name
of the resource block. See “Syntax” section above for more information.
members
- Ruby Type: String, Array | Default Value:
[]
Which users should be set or appended to a group. When more than one group member is identified, the list of members should be an array:
members ['user1', 'user2']
.
non_unique
- Ruby Type: true, false | Default Value:
false
Allow gid duplication. May only be used with the
Groupadd
user resource provider.
system
- Ruby Type: true, false | Default Value:
false
Set to
true
if the group belongs to a system group.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the group resource in recipes:
The following examples demonstrate various approaches for using the group resource in recipes:
Append users to groups:
group 'www-data' do
action :modify
members 'maintenance'
append true
end
Add a user to group on the Windows platform:
group 'Administrators' do
members ['domain\foo']
append true
action :modify
end
habitat_config resource
habitat_config resource pageUse the habitat_config resource to apply a configuration to a Chef Habitat service.
New in Chef Infra Client 17.3.
Syntax
The full syntax for all of the properties that are available to the habitat_config resource is:
habitat_config 'name' do
config Mash (Hash-like)
gateway_auth_token String
remote_sup String # default value: "127.0.0.1:9632"
remote_sup_http String # default value: "127.0.0.1:9631"
service_group String # default value: 'name' unless specified
user String
action Symbol # defaults to :apply if not specified
end
where:
habitat_config
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.config
,gateway_auth_token
,remote_sup
,remote_sup_http
,service_group
, anduser
are the properties available to this resource.
Actions
The habitat_config resource has the following actions:
:apply
- applies the given configuration (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The habitat_config resource has the following properties:
config
- Ruby Type: Mash (Hash-like) |
REQUIRED
The configuration to apply as a ruby hash, for example,
{ worker_count: 2, http: { keepalive_timeout: 120 } }
.
gateway_auth_token
- Ruby Type: String
Auth token for accessing the remote supervisor’s http port.
remote_sup
- Ruby Type: String | Default Value:
127.0.0.1:9632
Address to a remote supervisor’s control gateway.
remote_sup_http
- Ruby Type: String | Default Value:
127.0.0.1:9631
Address for remote supervisor http port. Used to pull existing.
service_group
- Ruby Type: String | Default Value:
The resource block's name
The service group to apply the configuration to. For example,
nginx.default
user
- Ruby Type: String
Name of user key to use for encryption. Passes
--user
tohab config apply
.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the habitat_config resource in recipes:
Configure your nginx defaults
habitat_config 'nginx.default' do
config({
worker_count: 2,
http: {
keepalive_timeout: 120
}
})
end
habitat_install resource
habitat_install resource pageUse the habitat_install resource to install Chef Habitat.
New in Chef Infra Client 17.3.
Syntax
The full syntax for all of the properties that are available to the habitat_install resource is:
habitat_install 'name' do
bldr_url String
create_user true, false # default value: true
hab_version String
install_url String
license String
tmp_dir String
action Symbol # defaults to :install if not specified
end
where:
habitat_install
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.bldr_url
,create_user
,hab_version
,install_url
,license
, andtmp_dir
are the properties available to this resource.
Actions
The habitat_install resource has the following actions:
:install
- Installs Habitat. Does nothing if the
hab
binary is found in the default location for the system (/bin/hab
on Linux,/usr/local/bin/hab
on macOS,C:/habitat/hab.exe
on Windows) (default) :nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The habitat_install resource has the following properties:
bldr_url
- Ruby Type: String
Optional URL to an alternate Habitat Builder.
create_user
- Ruby Type: true, false | Default Value:
true
Creates the
hab
system user.
hab_version
- Ruby Type: String
Specify the version of
Habitat
you would like to install.
install_url
- Ruby Type: String | Default Value:
https://raw.githubusercontent.com/habitat-sh/habitat/main/components/hab/install.sh
URL to the install script, default is from the habitat repo .
license
- Ruby Type: StringAllowed Values:
"accept"
Specifies acceptance of habitat license when set to
accept
.
tmp_dir
- Ruby Type: String
Sets TMPDIR environment variable for location to place temp files.
Note
This is required if
/tmp
and/var/tmp
are mountednoexec
.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the habitat_install resource in recipes:
Installation Without a Resource Name
habitat_install
Installation specifying a habitat builder URL
habitat_install 'install habitat' do
bldr_url 'http://localhost'
end
Installation specifying version and habitat builder URL
habitat_install 'install habitat' do
bldr_url 'http://localhost'
hab_version '1.5.50'
end
habitat_package resource
habitat_package resource pageUse the habitat_package to install or remove Chef Habitat packages from Habitat Builder.
New in Chef Infra Client 17.3.
Syntax
The full syntax for all of the properties that are available to the habitat_package resource is:
habitat_package 'name' do
auth_token String
binlink true, false, force # default value: false
bldr_url String # default value: "https://bldr.habitat.sh"
channel String # default value: "stable"
exclude String
keep_latest String
no_deps true, false # default value: false
options String
package_name String, Array
source String
timeout String, Integer
version String, Array
action Symbol # defaults to :install if not specified
end
where:
habitat_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.auth_token
,binlink
,bldr_url
,channel
,exclude
,keep_latest
,no_deps
,options
,package_name
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The habitat_package resource has the following actions:
:install
- Install a package. If a version is specified, install the specified version of the package. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:purge
- Purge a package. This action typically removes the configuration files as well as the package.
:reconfig
- Change the installed package
:remove
- Remove a package.
:upgrade
- Install a package and ensure that a package is the latest version.
Properties
The habitat_package resource has the following properties:
auth_token
- Ruby Type: String
Auth token for installing a package from a private organization on Habitat builder.
binlink
- Ruby Type: true, false, force | Default Value:
false
If habitat should attempt to binlink the package. Acceptable values:
true
,false
,:force
. Will fail on binlinking if set totrue
and binary or binlink exists.
bldr_url
- Ruby Type: String | Default Value:
https://bldr.habitat.sh
The habitat builder url where packages will be downloaded from. Defaults to public Habitat Builder
channel
- Ruby Type: String | Default Value:
stable
The release channel to install your package from.
exclude
- Ruby Type: String
Identifier of one or more packages that should not be uninstalled. (ex: core/redis, core/busybox-static/1.42.2/21120102031201)
keep_latest
- Ruby Type: String
Ability to uninstall while retaining a specified version This feature only works in Habitat 1.5.86+.
no_deps
- Ruby Type: true, false | Default Value:
false
Remove package but retain dependencies.
options
- Ruby Type: String
Pass any additional parameters to the habitat package command.
package_name
- Ruby Type: String, Array
An optional property to set the package name if it differs from the resource block’s name.
source
- Ruby Type: String
The optional path to a package on the local file system.
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String, Array
The version of a package to be installed or upgraded.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the habitat_package resource in recipes:
Install core/redis
habitat_package 'core/redis'
Install specific version of a package from the unstable channel
habitat_package 'core/redis' do
version '3.2.3'
channel 'unstable'
end
Install a package with specific version and revision
habitat_package 'core/redis' do
version '3.2.3/20160920131015'
end
Install a package and force linking it’s binary files to the system path
habitat_package 'core/nginx' do
binlink :force
end
Install a package and link it’s binary files to the system path
habitat_package 'core/nginx' do
options '--binlink'
end
Remove package and all of it’s versions
habitat_package 'core/nginx'
action :remove
end
Remove specified version of a package
habitat_package 'core/nginx/3.2.3'
action :remove
end
Remove package but retain some versions Note: Only available as of Habitat 1.5.86
habitat_package 'core/nginx'
keep_latest '2'
action :remove
end
**Remove package but keep dependencies**
habitat_package 'core/nginx'
no_deps false
action :remove
end
habitat_service resource
habitat_service resource pageUse the habitat_service resource to manage Chef Habitat services. This requires that core/hab-sup
be running as a service. See the habitat_sup
resource documentation for more information.
Note
Applications may run as a specific user. Often with Habitat, the default is hab
, or root
. If the application requires another user, then it should be created with Chef’s user
resource.
New in Chef Infra Client 17.3.
Syntax
The full syntax for all of the properties that are available to the habitat_service resource is:
habitat_service 'name' do
bind String, Array # default value: []
binding_mode Symbol, String # default value: :strict
bldr_url String # default value: "https://bldr.habitat.sh/"
channel Symbol, String # default value: :stable
gateway_auth_token String
health_check_interval Integer # default value: 30
remote_sup String # default value: "127.0.0.1:9632"
remote_sup_http String # default value: "127.0.0.1:9631"
service_group String # default value: "default"
service_name String # default value: 'name' unless specified
shutdown_timeout Integer # default value: 8
strategy Symbol, String # default value: :none
topology Symbol, String # default value: :standalone
update_condition Symbol, String # default value: :latest
action Symbol # defaults to :load if not specified
end
where:
habitat_service
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.bind
,binding_mode
,bldr_url
,channel
,gateway_auth_token
,health_check_interval
,remote_sup
,remote_sup_http
,service_group
,service_name
,shutdown_timeout
,strategy
,topology
, andupdate_condition
are the properties available to this resource.
Actions
The habitat_service resource has the following actions:
:load
- (default action) runs
hab service load
to load and start the specified application service (default) :nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:reload
- runs the
:unload
and then:load
actions :restart
- runs the
:stop
and then:start
actions :start
- runs
hab service start
to start the specified application service :stop
- runs
hab service stop
to stop the specified application service :unload
- runs
hab service unload
to unload and stop the specified application service
Properties
The habitat_service resource has the following properties:
bind
- Ruby Type: String, Array | Default Value:
[]
Passes
--bind
with the specified services to bind to the hab command. If an array of multiple service binds are specified then a--bind
flag is added for each.
binding_mode
- Ruby Type: Symbol, String | Default Value:
:strict
Allowed Values::strict, "strict", :relaxed, "relaxed"
Passes
--binding-mode
with the specified binding mode. Defaults to:strict
. Options are:strict
or:relaxed
bldr_url
- Ruby Type: String | Default Value:
https://bldr.habitat.sh/
Passes
--url
with the specified Habitat Builder URL to the hab command. Depending on the type of Habitat Builder you are connecting to, this URL will look different, here are the 3 current types: - Public Habitat Builder (default) -https://bldr.habitat.sh
- On-Prem Habitat Builder installed using the Source Install Method -https://your.bldr.url
- On-Prem Habitat Builder installed using the Automate Installer -https://your.bldr.url/bldr/v1
channel
- Ruby Type: Symbol, String | Default Value:
:stable
Passes
--channel
with the specified channel to the hab command
gateway_auth_token
- Ruby Type: String
Auth token for accessing the remote supervisor’s http port.
health_check_interval
- Ruby Type: Integer | Default Value:
30
The interval (seconds) on which to run health checks.
remote_sup
- Ruby Type: String | Default Value:
127.0.0.1:9632
Address to a remote Supervisor’s Control Gateway
remote_sup_http
- Ruby Type: String | Default Value:
127.0.0.1:9631
IP address and port used to communicate with the remote supervisor. If this value is invalid, the resource will update the supervisor configuration each time Chef Infra Server runs.
service_group
- Ruby Type: String | Default Value:
default
Passes
--group
with the specified service group to the hab command
service_name
- Ruby Type: String | Default Value:
The resource block's name
The name of the service, must be in the form of
origin/name
shutdown_timeout
- Ruby Type: Integer | Default Value:
8
The timeout in seconds allowed during shutdown.
strategy
- Ruby Type: Symbol, String | Default Value:
:none
Allowed Values::none, "none", :"at-once", "at-once", :rolling, "rolling"
Passes
--strategy
with the specified update strategy to the hab command. Defaults to:none
. Other options are:'at-once'
and:rolling
topology
- Ruby Type: Symbol, String | Default Value:
:standalone
Allowed Values::standalone, "standalone", :leader, "leader"
Passes
--topology
with the specified service topology to the hab command
update_condition
- Ruby Type: Symbol, String | Default Value:
:latest
Allowed Values::latest, "latest", :"track-channel", "track-channel"
Passes
--update-condition
dictating when this service should updated. Defaults tolatest
. Options arelatest
ortrack-channel
**_Note
This requires a minimum habitat version of 1.5.71_** -
latest
: Runs the latest package that can be found in the configured channel and local packages. -track-channel
: Always run the package at the head of a given channel. This enables service rollback, where demoting a package from a channel will cause the package to rollback to an older version of the package. A ramification of enabling this condition is that packages that are newer than the package at the head of the channel are also uninstalled during a service rollback.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the habitat_service resource in recipes:
Install and load nginx
habitat_package 'core/nginx'
habitat_service 'core/nginx'
habitat_service 'core/nginx unload' do
service_name 'core/nginx'
action :unload
end
Pass the strategy
and topology
options to hab service commands
habitat_service 'core/redis' do
strategy 'rolling'
topology 'standalone'
end
Using update_condition
habitat_service 'core/redis' do
strategy 'rolling'
update_condition 'track-channel'
topology 'standalone'
end
If the service has it’s own user specified that is not the hab
user, don’t create the hab
user on install, and instead create the application user with Chef’s user
resource
habitat_install 'install habitat' do
create_user false
end
user 'acme-apps' do
system true
end
habitat_service 'acme/apps'
habitat_sup resource
habitat_sup resource pageUse the habitat_sup resource to runs a Chef Habitat supervisor for one or more Chef Habitat services. The resource is commonly used in conjunction with habitat_service
which will manage the services loaded and started within the supervisor.
New in Chef Infra Client 17.3.
Syntax
The full syntax for all of the properties that are available to the habitat_sup resource is:
habitat_sup 'name' do
auth_token String
auto_update true, false # default value: false
bldr_url String
event_stream_application String
event_stream_cert String
event_stream_environment String
event_stream_site String
event_stream_token String
event_stream_url String
gateway_auth_token String
hab_channel String
health_check_interval String, Integer
keep_latest String
launcher_version String
license String
limit_no_files String
listen_ctl String
listen_gossip String
listen_http String
org String # default value: "default"
peer String, Array
permanent_peer true, false # default value: false
ring String
service_version String
sup_version String
toml_config true, false # default value: false
update_condition String
action Symbol # defaults to :run if not specified
end
where:
habitat_sup
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.auth_token
,auto_update
,bldr_url
,event_stream_application
,event_stream_cert
,event_stream_environment
,event_stream_site
,event_stream_token
,event_stream_url
,gateway_auth_token
,hab_channel
,health_check_interval
,keep_latest
,launcher_version
,license
,limit_no_files
,listen_ctl
,listen_gossip
,listen_http
,org
,peer
,permanent_peer
,ring
,service_version
,sup_version
,toml_config
, andupdate_condition
are the properties available to this resource.
Actions
The habitat_sup resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:run
- The
run
action handles installing Habitat using thehabitat_install
resource, ensures that the appropriate versions of thecore/hab-sup
andcore/hab-launcher
packages are installed usinghabitat_package
, and then drops off the appropriate init system definitions and manages the service. (default) :stop
Properties
The habitat_sup resource has the following properties:
auth_token
- Ruby Type: String
Auth token for accessing a private organization on bldr. This value is templated into the appropriate service file.
auto_update
- Ruby Type: true, false | Default Value:
false
Passes
--auto-update
. This will set the Habitat supervisor to automatically update itself any time a stable version has been released.
bldr_url
- Ruby Type: String
The Habitat Builder URL for the
habitat_package
resource, if needed.
event_stream_application
- Ruby Type: String
The name of your application that will be displayed in the Chef Automate Applications Dashboard.
event_stream_cert
- Ruby Type: String
With
Intermediary Certificates
or, Automate 2 being set to use TLS with a valid cert, you will need to provideHabitat
with your certificate for communication with Automate to work. Follow these steps!.
event_stream_environment
- Ruby Type: String
The application environment for the supervisor, this is for grouping in the Applications Dashboard.
event_stream_site
- Ruby Type: String
Application Dashboard label for the ‘site’ of the application - can be filtered in the dashboard.
event_stream_token
- Ruby Type: String
Chef Automate token for sending application event stream data.
event_stream_url
- Ruby Type: String
AUTOMATE_HOSTNAME:4222
- the Chef Automate URL with port 4222 specifiedNote
The port can be changed if needed.
gateway_auth_token
- Ruby Type: String
Auth token for accessing the supervisor’s HTTP gateway. This value is templated into the appropriate service file.
hab_channel
- Ruby Type: String
The channel to install Habitat from. Defaults to stable
health_check_interval
- Ruby Type: String, Integer
The interval (seconds) on which to run health checks.
keep_latest
- Ruby Type: String
Automatically cleans up old packages. If this flag is enabled, service startup will initiate an uninstall of all previous versions of the associated package. This also applies when a service is restarted due to an update. If a number is passed to this argument, that number of latest versions will be kept. The same logic applies to the Supervisor package
env:HAB_KEEP_LATEST_PACKAGES=1
Note
This requires Habitat version
1.5.86+
launcher_version
- Ruby Type: String
Allows you to choose which version of launcher to install.
license
- Ruby Type: StringAllowed Values:
"accept"
Specifies acceptance of habitat license when set to
accept
.
limit_no_files
- Ruby Type: String
allows you to set LimitNOFILE in the systemd service when used
Note
Linux Only.
listen_ctl
- Ruby Type: String
Only valid for
:run
action, passes--listen-ctl
with the specified address and port, e.g.,0.0.0.0:9632
, to the hab command.
listen_gossip
- Ruby Type: String
Only valid for
:run
action, passes--listen-gossip
with the specified address and port, e.g.,0.0.0.0:9638
, to the hab command.
listen_http
- Ruby Type: String
Only valid for
:run
action, passes--listen-http
with the specified address and port, e.g.,0.0.0.0:9631
, to the hab command.
org
- Ruby Type: String | Default Value:
default
Only valid for
:run
action, passes--org
with the specified org name to the hab command.
peer
- Ruby Type: String, Array
Only valid for
:run
action, passes--peer
with the specified initial peer to the hab command.
permanent_peer
- Ruby Type: true, false | Default Value:
false
Only valid for
:run
action, passes--permanent-peer
to the hab command.
ring
- Ruby Type: String
Only valid for
:run
action, passes--ring
with the specified ring key name to the hab command.
service_version
- Ruby Type: String
Allows you to choose which version of the Windows Service to install.
sup_version
- Ruby Type: String
Allows you to choose which version of supervisor you would like to install.
Note
If a version is provided, it will also install that version of habitat if not previously installed.
toml_config
- Ruby Type: true, false | Default Value:
false
Supports using the Supervisor toml configuration instead of passing exec parameters to the service, reference.
update_condition
- Ruby Type: String
Passes
--update-condition
dictating when this service should updated. Defaults tolatest
. Options arelatest
ortrack-channel
**_Note
This requires a minimum habitat version of 1.5.71_** -
latest
: Runs the latest package that can be found in the configured channel and local packages. -track-channel
: Always run what is at the head of a given channel. This enables service rollback where demoting a package from a channel will cause the package to rollback to an older version of the package. A ramification of enabling this condition is packages newer than the package at the head of the channel will be automatically uninstalled during a service rollback.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the habitat_sup resource in recipes:
Set up with just the defaults
habitat_sup 'default'
Update listen ports and use Supervisor toml config
habitat_sup 'test-options' do
listen_http '0.0.0.0:9999'
listen_gossip '0.0.0.0:9998'
toml_config true
end
Use with an on-prem Habitat Builder. Note: Access to public builder may not be available due to your company policies
habitat_sup 'default' do
bldr_url 'https://bldr.example.com'
end
Using update_condition
habitat_sup 'default' do
bldr_url 'https://bldr.example.com'
habitat_channel 'dev'
update_condition 'track-channel'
end
Provide event_stream_ information*
habitat_sup 'default' do
license 'accept'
event_stream_application 'myapp'
event_stream_environment 'production'
event_stream_site 'MySite'
event_stream_url 'automate.example.com:4222'
event_stream_token 'myawesomea2clitoken='
event_stream_cert '/hab/cache/ssl/mycert.crt'
end
Provide specific versions
habitat_sup 'default' do
bldr_url 'https://bldr.example.com'
sup_version '1.5.50'
launcher_version '13458'
service_version '0.6.0' # WINDOWS ONLY
end
Set latest version of packages to retain
habitat_sup ‘default’ do bldr_url ‘https://bldr.example.com’ sup_version ‘1.5.86’ launcher_version ‘13458’ service_version ‘0.6.0’ # WINDOWS ONLY keep_latest ‘2’ end
habitat_user_toml resource
habitat_user_toml resource pageUse the habitat_user_toml to template a user.toml
for Chef Habitat services. Configurations set in the user.toml
override the default.toml
for a given package, which makes it an alternative to applying service group level configuration.
New in Chef Infra Client 17.3.
Syntax
The full syntax for all of the properties that are available to the habitat_user_toml resource is:
habitat_user_toml 'name' do
config Mash (Hash-like)
service_name String # default value: 'name' unless specified
action Symbol # defaults to :create if not specified
end
where:
habitat_user_toml
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.config
andservice_name
are the properties available to this resource.
Actions
The habitat_user_toml resource has the following actions:
:create
- (default action) Create the user.toml from the specified config. (default)
:delete
- Delete the user.toml
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The habitat_user_toml resource has the following properties:
config
- Ruby Type: Mash (Hash-like) |
REQUIRED
Only valid for
:create
action. The configuration to apply as a ruby hash, for example,{ worker_count: 2, http: { keepalive_timeout: 120 } }
.
service_name
- Ruby Type: String | Default Value:
The resource block's name
The service group to apply the configuration to, for example,
nginx.default
.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the habitat_user_toml resource in recipes:
Configure user specific settings to nginx
habitat_user_toml 'nginx' do
config({
worker_count: 2,
http: {
keepalive_timeout: 120
}
})
end
homebrew_cask resource
homebrew_cask resource pageUse the homebrew_cask resource to install binaries distributed via the Homebrew package manager.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the homebrew_cask resource is:
homebrew_cask 'name' do
cask_name String # default value: 'name' unless specified
homebrew_path String
install_cask true, false # default value: true
options String
owner String, Integer # default value: "Calculated default username"
action Symbol # defaults to :install if not specified
end
where:
homebrew_cask
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.cask_name
,homebrew_path
,install_cask
,options
, andowner
are the properties available to this resource.
Actions
The homebrew_cask resource has the following actions:
:install
- Install an application that is packaged as a Homebrew cask. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove an application that is packaged as a Homebrew cask.
Properties
The homebrew_cask resource has the following properties:
cask_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the cask name if it differs from the resource block’s name.
homebrew_path
- Ruby Type: String
The path to the homebrew binary.
install_cask
- Ruby Type: true, false | Default Value:
true
Automatically install the Homebrew cask tap, if necessary.
options
- Ruby Type: String
Options to pass to the brew command during installation.
owner
- Ruby Type: String, Integer | Default Value:
Calculated default username
The owner of the Homebrew installation.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
This resource does not have any examples.
homebrew_package resource
homebrew_package resource pageUse the homebrew_package resource to manage packages for the macOS platform.
Note
Starting with Chef Infra Client 16 the homebrew resource now accepts an array of packages for installing multiple packages at once.
Note
New in Chef Infra Client 12.0.
Syntax
The full syntax for all of the properties that are available to the homebrew_package resource is:
homebrew_package 'name' do
homebrew_user String, Integer
options String, Array
package_name String, Array
source String
timeout String, Integer
version String, Array
action Symbol # defaults to :install if not specified
end
where:
homebrew_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.homebrew_user
,options
,package_name
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The homebrew_package resource has the following actions:
:install
- Install a package. If a version is specified, install the specified version of the package. (default)
:purge
- Purge a package. This action typically removes the configuration files as well as the package.
:remove
- Remove a package.
:upgrade
- Install a package and ensure that a package is the latest version.
Properties
The homebrew_package resource has the following properties:
homebrew_user
- Ruby Type: String, Integer
The name or uid of the Homebrew owner to be used by Chef Infra Client when executing a command.
Chef Infra Client, by default, will attempt to execute a Homebrew command as the owner of the
/usr/local/bin/brew
executable on x86_64 machines or/opt/homebrew/bin/brew
executable on arm64 machines. If that executable doesn’t exist, Chef Infra Client will attempt to find the user by executingwhich brew
. If that executable can’t be found, Chef Infra Client will print an error message:Couldn't find the 'brew' executable anywhere on the path.
.Set this property to specify the Homebrew owner for situations where Chef Infra Client can’t automatically detect the correct owner.'
options
- Ruby Type: String, Array
One (or more) additional command options that are passed to the command.
package_name
- Ruby Type: String, Array
An optional property to set the package name if it differs from the resource block’s name.
source
- Ruby Type: String
The optional path to a package on the local file system.
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String, Array
The version of a package to be installed or upgraded.
Multiple Packages
A resource may specify multiple packages and/or versions for platforms that use Apt, Chocolatey, DNF, Homebrew, Pacman, or Zypper package managers. Specifying multiple packages and/or versions allows a single transaction to:
- Download the specified packages and versions using a single HTTP transaction
- Update or install multiple packages with a single resource during a Chef Infra Client run
For example, installing multiple packages:
package %w(package1 package2)
Installing multiple packages with versions:
package %w(package1 package2) do
version [ '1.3.4-2', '4.3.6-1']
end
Upgrading multiple packages:
package %w(package1 package2) do
action :upgrade
end
Removing multiple packages:
package %w(package1 package2) do
action :remove
end
Purging multiple packages:
package %w(package1 package2) do
action :purge
end
Notifications, using an implicit name:
package %w(package1 package2) do
action :nothing
end
log 'call a notification' do
notifies :install, 'package[package1, package2]', :immediately
end
Note
Notifications and subscriptions do not need to be updated when packages
and versions are added or removed from the package_name
or version
properties.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Multiple Packages
A resource may specify multiple packages and/or versions for platforms that use Apt, Chocolatey, DNF, Homebrew, Pacman, or Zypper package managers. Specifying multiple packages and/or versions allows a single transaction to:
- Download the specified packages and versions using a single HTTP transaction
- Update or install multiple packages with a single resource during a Chef Infra Client run
For example, installing multiple packages:
package %w(package1 package2)
Installing multiple packages with versions:
package %w(package1 package2) do
version [ '1.3.4-2', '4.3.6-1']
end
Upgrading multiple packages:
package %w(package1 package2) do
action :upgrade
end
Removing multiple packages:
package %w(package1 package2) do
action :remove
end
Purging multiple packages:
package %w(package1 package2) do
action :purge
end
Notifications, using an implicit name:
package %w(package1 package2) do
action :nothing
end
log 'call a notification' do
notifies :install, 'package[package1, package2]', :immediately
end
Note
Notifications and subscriptions do not need to be updated when packages
and versions are added or removed from the package_name
or version
properties.
Examples
The following examples demonstrate various approaches for using the homebrew_package resource in recipes:
Install a package:
homebrew_package 'git'
Install multiple packages at once:
homebrew_package %w(git fish ruby)
Specify the Homebrew user with a UUID
homebrew_package 'git' do
homebrew_user 1001
end
Specify the Homebrew user with a string:
homebrew_package 'vim' do
homebrew_user 'user1'
end
homebrew_tap resource
homebrew_tap resource pageUse the homebrew_tap resource to add additional formula repositories to the Homebrew package manager.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the homebrew_tap resource is:
homebrew_tap 'name' do
homebrew_path String
owner String # default value: "Calculated default username"
tap_name String # default value: 'name' unless specified
url String
action Symbol # defaults to :tap if not specified
end
where:
homebrew_tap
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.homebrew_path
,owner
,tap_name
, andurl
are the properties available to this resource.
Actions
The homebrew_tap resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:tap
- Add a Homebrew tap. (default)
:untap
- Remove a Homebrew tap.
Properties
The homebrew_tap resource has the following properties:
homebrew_path
- Ruby Type: String
The path to the Homebrew binary.
owner
- Ruby Type: String | Default Value:
Calculated default username
The owner of the Homebrew installation.
tap_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the tap name if it differs from the resource block’s name.
url
- Ruby Type: String
The URL of the tap.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
This resource does not have any examples.
homebrew_update resource
homebrew_update resource pageUse the homebrew_update resource to manage Homebrew repository updates on macOS.
New in Chef Infra Client 16.2.
Syntax
The full syntax for all of the properties that are available to the homebrew_update resource is:
homebrew_update 'name' do
frequency Integer # default value: 86400
action Symbol # defaults to :periodic if not specified
end
where:
homebrew_update
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.frequency
is the property available to this resource.
Actions
The homebrew_update resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:periodic
- Run a periodic update based on the frequency property. (default)
:update
- Run an immediate update.
Properties
The homebrew_update resource has the following properties:
frequency
- Ruby Type: Integer | Default Value:
86400
Determines how frequently (in seconds) Homebrew updates are made. Use this property when the
:periodic
action is specified.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the homebrew_update resource in recipes:
Update the homebrew repository data at a specified interval:
homebrew_update 'all platforms' do
frequency 86400
action :periodic
end
Update the Homebrew repository at the start of a Chef Infra Client run:
homebrew_update 'update'
hostname resource
hostname resource pageUse the hostname resource to set the system’s hostname, configure hostname and hosts config file, and re-run the Ohai hostname plugin so the hostname will be available in subsequent cookbooks.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the hostname resource is:
hostname 'name' do
aliases Array
compile_time true, false # default value: true
domain_password String
domain_user String
fqdn String
hostname String # default value: 'name' unless specified
ipaddress String # default value: The node's IP address as determined by Ohai.
windows_reboot true, false # default value: true
action Symbol # defaults to :set if not specified
end
where:
hostname
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.aliases
,compile_time
,domain_password
,domain_user
,fqdn
,hostname
,ipaddress
, andwindows_reboot
are the properties available to this resource.
Actions
The hostname resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:set
- Sets the node’s hostname. (default)
Properties
The hostname resource has the following properties:
aliases
- Ruby Type: Array
An array of hostname aliases to use when configuring the hosts file.
compile_time
- Ruby Type: true, false | Default Value:
true
Determines whether or not the resource should be run at compile time.
domain_password
- Ruby Type: String
The password to accompany the domain_user parameter
New in Chef Infra Client 17.2
domain_user
- Ruby Type: String
A domain account specified in the form of DOMAIN\user used when renaming a domain-joined device
New in Chef Infra Client 17.2
fqdn
- Ruby Type: String
An optional property to set the fqdn if it differs from the resource block’s hostname.
New in Chef Infra Client 17.0
hostname
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the hostname if it differs from the resource block’s name.
ipaddress
- Ruby Type: String | Default Value:
The node's IP address as determined by Ohai.
The IP address to use when configuring the hosts file.
windows_reboot
- Ruby Type: true, false | Default Value:
true
Determines whether or not Windows should be reboot after changing the hostname, as this is required for the change to take effect.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the hostname resource in recipes:
Set the hostname using the IP address, as detected by Ohai:
hostname 'example'
Manually specify the hostname and IP address:
hostname 'statically_configured_host' do
hostname 'example'
ipaddress '198.51.100.2'
end
Change the hostname of a Windows, Non-Domain joined node:
hostname 'renaming a workgroup computer' do
hostname 'Foo'
end
Change the hostname of a Windows, Domain-joined node (new in 17.2):
hostname 'renaming a domain-joined computer' do
hostname 'Foo'
domain_user "Domain\Someone"
domain_password 'SomePassword'
end
http_request resource
http_request resource pageUse the http_request resource to send an HTTP request (GET
, PUT
, POST
, DELETE
, HEAD
, or OPTIONS
) with an arbitrary message. This resource is often useful when custom callbacks are necessary.
Syntax
An http_request resource block sends HTTP requests with an arbitrary message.
For example, to send a DELETE
request to 'http://www.example.com/some_page?message=please_delete_me'
:
http_request 'please_delete_me' do
url 'http://www.example.com/some_page'
action :delete
end
The full syntax for all of the properties that are available to the http_request resource is:
http_request 'name' do
headers Hash # default value: {}
message Object # defaults to 'name' if not specified
url String
action Symbol # defaults to :get if not specified
end
where:
http_request
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.headers
,message
, andurl
are properties of this resource, with the Ruby type shown. See “Properties” section below for more information about all of the properties that may be used with this resource.
Actions
The http_request resource has the following actions:
:delete
- Send a
DELETE
request. :get
- (default) Send a
GET
request. Changed in Chef Client 12.0 to deprecate the hard-coded query string from earlier versions. Cookbooks that rely on this string need to be updated to manually add it to the URL as it is passed to the resource. :head
- Send a
HEAD
request. :nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:options
- Send an
OPTIONS
request. :post
- Send a
POST
request. :put
- Send a
PUT
request.
Properties
The http_request resource has the following properties:
headers
- Ruby Type: Hash
A Hash of custom headers.
message
- Ruby Type: Object
The message that is sent by the HTTP request. Default value: the
name
of the resource block. See “Syntax” section above for more information.
url
- Ruby Type: String
The URL to which an HTTP request is sent.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the http_request resource in recipes:
Send a GET request
http_request 'some_message' do
url 'http://example.com/check_in'
end
The message is sent as
http://example.com/check_in?message=some_message
.
Send a POST request
To send a POST
request as JSON data, convert the message to JSON and
include the correct content-type header. For example:
http_request 'posting data' do
action :post
url 'http://example.com/check_in'
message ({:some => 'data'}.to_json)
headers({'AUTHORIZATION' => "Basic #{
Base64.encode64('username:password')}",
'Content-Type' => 'application/data'
})
end
Transfer a file only when the remote source changes
remote_file '/tmp/couch.png' do
source 'http://couchdb.apache.org/img/sketch.png'
action :nothing
end
http_request 'HEAD http://couchdb.apache.org/img/sketch.png' do
message ''
url 'http://couchdb.apache.org/img/sketch.png'
action :head
if ::File.exist?('/tmp/couch.png')
headers 'If-Modified-Since' => File.mtime('/tmp/couch.png').httpdate
end
notifies :create, 'remote_file[/tmp/couch.png]', :immediately
end
ifconfig resource
ifconfig resource pageUse the ifconfig resource to manage interfaces on Unix and Linux systems.
Note
This resource requires the ifconfig binary to be present on the system and may require additional packages to be installed first. On Ubuntu 18.04 or later you will need to install the ifupdown
package, which disables the built in Netplan functionality.
Warning
This resource will not work with Fedora release 33 or later.
Syntax
The full syntax for all of the properties that are available to the ifconfig resource is:
ifconfig 'name' do
bcast String
bonding_opts String
bootproto String
bridge String
device String
ethtool_opts String
family String # default value: "inet"
gateway String
hwaddr String
inet_addr String
mask String
master String
metric String
mtu String
network String
onboot String
onparent String
slave String
target String # default value: 'name' unless specified
vlan String
action Symbol # defaults to :add if not specified
end
where:
ifconfig
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.bcast
,bonding_opts
,bootproto
,bridge
,device
,ethtool_opts
,family
,gateway
,hwaddr
,inet_addr
,mask
,master
,metric
,mtu
,network
,onboot
,onparent
,slave
,target
, andvlan
are the properties available to this resource.
Actions
The ifconfig resource has the following actions:
:add
- Run ifconfig to configure a network interface and (on some platforms) write a configuration file for that network interface. (default)
:delete
- Run ifconfig to disable a network interface and (on some platforms) delete that network interface’s configuration file.
:disable
- Run ifconfig to disable a network interface.
:enable
- Run ifconfig to enable a network interface.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The ifconfig resource has the following properties:
bcast
- Ruby Type: String
The broadcast address for a network interface. On some platforms this property is not set using ifconfig, but instead is added to the startup configuration file for the network interface.
bonding_opts
- Ruby Type: String
Bonding options to pass via
BONDING_OPTS
on RHEL and CentOS. For example:mode=active-backup miimon=100
.New in Chef Client 13.4
bootproto
- Ruby Type: String
The boot protocol used by a network interface.
bridge
- Ruby Type: String
The bridge interface this interface is a member of on Red Hat based systems.
New in Chef Infra Client 16.7
device
- Ruby Type: String
The network interface to be configured.
ethtool_opts
- Ruby Type: String
Options to be passed to ethtool(8). For example:
-A eth0 autoneg off rx off tx off
.New in Chef Client 13.4
family
- Ruby Type: String | Default Value:
inet
Networking family option for Debian-based systems; for example:
inet
orinet6
.New in Chef Client 14.0
gateway
- Ruby Type: String
The gateway to use for the interface.
New in Chef Client 14.4
hwaddr
- Ruby Type: String
The hardware address for the network interface.
inet_addr
- Ruby Type: String
The Internet host address for the network interface.
mask
- Ruby Type: String
The decimal representation of the network mask. For example:
255.255.255.0
.
master
- Ruby Type: String
Specifies the channel bonding interface to which the Ethernet interface is linked.
New in Chef Client 13.4
metric
- Ruby Type: String
The routing metric for the interface.
mtu
- Ruby Type: String
The maximum transmission unit (MTU) for the network interface.
network
- Ruby Type: String
The address for the network interface.
onboot
- Ruby Type: String
Bring up the network interface on boot.
onparent
- Ruby Type: String
Bring up the network interface when its parent interface is brought up.
slave
- Ruby Type: String
When set to
yes
, this device is controlled by the channel bonding interface that is specified via themaster
property.New in Chef Client 13.4
target
- Ruby Type: String | Default Value:
The resource block's name
The IP address that is to be assigned to the network interface. If not specified we’ll use the resource’s name.
vlan
- Ruby Type: String
The VLAN to assign the interface to.
New in Chef Client 14.4
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the ifconfig resource in recipes:
Configure a network interface with a static IP
ifconfig '33.33.33.80' do
device 'eth1'
end
will create the following interface configuration:
iface eth1 inet static
address 33.33.33.80
Configure an interface to use DHCP
ifconfig 'Set eth1 to DHCP' do
device 'eth1'
bootproto 'dhcp'
end
will create the following interface configuration:
iface eth1 inet dhcp
Update a static IP address with a boot protocol
ifconfig "33.33.33.80" do
bootproto "dhcp"
device "eth1"
end
will update the interface configuration from static to dhcp:
iface eth1 inet dhcp
address 33.33.33.80
inspec_input resource
inspec_input resource pageUse the inspec_input resource to add an input to the Compliance Phase.
New in Chef Infra Client 17.5.
Syntax
The full syntax for all of the properties that are available to the inspec_input resource is:
inspec_input 'name' do
input Hash, String # default value: 'name' unless specified
source Hash, String # default value: 'name' unless specified
action Symbol # defaults to :add if not specified
end
where:
inspec_input
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.input
andsource
are the properties available to this resource.
Actions
The inspec_input resource has the following actions:
:add
- Add an input to the compliance phase (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The inspec_input resource has the following properties:
input
- Ruby Type: Hash, String | Default Value:
The resource block's name
source
- Ruby Type: Hash, String | Default Value:
The resource block's name
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the inspec_input resource in recipes:
Activate the default input in the openssh cookbook’s compliance segment:
inspec_input 'openssh' do
action :add
end
Activate all inputs in the openssh cookbook’s compliance segment:
inspec_input 'openssh::.*' do
action :add
end
Add an InSpec input to the Compliance Phase from a hash:
inspec_input { ssh_custom_path: '/whatever2' }
Add an InSpec input to the Compliance Phase using the ’name’ property to identify the input:
inspec_input "setting my input" do
source( { ssh_custom_path: '/whatever2' })
end
Add an InSpec input to the Compliance Phase using a TOML, JSON, or YAML file:
inspec_input "/path/to/my/input.yml"
Add an InSpec input to the Compliance Phase using a TOML, JSON, or YAML file, using the ’name’ property:
inspec_input "setting my input" do
source "/path/to/my/input.yml"
end
Note that the inspec_input resource does not update and will not fire notifications (similar to the log resource). This is done to preserve the ability to use
the resource while not causing the updated resource count to be larger than zero. Since the resource does not update the state of the managed node, this behavior
is still consistent with the configuration management model. Instead, you should use events to observe configuration changes for the compliance phase. It is
possible to use the notify_group
resource to chain notifications of the two resources, but notifications are the wrong model to use, and you should use pure ruby
conditionals instead. Compliance configuration should be independent of other resources and should only be conditional based on state/attributes, not other resources.
inspec_waiver resource
inspec_waiver resource pageUse the inspec_waiver resource to add a waiver to the Compliance Phase.
New in Chef Infra Client 17.5.
Syntax
The full syntax for all of the properties that are available to the inspec_waiver resource is:
inspec_waiver 'name' do
control String # default value: 'name' unless specified
expiration String
justification String
run_test true, false
source Hash, String
action Symbol # defaults to :add if not specified
end
where:
inspec_waiver
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.control
,expiration
,justification
,run_test
, andsource
are the properties available to this resource.
Actions
The inspec_waiver resource has the following actions:
:add
- Add a waiver to the compliance phase (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The inspec_waiver resource has the following properties:
control
- Ruby Type: String | Default Value:
The resource block's name
The name of the control being waived
expiration
- Ruby Type: String
The expiration date of the waiver - provided in YYYY-MM-DD format
justification
- Ruby Type: String
Can be any text you want and might include a reason for the waiver as well as who signed off on the waiver.
run_test
- Ruby Type: true, false
If present and true, the control will run and be reported, but failures in it won’t make the overall run fail. If absent or false, the control will not be run.
source
- Ruby Type: Hash, String
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the inspec_waiver resource in recipes:
Activate the default waiver in the openssh cookbook’s compliance segment:
inspec_waiver 'openssh' do
action :add
end
Activate all waivers in the openssh cookbook’s compliance segment:
inspec_waiver 'openssh::.*' do
action :add
end
Add an InSpec waiver to the Compliance Phase:
inspec_waiver 'Add waiver entry for control' do
control 'my_inspec_control_01'
run_test false
justification "The subject of this control is not managed by Chef Infra Client on the systems in policy group #{node['policy_group']}"
expiration '2022-01-01'
action :add
end
Add an InSpec waiver to the Compliance Phase using the ’name’ property to identify the control:
inspec_waiver 'my_inspec_control_01' do
justification "The subject of this control is not managed by Chef Infra Client on the systems in policy group #{node['policy_group']}"
action :add
end
Add an InSpec waiver to the Compliance Phase using an arbitrary YAML, JSON, or TOML file:
# files ending in .yml or .yaml that exist are parsed as YAML
inspec_waiver "/path/to/my/waiver.yml"
inspec_waiver "my-waiver-name" do
source "/path/to/my/waiver.yml"
end
# files ending in .json that exist are parsed as JSON
inspec_waiver "/path/to/my/waiver.json"
inspec_waiver "my-waiver-name" do
source "/path/to/my/waiver.json"
end
# files ending in .toml that exist are parsed as TOML
inspec_waiver "/path/to/my/waiver.toml"
inspec_waiver "my-waiver-name" do
source "/path/to/my/waiver.toml"
end
Add an InSpec waiver to the Compliance Phase using a hash:
my_hash = { "ssh-01" => {
"expiration_date" => "2033-07-31",
"run" => false,
"justification" => "because"
} }
inspec_waiver "my-waiver-name" do
source my_hash
end
Note that the inspec_waiver resource does not update and will not fire notifications (similar to the log resource). This is done to preserve the ability to use
the resource while not causing the updated resource count to be larger than zero. Since the resource does not update the state of the managed node, this behavior
is still consistent with the configuration management model. Instead, you should use events to observe configuration changes for the compliance phase. It is
possible to use the notify_group
resource to chain notifications of the two resources, but notifications are the wrong model to use, and you should use pure ruby
conditionals instead. Compliance configuration should be independent of other resources and should only be conditional based on state/attributes, not other resources.
inspec_waiver_file_entry resource
inspec_waiver_file_entry resource pageUse the inspec_waiver_file_entry resource to add or remove entries from an InSpec waiver file. This can be used in conjunction with the Compliance Phase.
New in Chef Infra Client 17.1.
Syntax
The full syntax for all of the properties that are available to the inspec_waiver_file_entry resource is:
inspec_waiver_file_entry 'name' do
backup false, Integer # default value: false
control String # default value: 'name' unless specified
expiration String
file_path String
justification String
run_test true, false
action Symbol # defaults to :add if not specified
end
where:
inspec_waiver_file_entry
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.backup
,control
,expiration
,file_path
,justification
, andrun_test
are the properties available to this resource.
Actions
The inspec_waiver_file_entry resource has the following actions:
:add
- (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
Properties
The inspec_waiver_file_entry resource has the following properties:
backup
- Ruby Type: false, Integer | Default Value:
false
The number of backups to be kept in
/var/chef/backup
(for UNIX- and Linux-based platforms) orC:/chef/backup
(for the Microsoft Windows platform). Set tofalse
to prevent backups from being kept.
control
- Ruby Type: String | Default Value:
The resource block's name
The name of the control being added or removed to the waiver file
expiration
- Ruby Type: String
The expiration date of the given waiver - provided in YYYY-MM-DD format
file_path
- Ruby Type: String | Default Value:
`/etc/chef/inspec_waivers.yml` on Linux/Unix and `C:\chef\inspec_waivers.yml` on Windows
|REQUIRED
The path to the waiver file being modified
justification
- Ruby Type: String
Can be any text you want and might include a reason for the waiver as well as who signed off on the waiver.
run_test
- Ruby Type: true, false
If present and
true
, the control will run and be reported, but failures in it won’t make the overall run fail. If absent orfalse
, the control will not be run.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the inspec_waiver_file_entry resource in recipes:
Add an InSpec waiver entry to a given waiver file:
inspec_waiver_file_entry 'Add waiver entry for control' do
file_path 'C:\chef\inspec_waiver_file.yml'
control 'my_inspec_control_01'
run_test false
justification "The subject of this control is not managed by Chef Infra Client on the systems in policy group #{node['policy_group']}"
expiration '2022-01-01'
action :add
end
Add an InSpec waiver entry to a given waiver file using the ’name’ property to identify the control:
inspec_waiver_file_entry 'my_inspec_control_01' do
justification "The subject of this control is not managed by Chef Infra Client on the systems in policy group #{node['policy_group']}"
action :add
end
Remove an InSpec waiver entry to a given waiver file:
inspec_waiver_file_entry "my_inspec_control_01" do
action :remove
end
ips_package resource
ips_package resource pageUse the ips_package resource to manage packages (using Image Packaging System (IPS)) on the Solaris 11 platform.
Note
Syntax
A ips_package resource block manages a package on a node, typically by installing it. The simplest use of the ips_package resource is:
ips_package ''package_name''
which will install the named package using all of the default options
and the default action (:install
).
The full syntax for all of the properties that are available to the ips_package resource is:
ips_package 'name' do
accept_license true, false # default value: false
options String, Array
package_name String
source String
timeout String, Integer
version String
action Symbol # defaults to :install if not specified
end
where:
ips_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.accept_license
,options
,package_name
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The ips_package resource has the following actions:
:install
- Install a package. If a version is specified, install the specified version of the package. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove a package.
:upgrade
- Install a package and ensure that a package is the latest version.
Properties
The ips_package resource has the following properties:
accept_license
- Ruby Type: true, false | Default Value:
false
Accept an end-user license agreement, automatically.
options
- Ruby Type: String, Array
One (or more) additional command options that are passed to the command.
package_name
- Ruby Type: String
An optional property to set the package name if it differs from the resource block’s name.
source
- Ruby Type: String
The optional path to a package on the local file system.
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String
The version of a package to be installed or upgraded.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the ips_package resource in recipes:
Install a package
ips_package 'name of package' do
action :install
end
kernel_module resource
kernel_module resource pageUse the kernel_module resource to manage kernel modules on Linux systems. This resource can load, unload, blacklist, disable, enable, install, and uninstall modules.
New in Chef Infra Client 14.3.
Syntax
The full syntax for all of the properties that are available to the kernel_module resource is:
kernel_module 'name' do
load_dir String # default value: "/etc/modules-load.d"
modname String # default value: 'name' unless specified
options Array
unload_dir String # default value: "/etc/modprobe.d"
action Symbol # defaults to :install if not specified
end
where:
kernel_module
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.load_dir
,modname
,options
, andunload_dir
are the properties available to this resource.
Actions
The kernel_module resource has the following actions:
:blacklist
- Blacklist a kernel module.
:disable
- Disable a kernel module. New in Chef Infra Client 15.2.
:enable
- Enable a kernel module. Reverse :disable actions
:install
- Load kernel module, and ensure it loads on reboot. (default)
:load
- Load a kernel module.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:uninstall
- Unload a kernel module and remove module config, so it doesn’t load on reboot.
:unload
- Unload kernel module.
Properties
The kernel_module resource has the following properties:
load_dir
- Ruby Type: String | Default Value:
/etc/modules-load.d
The directory to load modules from.
modname
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the kernel module name if it differs from the resource block’s name.
options
- Ruby Type: Array
An optional property to set options for the kernel module.
New in Chef Infra Client 15.4
unload_dir
- Ruby Type: String | Default Value:
/etc/modprobe.d
The modprobe.d directory.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the kernel_module resource in recipes:
Install and load a kernel module, and ensure it loads on reboot.
kernel_module 'loop'
Install and load a kernel with a specific set of options, and ensure it loads on reboot. Consult kernel module documentation for specific options that are supported.
kernel_module 'loop' do
options [
'max_loop=4',
'max_part=8',
]
end
Load a kernel module.
kernel_module 'loop' do
action :load
end
Unload a kernel module and remove module config, so it doesn’t load on reboot.
kernel_module 'loop' do
action :uninstall
end
Unload kernel module.
kernel_module 'loop' do
action :unload
end
Blacklist a module from loading.
kernel_module 'loop' do
action :blacklist
end
Disable a kernel module so that it is not installable.
kernel_module 'loop' do
action :disable
end
Enable a kernel module so that it is can be installed. Does not load or install.
kernel_module 'loop' do
action :enable
end
ksh resource
ksh resource pageUse the ksh resource to execute scripts using the Korn shell (ksh) interpreter. This resource may also use any of the actions and properties that are available to the execute resource. 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.
Syntax
A ksh resource block executes scripts using ksh:
ksh 'hello world' do
code <<-EOH
echo "Hello world!"
echo "Current directory: " $cwd
EOH
end
where:
code
specifies the command to run.
where:
code
specifies the command to run
The full syntax for all of the properties that are available to the ksh resource is:
ksh 'name' do
code String
creates String
cwd String
environment Hash
flags String
group String, Integer
path Array
returns Integer, Array
timeout Integer, Float
user String, Integer
umask String, Integer
action Symbol # defaults to :run if not specified
end
where:
ksh
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.code
,creates
,cwd
,environment
,flags
,group
,input
,path
,returns
,timeout
,user
, andumask
are the properties available to this resource.
Actions
The ksh resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:run
- Run a command. (default)
Properties
The ksh resource has the following properties:
code
- Ruby Type: String |
REQUIRED
A quoted string of code to be executed.
creates
- Ruby Type: String
Prevent a command from creating a file when that file already exists.
cwd
- Ruby Type: String
The current working directory from which the command will be run.
environment
- Ruby Type: Hash
A Hash of environment variables in the form of
({'ENV_VARIABLE' => 'VALUE'})
. Note: These variables must exist for a command to be run successfully.
flags
- Ruby Type: String
One or more command line flags that are passed to the interpreter when a command is invoked.
group
- Ruby Type: String, Integer
The group name or group ID that must be changed before running a command.
returns
- Ruby Type: Integer, Array | Default Value:
0
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.
timeout
- Ruby Type: Integer, String, Float | Default Value:
3600
The amount of time (in seconds) a command is to wait before timing out.
user
- Ruby Type: String, Integer
The user name or user ID that should be changed before running a command.
umask
- Ruby Type: String, Integer
The file mode creation mask, or umask.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
This resource does not have any examples.
launchd resource
launchd resource pageUse the launchd resource to manage system-wide services (daemons) and per-user services (agents) on the macOS platform.
New in Chef Infra Client 12.8.
Syntax
The full syntax for all of the properties that are available to the launchd resource is:
launchd 'name' do
abandon_process_group true, false
associated_bundle_identifiers Array
backup Integer, false
cookbook String
debug true, false
disabled true, false # default value: false
enable_globbing true, false
enable_transactions true, false
environment_variables Hash
exit_timeout Integer
group String, Integer
hard_resource_limits Hash
inetd_compatibility Hash
init_groups true, false
keep_alive true, false, Hash
label String # default value: 'name' unless specified
launch_events Hash
launch_only_once true, false
ld_group String
limit_load_from_hosts Array
limit_load_to_hosts Array
limit_load_to_session_type Array, String
low_priority_io true, false
mach_services Hash
mode String, Integer
nice Integer
on_demand true, false
owner String, Integer
path String
plist_hash Hash
process_type String
program String
program_arguments Array
queue_directories Array
root_directory String
run_at_load true, false
session_type String
sockets Hash
soft_resource_limits Array
source String
standard_error_path String
standard_in_path String
standard_out_path String
start_calendar_interval Hash, Array
start_interval Integer
start_on_mount true, false
throttle_interval Integer
time_out Integer
type String # default value: "daemon"
username String
wait_for_debugger true, false
watch_paths Array
working_directory String
action Symbol # defaults to :create if not specified
end
where:
launchd
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.abandon_process_group
,associated_bundle_identifiers
,backup
,cookbook
,debug
,disabled
,enable_globbing
,enable_transactions
,environment_variables
,exit_timeout
,group
,hard_resource_limits
,inetd_compatibility
,init_groups
,keep_alive
,label
,launch_events
,launch_only_once
,ld_group
,limit_load_from_hosts
,limit_load_to_hosts
,limit_load_to_session_type
,low_priority_io
,mach_services
,mode
,nice
,on_demand
,owner
,path
,plist_hash
,process_type
,program
,program_arguments
,queue_directories
,root_directory
,run_at_load
,session_type
,sockets
,soft_resource_limits
,source
,standard_error_path
,standard_in_path
,standard_out_path
,start_calendar_interval
,start_interval
,start_on_mount
,throttle_interval
,time_out
,type
,username
,wait_for_debugger
,watch_paths
, andworking_directory
are the properties available to this resource.
Actions
The launchd resource has the following actions:
:create
- Create a launchd property list. (default)
:create_if_missing
- Create a launchd property list, if it does not already exist.
:delete
- Delete a launchd property list. This will unload a daemon or agent, if loaded.
:disable
- Disable a launchd property list.
:enable
- Create a launchd property list, and then ensure that it is enabled. If a launchd property list already exists, but does not match, updates the property list to match, and then restarts the daemon or agent.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:restart
- Restart a launchd managed daemon or agent.
Properties
The launchd resource has the following properties:
abandon_process_group
- Ruby Type: true, false
If a job dies, all remaining processes with the same process ID may be kept running. Set to true to kill all remaining processes.
associated_bundle_identifiers
- Ruby Type: Array
This optional key indicates which bundles the Login Items Added by Apps panel associates with the helper executable.
backup
- Ruby Type: Integer, false
The number of backups to be kept in
/var/chef/backup
. Set tofalse
to prevent backups from being kept.
cookbook
- Ruby Type: String
The name of the cookbook in which the source files are located.
debug
- Ruby Type: true, false
Sets the log mask to
LOG_DEBUG
for this job.
disabled
- Ruby Type: true, false | Default Value:
false
Hints to
launchctl
to not submit this job to launchd.
enable_globbing
- Ruby Type: true, false
Update program arguments before invocation.
enable_transactions
- Ruby Type: true, false
Track in-progress transactions; if none, then send the
SIGKILL
signal.
environment_variables
- Ruby Type: Hash
Additional environment variables to set before running a job.
exit_timeout
- Ruby Type: Integer
The amount of time (in seconds) launchd waits before sending a
SIGKILL
signal.
group
- Ruby Type: String, Integer
When launchd is run as the root user, this is the corresponding group to run the job as. If the
username
property is specified and this property is not, this value is set to the default group for the user.
hard_resource_limits
- Ruby Type: Hash
A Hash of resource limits to be imposed on a job.
inetd_compatibility
- Ruby Type: Hash
Specifies if a daemon expects to be run as if it were launched from inetd. Set to
wait => true
to pass standard input, output, and error file descriptors. Set towait => false
to call the accept system call on behalf of the job, and then pass standard input, output, and error file descriptors.
init_groups
- Ruby Type: true, false
Specify if
initgroups
is called before running a job.
keep_alive
- Ruby Type: true, false, Hash
Keep a job running continuously (true) or allow demand and conditions on the node to determine if the job keeps running (
false
).New in Chef Client 12.14
label
- Ruby Type: String | Default Value:
The resource block's name
The unique identifier for the job.
launch_events
- Ruby Type: Hash
Specify higher-level event types to be used as launch-on-demand event sources.
New in Chef Infra Client 15.1
launch_only_once
- Ruby Type: true, false
Specify if a job can be run only one time. Set this value to true if a job cannot be restarted without a full machine reboot.
ld_group
- Ruby Type: String
The group name.
limit_load_from_hosts
- Ruby Type: Array
An array of hosts to which this configuration file does not apply, i.e. ‘apply this configuration file to all hosts not specified in this array’.
limit_load_to_hosts
- Ruby Type: Array
An array of hosts to which this configuration file applies.
limit_load_to_session_type
- Ruby Type: Array, String
The session type(s) to which this configuration file applies.
low_priority_io
- Ruby Type: true, false
Specify if the kernel on the node should consider this daemon to be low priority during file system I/O.
mach_services
- Ruby Type: Hash
Specify services to be registered with the bootstrap subsystem.
mode
- Ruby Type: String, Integer
A quoted 3-5 character string that defines the octal mode. For example: ‘755’, ‘0755’, or 00755.
nice
- Ruby Type: Integer
The program scheduling priority value in the range -20 to 19.
on_demand
- Ruby Type: true, false
Keep a job alive. Only applies to macOS version 10.4 (and earlier); use
keep_alive
instead for newer versions.
owner
- Ruby Type: String, Integer
A string or ID that identifies the group owner by user name, including fully qualified user names such as
domain_user
oruser@domain
. If this value is not specified, existing owners remain unchanged and new owner assignments use the current user (when necessary).
path
- Ruby Type: String
The path to the directory. Using a fully qualified path is recommended, but is not always required.
plist_hash
- Ruby Type: Hash
A Hash of key value pairs used to create the launchd property list.
New in Chef Client 12.19
process_type
- Ruby Type: String
The intended purpose of the job:
Adaptive
,Background
,Interactive
, orStandard
.
program
- Ruby Type: String
The first argument of
execvp
, typically the file name associated with the file to be executed. This value must be specified ifprogram_arguments
is not specified, and vice-versa.
program_arguments
- Ruby Type: Array
The second argument of
execvp
. If program is not specified, this property must be specified and will be handled as if it were the first argument.
queue_directories
- Ruby Type: Array
An array of non-empty directories which, if any are modified, will cause a job to be started.
root_directory
- Ruby Type: String
chroot
to this directory, and then run the job.
run_at_load
- Ruby Type: true, false
Launch a job once (at the time it is loaded).
session_type
- Ruby Type: String
The type of launchd plist to be created. Possible values: system (default) or user.
sockets
- Ruby Type: Hash
A Hash of on-demand sockets that notify launchd when a job should be run.
soft_resource_limits
- Ruby Type: Array
A Hash of resource limits to be imposed on a job.
source
- Ruby Type: String
The path to the launchd property list.
standard_error_path
- Ruby Type: String
The file to which standard error (
stderr
) is sent.
standard_in_path
- Ruby Type: String
The file to which standard input (
stdin
) is sent.
standard_out_path
- Ruby Type: String
The file to which standard output (
stdout
) is sent.
start_calendar_interval
- Ruby Type: Hash, Array
A Hash (similar to
crontab
) or an Array that defines the calendar frequency at which a job is started. For example:{ Minute => "0", Hour => "20", Day => "*", Weekday => "1-5", Month => "*" }
will run a job at 8:00 PM every day, Monday through Friday, every month of the year.
start_interval
- Ruby Type: Integer
The frequency (in seconds) at which a job is started.
start_on_mount
- Ruby Type: true, false
Start a job every time a file system is mounted.
throttle_interval
- Ruby Type: Integer
The frequency (in seconds) at which jobs are allowed to spawn.
time_out
- Ruby Type: Integer
The amount of time (in seconds) a job may be idle before it times out. If no value is specified, the default timeout value for launchd will be used.
type
- Ruby Type: String | Default Value:
daemon
The type of resource. Possible values: daemon (default), agent.
username
- Ruby Type: String
When launchd is run as the root user, the user to run the job as.
wait_for_debugger
- Ruby Type: true, false
Specify if launchd has a job wait for a debugger to attach before executing code.
watch_paths
- Ruby Type: Array
An array of paths which, if any are modified, will cause a job to be started.
working_directory
- Ruby Type: String
chdir
to this directory, and then run the job.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the launchd resource in recipes:
Create a Launch Daemon from a cookbook file
launchd 'com.chef.every15' do
source 'com.chef.every15.plist'
end
Create a Launch Daemon using keys
launchd 'call.mom.weekly' do
program '/Library/scripts/call_mom.sh'
start_calendar_interval 'Weekday' => 7, 'Hourly' => 10
time_out 300
end
Remove a Launch Daemon
launchd 'com.chef.every15' do
action :delete
end
link resource
link resource pageUse the link resource to create symbolic or hard links.
A symbolic link–sometimes referred to as a soft link–is a directory entry that associates a file name with a string that contains an absolute or relative path to a file on any file system. In other words, it’s a file that contains a path that points to another file. A symbolic link creates a new file with a new inode that points to the inode location of the original file.
A hard link is a directory entry that associates a file with another file in the same file system. In other words, multiple directory entries to the same file. A hard link creates a new file that points to the same inode as the original file.
Syntax
A link resource block creates symbolic or hard links. For
example, to create a hard link from /tmp/file
to /etc/file
:
link '/tmp/file' do
to '/etc/file'
link_type :hard
end
Because the default value for link_type
is symbolic, and because
properties that are not specified in the resource block will be assigned
their default values, the following example creates a symbolic link:
link '/tmp/file' do
to '/etc/file'
end
The full syntax for all of the properties that are available to the link resource is:
link 'name' do
group String, Integer
link_type String, Symbol # default value: :symbolic
owner String, Integer
target_file String # default value: 'name' unless specified
to String
action Symbol # defaults to :create if not specified
end
where:
link
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.group
,link_type
,owner
,target_file
, andto
are the properties available to this resource.
Actions
The link resource has the following actions:
:create
- (default) Create a link. If a link already exists (but does not match), update that link to match.
:delete
- Delete a link.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The link resource has the following properties:
group
- Ruby Type: String, Integer
A group name or ID number that identifies the group associated with a symbolic link.
link_type
- Ruby Type: String, Symbol | Default Value:
:symbolic
Allowed Values::hard, :symbolic
The type of link:
:symbolic
or:hard
. On Windows,:symbolic
will create a junction point if the target is a directory.
mode
- Ruby Type: Integer, String | Default Value:
777
If
mode
is not specified and if the file already exists, the existing mode on the file is used. Ifmode
is not specified, the file does not exist, and the:create
action is specified, Chef Infra Client assumes a mask value of'0777'
and then applies the umask for the system on which the file is to be created to themask
value. For example, if the umask on a system is'022'
, Chef Infra Client uses the default value of'0755'
.The behavior is different depending on the platform.
UNIX- and Linux-based systems: A quoted 3-5 character string that defines the octal mode that is passed to chmod. For example:
'755'
,'0755'
, or00755
. If the value is specified as a quoted string, it works exactly as if thechmod
command was passed. If the value is specified as an integer, prepend a zero (0
) to the value to ensure that it is interpreted as an octal number. For example, to assign read, write, and execute rights for all users, use'0777'
or'777'
; for the same rights, plus the sticky bit, use01777
or'1777'
.Microsoft Windows: A quoted 3-5 character string that defines the octal mode that is translated into rights for Microsoft Windows security. For example:
'755'
,'0755'
, or00755
. Values up to'0777'
are allowed (no sticky bits) and mean the same in Microsoft Windows as they do in UNIX, where4
equalsGENERIC_READ
,2
equalsGENERIC_WRITE
, and1
equalsGENERIC_EXECUTE
. This property cannot be used to set:full_control
. This property has no effect if not specified, but when it andrights
are both specified, the effects are cumulative.
owner
- Ruby Type: String, Integer
The owner associated with a symbolic link.
target_file
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the target file if it differs from the resource block’s name.
to
- Ruby Type: String
The actual file to which the link is to be created.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the link resource in recipes:
Create symbolic links
The following example will create a symbolic link from /tmp/file
to /etc/file
:
link '/tmp/file' do
to '/etc/file'
end
Create hard links
The following example will create a hard link from /tmp/file
to /etc/file
:
link '/tmp/file' do
to '/etc/file'
link_type :hard
end
Delete links
The following example will delete the /tmp/file
symbolic link and uses
the only_if
guard to run the test -L
command, which verifies that
/tmp/file
is a symbolic link, and then only deletes /tmp/file
if the
test passes:
link '/tmp/file' do
action :delete
only_if
'test -L /tmp/file'
end
Create multiple symbolic links
The following example creates symbolic links from two files in the /vol/webserver/cert/
directory to files located in the /etc/ssl/certs/
directory:
link '/vol/webserver/cert/server.crt' do
to '/etc/ssl/certs/ssl-cert-name.pem'
end
link '/vol/webserver/cert/server.key' do
to '/etc/ssl/certs/ssl-cert-name.key'
end
Create platform-specific symbolic links
The following example shows installing a filter module on Apache. The package name is different for different platforms, and for the Red Hat Enterprise Linux family, a symbolic link is required:
include_recipe 'apache2::default'
case node['platform_family']
when 'debian'
...
when 'suse'
...
when 'rhel', 'fedora'
...
link '/usr/lib64/httpd/modules/mod_apreq.so' do
to '/usr/lib64/httpd/modules/mod_apreq2.so'
only_if 'test -f /usr/lib64/httpd/modules/mod_apreq2.so'
end
link '/usr/lib/httpd/modules/mod_apreq.so' do
to '/usr/lib/httpd/modules/mod_apreq2.so'
only_if 'test -f /usr/lib/httpd/modules/mod_apreq2.so'
end
end
...
For the complete recipe, see https://github.com/onehealth-cookbooks/apache2/blob/68bdfba4680e70b3e90f77e40223dd535bf22c17/recipes/mod_apreq2.rb.
Create Windows junction/reparse points
This example demonstrates how to create a directory junction/reparse point. In this example, C:\\destination
will be a junction/reparse point to the C:\\source
directory.
directory 'C:/source'
link 'C:/destination' do
link_type :symbolic
to 'C:/source'
end
locale resource
locale resource pageUse the locale resource to set the system’s locale on Debian and Windows systems. Windows support was added in Chef Infra Client 16.0
New in Chef Infra Client 14.5.
Syntax
The full syntax for all of the properties that are available to the locale resource is:
locale 'name' do
lang String
lc_env Hash # default value: {}
action Symbol # defaults to :update if not specified
end
where:
locale
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.lang
andlc_env
are the properties available to this resource.
Actions
The locale resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:update
- Update the system’s locale. (default)
Properties
The locale resource has the following properties:
lang
- Ruby Type: String
Sets the default system language.
lc_env
- Ruby Type: Hash | Default Value:
{}
A Hash of LC_* env variables in the form of
({ 'LC_ENV_VARIABLE' => 'VALUE' })
.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the locale resource in recipes:
Set the lang to ’en_US.UTF-8'
locale 'set system locale' do
lang 'en_US.UTF-8'
end
log resource
log resource pageUse the log resource to create log entries. The log resource behaves like any other resource: built into the resource collection during the compile phase, and then run during the execution phase. (To create a log entry that is not built into the resource collection, use Chef::Log
instead of the log resource.)
Syntax
A log resource block adds messages to the log file based on events that occur during a Chef Infra Client run:
log 'message' do
message 'A message add to the log.'
level :info
end
The full syntax for all of the properties that are available to the log resource is:
log 'name' do
level Symbol # default value: :info
message String # default value: 'name' unless specified
action Symbol # defaults to :write if not specified
end
where:
log
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.level
andmessage
are the properties available to this resource.
Actions
The log resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:write
- (default)
Properties
The log resource has the following properties:
level
Ruby Type: Symbol | Default Value:
:info
The logging level for displaying this message. Options (in order of priority):
:debug
,:info
,:warn
,:error
, and:fatal
.message
Ruby Type: String | Default Value:
The resource block's name
The message to be added to a log file. Default value: the
name
of the resource block. See “Syntax” section above for more information.
Log Entries
Chef::Log
will print log entries to the default logger that is configured for the machine on which Chef Infra Client is running. (To create a log entry that is built into the resource collection, use the log resource instead of Chef::Log
.)
Supported log levels
Log Level | Syntax |
---|---|
Fatal | Chef::Log.fatal('string') |
Error | Chef::Log.error('string') |
Warn | Chef::Log.warn('string') |
Info | Chef::Log.info('string') |
Debug | Chef::Log.debug('string') |
The following example shows a series of fatal Chef::Log
entries:
unless node['splunk']['upgrade_enabled']
Chef::Log.fatal('The chef-splunk::upgrade recipe was added to the node,')
Chef::Log.fatal('but the attribute `node["splunk"]["upgrade_enabled"]` was not set.')
Chef::Log.fatal('I am bailing here so this node does not upgrade.')
raise
end
service 'splunk_stop' do
service_name 'splunk'
supports status: true
action :stop
end
if node['splunk']['is_server']
splunk_package = 'splunk'
url_type = 'server'
else
splunk_package = 'splunkforwarder'
url_type = 'forwarder'
end
splunk_installer splunk_package do
url node['splunk']['upgrade']["#{url_type}_url"]
end
if node['splunk']['accept_license']
execute 'splunk-unattended-upgrade' do
command "#{splunk_cmd} start --accept-license --answer-yes"
end
else
Chef::Log.fatal('You did not accept the license (set node["splunk"]["accept_license"] to true)')
Chef::Log.fatal('Splunk is stopped and cannot be restarted until the license is accepted!')
raise
end
The following example shows using multiple Chef::Log
entry types:
...
begin
aws = Chef::DataBagItem.load(:aws, :main)
Chef::Log.info("Loaded AWS information from DataBagItem aws[#{aws['id']}]")
rescue
Chef::Log.fatal("Could not find the 'main' item in the 'aws' data bag")
raise
end
...
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the log resource in recipes:
Set default logging level
log 'a string to log'
Set debug logging level
log 'a debug string' do
level :debug
end
Add a message to a log file
log 'message' do
message 'This is the message that will be added to the log.'
level :info
end
macos_userdefaults resource
macos_userdefaults resource pageUse the macos_userdefaults resource to manage the macOS user defaults system. The properties of this resource are passed to the defaults command, and the parameters follow the convention of that command. See the defaults(1) man page for details on how the tool works.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the macos_userdefaults resource is:
macos_userdefaults 'name' do
domain String # default value: NSGlobalDomain: the global domain.
host String, Symbol # default value: :all
key String
user String, Symbol # default value: :current
value Integer, Float, String, true, false, Hash, Array
action Symbol # defaults to :write if not specified
end
where:
macos_userdefaults
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.domain
,host
,key
,user
, andvalue
are the properties available to this resource.
Actions
The macos_userdefaults resource has the following actions:
:delete
- Delete a key from a domain.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:write
- Write the value to the specified domain/key. (default)
Properties
The macos_userdefaults resource has the following properties:
domain
- Ruby Type: String | Default Value:
NSGlobalDomain: the global domain.
The domain that the user defaults belong to.
host
- Ruby Type: String, Symbol | Default Value:
:all
Set either :current, :all or a hostname to set the user default at the host level.
New in Chef Infra Client 16.3
key
- Ruby Type: String |
REQUIRED
The preference key.
user
- Ruby Type: String, Symbol | Default Value:
:current
The system user that the default will be applied to. Set :current for current user, :all for all users or pass a valid username
value
- Ruby Type: Integer, Float, String, true, false, Hash, Array |
REQUIRED
The value of the key.
Note
With the
type
property set tobool
,String
forms of Boolean true/false values that Apple accepts in the defaults command will be coerced: 0/1, ‘TRUE’/‘FALSE,’ ’true’/false’, ‘YES’/‘NO’, or ‘yes’/’no’.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the macos_userdefaults resource in recipes:
Specify a global domain value
macos_userdefaults 'Full keyboard access to all controls' do
key 'AppleKeyboardUIMode'
value 2
end
Setting a value on a specific domain
macos_userdefaults 'Enable macOS firewall' do
domain '/Library/Preferences/com.apple.alf'
key 'globalstate'
value 1
end
Setting a value for specific user and hosts
macos_userdefaults 'Enable macOS firewall' do
key 'globalstate'
value 1
user 'jane'
host :current
end
macosx_service resource
macosx_service resource pageUse the macosx_service resource to manage services on the macOS platform.
Syntax
The full syntax for all of the properties that are available to the macosx_service resource is:
macosx_service 'name' do
init_command String
options Array, String
parameters Hash
pattern String
plist String
priority Integer, String, Hash
reload_command String, false
restart_command String, false
run_levels Array
service_name String # default value: 'name' unless specified
session_type String
start_command String, false
status_command String, false
stop_command String, false
supports Hash # default value: {"restart"=>nil, "reload"=>nil, "status"=>nil}
timeout Integer # default value: 900
user String
action Symbol # defaults to :nothing if not specified
end
where:
macosx_service
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.init_command
,options
,parameters
,pattern
,plist
,priority
,reload_command
,restart_command
,run_levels
,service_name
,session_type
,start_command
,status_command
,stop_command
,supports
,timeout
, anduser
are the properties available to this resource.
Actions
The macosx_service resource has the following actions:
:disable
- Disable a service.
:enable
- Enable a service at boot.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:reload
- Reload the configuration for this service.
:restart
- Stop and then start a service again.
:start
- Start a service, and keep it running until stopped or disabled.
:stop
- Stop a service. It will stay stopped until restarted.
Properties
The macosx_service resource has the following properties:
init_command
- Ruby Type: String
The path to the init script that is associated with the service. Use
init_command
to prevent the need to specify overrides for thestart_command
,stop_command
, andrestart_command
properties. When this property is not specified, the Chef Infra Client will use the default init command for the service provider being used.
options
- Ruby Type: Array, String
Solaris platform only. Options to pass to the
service
command. See the svcadm manual for details of possible options.
parameters
- Ruby Type: Hash
Upstart only. A hash of parameters to pass to the
service
command for use in the service definition.
pattern
- Ruby Type: String | Default Value:
The value provided to `service_name` or the resource block's name
The pattern to look for in the process table.
plist
- Ruby Type: String
A plist to use in the case where the filename and label for the service do not match.
priority
- Ruby Type: Integer, String, Hash
Debian platform only. The relative priority of the program for start and shutdown ordering. May be an integer or a Hash. An integer is used to define the start run levels; stop run levels are then 100-integer. A Hash is used to define values for specific run levels. For example, { 2 => [:start, 20], 3 => [:stop, 55] } will set a priority of twenty for run level two and a priority of fifty-five for run level three.
reload_command
- Ruby Type: String, false
The command used to tell a service to reload its configuration.
restart_command
- Ruby Type: String, false
The command used to restart a service.
run_levels
- Ruby Type: Array
RHEL platforms only. Specific run levels the service will run under.
service_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the service name if it differs from the resource block’s name.
session_type
- Ruby Type: String
The type of plist to be created
start_command
- Ruby Type: String, false
The command used to start a service.
status_command
- Ruby Type: String, false
The command used to check the run status for a service.
stop_command
- Ruby Type: String, false
The command used to stop a service.
supports
- Ruby Type: Hash | Default Value:
{"restart"=>nil, "reload"=>nil, "status"=>nil}
A list of properties that controls how Chef Infra Client is to attempt to manage a service: :restart, :reload, :status. For :restart, the init script or other service provider can use a restart command; if :restart is not specified, the chef-client attempts to stop and then start a service. For :reload, the init script or other service provider can use a reload command. For :status, the init script or other service provider can use a status command to determine if the service is running; if :status is not specified, the chef-client attempts to match the service_name against the process table as a regular expression, unless a pattern is specified as a parameter property. Default value: { restart: false, reload: false, status: false } for all platforms (except for the Red Hat platform family, which defaults to { restart: false, reload: false, status: true }.)
timeout
- Ruby Type: Integer | Default Value:
900
The amount of time (in seconds) to wait before timing out.
user
- Ruby Type: String
systemd only: A username to run the service under.
New in Chef Client 12.21
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
This resource does not have any examples.
macports_package resource
macports_package resource pageUse the macports_package resource to manage packages for the macOS platform using the MacPorts package management system.
Syntax
A macports_package resource block manages a package on a node, typically by installing it. The simplest use of the macports_package resource is:
macports_package 'package_name'
which will install the named package using all of the default options
and the default action (:install
).
The full syntax for all of the properties that are available to the macports_package resource is:
macports_package 'name' do
options String, Array
package_name String
source String
timeout String, Integer
version String
action Symbol # defaults to :install if not specified
end
where:
macports_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.options
,package_name
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The macports_package resource has the following actions:
:install
- Install a package. If a version is specified, install the specified version of the package. (default)
:purge
- Purge a package. This action typically removes the configuration files as well as the package.
:remove
- Remove a package.
:upgrade
- Install a package and ensure that a package is the latest version.
Properties
The macports_package resource has the following properties:
options
- Ruby Type: String, Array
One (or more) additional command options that are passed to the command.
package_name
- Ruby Type: String
An optional property to set the package name if it differs from the resource block’s name.
source
- Ruby Type: String
The optional path to a package on the local file system.
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String
The version of a package to be installed or upgraded.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the macports_package resource in recipes:
Install a package
macports_package 'name of package' do
action :install
end
mdadm resource
mdadm resource pageUse the mdadm resource to manage RAID devices in a Linux environment using the mdadm utility. The mdadm resource will create and assemble an array, but it will not create the config file that is used to persist the array upon reboot. If the config file is required, it must be done by specifying a template with the correct array layout, and then by using the mount provider to create a file systems table (fstab) entry.
Syntax
The full syntax for all of the properties that are available to the mdadm resource is:
mdadm 'name' do
bitmap String
chunk Integer # default value: 16
devices Array # default value: []
layout String
level Integer # default value: 1
metadata String # default value: "0.90"
raid_device String # default value: 'name' unless specified
action Symbol # defaults to :create if not specified
end
where:
mdadm
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.bitmap
,chunk
,devices
,layout
,level
,metadata
, andraid_device
are the properties available to this resource.
Actions
The mdadm resource has the following actions:
:assemble
- Assemble a previously created array into an active array.
:create
- Create an array with per-device superblocks. If an array already exists (but does not match), update that array to match. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:stop
- Stop an active array.
Properties
The mdadm resource has the following properties:
bitmap
- Ruby Type: String
The path to a file in which a write-intent bitmap is stored.
chunk
- Ruby Type: Integer | Default Value:
16
The chunk size. This property should not be used for a RAID 1 mirrored pair (i.e. when the
level
property is set to1
).
devices
- Ruby Type: Array | Default Value:
[]
The devices to be part of a RAID array.
layout
- Ruby Type: String
The RAID5 parity algorithm. Possible values:
left-asymmetric
(orla
),left-symmetric
(or ls),right-asymmetric
(orra
), orright-symmetric
(orrs
).
level
- Ruby Type: Integer | Default Value:
1
The RAID level.
metadata
- Ruby Type: String | Default Value:
0.90
The superblock type for RAID metadata.
raid_device
- Ruby Type: String | Default Value:
The resource block's name
An optional property to specify the name of the RAID device if it differs from the resource block’s name.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the mdadm resource in recipes:
Create and assemble a RAID 0 array
The mdadm command can be used to create RAID arrays. For example, a RAID 0 array named /dev/md0 with 10 devices would have a command similar to the following:
mdadm --create /dev/md0 --level=0 --raid-devices=10 /dev/s01.../dev/s10
where /dev/s01 .. /dev/s10 represents 10 devices (01, 02, 03, and so on). This same command, when expressed as a recipe using the mdadm resource, would be similar to:
mdadm '/dev/md0' do
devices [ '/dev/s01', ... '/dev/s10' ]
level 0
action :create
end
(again, where /dev/s01 .. /dev/s10 represents devices /dev/s01, /dev/s02, /dev/s03, and so on).
Create and assemble a RAID 1 array
mdadm '/dev/md0' do
devices [ '/dev/sda', '/dev/sdb' ]
level 1
action [ :create, :assemble ]
end
Create and assemble a RAID 5 array
The mdadm command can be used to create RAID arrays. For example, a RAID 5 array named /dev/sd0 with 4, and a superblock type of 0.90 would be similar to:
mdadm '/dev/sd0' do
devices [ '/dev/s1', '/dev/s2', '/dev/s3', '/dev/s4' ]
level 5
metadata '0.90'
chunk 32
action :create
end
mount resource
mount resource pageUse the mount resource to manage a mounted file system.
Syntax
The full syntax for all of the properties that are available to the mount resource is:
mount 'name' do
device String
device_type String, Symbol # default value: :device
domain String
dump Integer, false # default value: 0
enabled true, false # default value: false
fsck_device String # default value: "-"
fstype String # default value: "auto"
mount_point String # default value: 'name' unless specified
options Array, String # default value: ["defaults"]
pass Integer, false # default value: 2
password String
supports Array, Hash # default value: "{ remount: false }"
username String
action Symbol # defaults to :mount if not specified
end
where:
mount
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.device
,device_type
,domain
,dump
,enabled
,fsck_device
,fstype
,mount_point
,options
,pass
,password
,supports
, andusername
are the properties available to this resource.
Actions
The mount resource has the following actions:
:disable
- Remove an entry from the file systems table (fstab).
:enable
- Add an entry to the file systems table (fstab).
:mount
- (default) Mount a device.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remount
- Remount a device
:umount
- Unmount a device.
:unmount
- Alias for the
:umount
action.
Properties
The mount resource has the following properties:
device
- Ruby Type: String
Required for
:umount
and:remount
actions (for the purpose of checking the mount command output for presence). The special block device or remote node, a label, or a uuid to be mounted.
device_type
- Ruby Type: String, Symbol | Default Value:
:device
Allowed Values::device, :label, :uuid
The type of device: :device, :label, or :uuid
domain
- Ruby Type: String
Windows only. Use to specify the domain in which the
username
andpassword
are located.
dump
- Ruby Type: Integer, false | Default Value:
0
The dump frequency (in days) used while creating a file systems table (fstab) entry.
enabled
- Ruby Type: true, false | Default Value:
false
Use to specify if a mounted file system is enabled.
fsck_device
- Ruby Type: String | Default Value:
-
Solaris only. The fsck device.
fstype
- Ruby Type: String | Default Value:
auto
The file system type of the device.
mount_point
- Ruby Type: String | Default Value:
The resource block's name
The directory (or path) in which the device is to be mounted. Defaults to the name of the resource block if not provided.
options
- Ruby Type: Array, String | Default Value:
["defaults"]
An array or comma separated list of options for the mount.
pass
- Ruby Type: Integer, false | Default Value:
2
The pass number used by the file system check (fsck) command while creating a file systems table (fstab) entry.
password
- Ruby Type: String
Windows only. Use to specify the password for username.
supports
- Ruby Type: Array, Hash | Default Value:
{ remount: false }
Specify a Hash of supported mount features.
username
- Ruby Type: String
Windows only. Use to specify the user name.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the mount resource in recipes:
Mount a labeled file system
mount '/mnt/volume1' do
device 'volume1'
device_type :label
fstype 'xfs'
options 'rw'
end
Mount a local block drive
mount '/mnt/local' do
device '/dev/sdb1'
fstype 'ext3'
end
Mount a non-block file system
mount '/mount/tmp' do
pass 0
fstype 'tmpfs'
device '/dev/null'
options 'nr_inodes=999k,mode=755,size=500m'
action [:mount, :enable]
end
Mount and add to the file systems table
mount '/export/www' do
device 'nas1prod:/export/web_sites'
fstype 'nfs'
options 'rw'
action [:mount, :enable]
end
Mount a remote file system
mount '/export/www' do
device 'nas1prod:/export/web_sites'
fstype 'nfs'
options 'rw'
end
Mount a remote folder in Microsoft Windows
mount 'T:' do
action :mount
device '\\\\hostname.example.com\\folder'
end
Unmount a remote folder in Microsoft Windows
mount 'T:' do
action :umount
device '\\\\hostname.example.com\\D$'
end
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
# 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 do FileTest.directory?(node['mysql']['ec2_path']) end
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
msu_package resource
msu_package resource pageUse the msu_package resource to install Microsoft Update(MSU) packages on Microsoft Windows machines.
New in Chef Infra Client 12.17.
Syntax
The full syntax for all of the properties that are available to the msu_package resource is:
msu_package 'name' do
checksum String
options String, Array
package_name String
source String
timeout String, Integer # default value: 3600
action Symbol # defaults to :install if not specified
end
where:
msu_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.checksum
,options
,package_name
,source
, andtimeout
are the properties available to this resource.
Actions
The msu_package resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The msu_package resource has the following properties:
checksum
- Ruby Type: String
SHA-256 digest used to verify the checksum of the downloaded MSU package.
options
- Ruby Type: String, Array
One (or more) additional command options that are passed to the command.
package_name
- Ruby Type: String
An optional property to set the package name if it differs from the resource block’s name.
source
- Ruby Type: String | Default Value:
lazy default
The local file path or URL for the MSU package.
timeout
- Ruby Type: String, Integer | Default Value:
3600
The amount of time (in seconds) to wait before timing out.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the msu_package resource in recipes:
Using local path in source
msu_package 'Install Windows 2012R2 Update KB2959977' do
source 'C:\Users\xyz\AppData\Local\Temp\Windows8.1-KB2959977-x64.msu'
action :install
end
msu_package 'Remove Windows 2012R2 Update KB2959977' do
source 'C:\Users\xyz\AppData\Local\Temp\Windows8.1-KB2959977-x64.msu'
action :remove
end
Using URL in source
msu_package 'Install Windows 2012R2 Update KB2959977' do
source 'https://s3.amazonaws.com/my_bucket/Windows8.1-KB2959977-x64.msu'
action :install
end
msu_package 'Remove Windows 2012R2 Update KB2959977' do
source 'https://s3.amazonaws.com/my_bucket/Windows8.1-KB2959977-x64.msu'
action :remove
end
notify_group resource
notify_group resource pageThe notify_group resource does nothing, and always fires notifications which are set on it. Use it to DRY blocks of notifications that are common to multiple resources, and provide a single target for other resources to notify. Unlike most resources, its default action is :nothing.
New in Chef Infra Client 15.8.
Syntax
The full syntax for all of the properties that are available to the notify_group resource is:
notify_group 'name' do
action Symbol # defaults to :nothing if not specified
end
where:
notify_group
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.
Actions
The notify_group resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run. (default)
:run
Properties
This resource does not have any properties.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the notify_group resource in recipes:
Wire up a notification from a service resource to stop and start the service with a 60 second delay.
service "crude" do
action [ :enable, :start ]
end
chef_sleep "60" do
action :nothing
end
# Example code for a hypothetical badly behaved service that requires
# 60 seconds between a stop and start in order to restart the service
# (due to race conditions, bleeding connections down, resources that only
# slowly unlock in the background, or other poor software behaviors that
# are sometimes encountered).
#
notify_group "crude_stop_and_start" do
notifies :stop, "service[crude]", :immediately
notifies :sleep, "chef_sleep[60]", :immediately
notifies :start, "service[crude]", :immediately
end
template "/etc/crude/crude.conf" do
source "crude.conf.erb"
variables node["crude"]
notifies :run, "notify_group[crude_stop_and_start]", :immediately
end
ohai resource
ohai resource pageUse the ohai resource to reload the Ohai configuration on a node. This allows recipes that change system attributes (like a recipe that adds a user) to refer to those attributes later on during the Chef Infra Client run.
Syntax
The full syntax for all of the properties that are available to the ohai resource is:
ohai 'name' do
plugin String
action Symbol # defaults to :reload if not specified
end
where:
ohai
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.plugin
is the property available to this resource.
Actions
The ohai resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:reload
- Reloads the Ohai data. (default)
Properties
The ohai resource has the following properties:
plugin
- Ruby Type: String
Specific Ohai attribute data to reload. This property behaves similar to specifying attributes when running Ohai on the command line and takes the attribute that you wish to reload instead of the actual plugin name. For instance, you can pass
ipaddress
to reloadnode['ipaddress']
even though that data comes from theNetwork
plugin. If this property is not specified, Chef Infra Client will reload all plugins.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the ohai resource in recipes:
Reload All Ohai Plugins
ohai 'reload' do
action :reload
end
Reload A Single Ohai Plugin
ohai 'reload' do
plugin 'ipaddress'
action :reload
end
Reload Ohai after a new user is created
ohai 'reload_passwd' do
action :nothing
plugin 'etc'
end
user 'daemon_user' do
home '/dev/null'
shell '/sbin/nologin'
system true
notifies :reload, 'ohai[reload_passwd]', :immediately
end
ruby_block 'just an example' do
block do
# These variables will now have the new values
puts node['etc']['passwd']['daemon_user']['uid']
puts node['etc']['passwd']['daemon_user']['gid']
end
end
ohai_hint resource
ohai_hint resource pageUse the ohai_hint resource to aid in configuration detection by passing hint data to Ohai.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the ohai_hint resource is:
ohai_hint 'name' do
compile_time true, false # default value: true
content Hash
hint_name String # default value: 'name' unless specified
action Symbol # defaults to :create if not specified
end
where:
ohai_hint
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.compile_time
,content
, andhint_name
are the properties available to this resource.
Actions
The ohai_hint resource has the following actions:
:create
- Create an Ohai hint file. (default)
:delete
- Delete an Ohai hint file.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The ohai_hint resource has the following properties:
compile_time
- Ruby Type: true, false | Default Value:
true
Determines whether or not the resource is executed during the compile time phase.
content
- Ruby Type: Hash
Values to include in the hint file.
hint_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the hint name if it differs from the resource block’s name.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the ohai_hint resource in recipes:
Create a hint file
ohai_hint 'example' do
content a: 'test_content'
end
Create a hint file with a name that does not match the resource name
ohai_hint 'example' do
hint_name 'custom'
end
Create a hint file that is not loaded at compile time
ohai_hint 'example' do
compile_time false
end
Delete a hint file
ohai_hint 'example' do
action :delete
end
openbsd_package resource
openbsd_package resource pageUse the openbsd_package resource to manage packages for the OpenBSD platform.
Note
New in Chef Infra Client 12.1.
Syntax
An openbsd_package resource block manages a package on a node, typically by installing it. The simplest use of the openbsd_package resource is:
openbsd_package 'package_name'
which will install the named package using all of the default options
and the default action (:install
).
The full syntax for all of the properties that are available to the openbsd_package resource is:
openbsd_package 'name' do
options String, Array
package_name String
source String
timeout String, Integer
version String
action Symbol # defaults to :install if not specified
end
where:
openbsd_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.options
,package_name
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The openbsd_package resource has the following actions:
:install
- Install a package. If a version is specified, install the specified version of the package. (default)
:remove
- Remove a package.
Properties
The openbsd_package resource has the following properties:
options
- Ruby Type: String, Array
One (or more) additional command options that are passed to the command.
package_name
- Ruby Type: String
An optional property to set the package name if it differs from the resource block’s name.
source
- Ruby Type: String
The optional path to a package on the local file system.
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String
The version of a package to be installed or upgraded.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the openbsd_package resource in recipes:
Install a package
openbsd_package 'name of package' do
action :install
end
Remove a package
openbsd_package 'name of package' do
action :remove
end
openssl_dhparam resource
openssl_dhparam resource pageUse the openssl_dhparam resource to generate dhparam.pem
files. If a valid dhparam.pem
file is found at the specified location, no new file will be created. If a file is found at the specified location but it is not a valid dhparam.pem
file, it will be overwritten.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the openssl_dhparam resource is:
openssl_dhparam 'name' do
generator Integer # default value: 2
group String, Integer
key_length Integer # default value: 2048
mode Integer, String # default value: "0640"
owner String, Integer
path String # default value: 'name' unless specified
action Symbol # defaults to :create if not specified
end
where:
openssl_dhparam
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.generator
,group
,key_length
,mode
,owner
, andpath
are the properties available to this resource.
Actions
The openssl_dhparam resource has the following actions:
:create
- Create the
dhparam.pem
file. (default) :nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The openssl_dhparam resource has the following properties:
generator
- Ruby Type: Integer | Default Value:
2
Allowed Values:2, 5
The desired Diffie-Hellmann generator.
group
- Ruby Type: String, Integer
The group ownership applied to all files created by the resource.
key_length
- Ruby Type: Integer | Default Value:
2048
Allowed Values:1024, 2048, 4096, 8192
The desired bit length of the generated key.
mode
- Ruby Type: Integer, String | Default Value:
0640
The permission mode applied to all files created by the resource.
owner
- Ruby Type: String, Integer
The owner applied to all files created by the resource.
path
- Ruby Type: String | Default Value:
The resource block's name
An optional property for specifying the path to write the file to if it differs from the resource block’s name.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the openssl_dhparam resource in recipes:
Create a dhparam file
openssl_dhparam '/etc/httpd/ssl/dhparam.pem'
Create a dhparam file with a specific key length
openssl_dhparam '/etc/httpd/ssl/dhparam.pem' do
key_length 4096
end
Create a dhparam file with specific user/group ownership
openssl_dhparam '/etc/httpd/ssl/dhparam.pem' do
owner 'www-data'
group 'www-data'
end
Manually specify the dhparam file path
openssl_dhparam 'httpd_dhparam' do
path '/etc/httpd/ssl/dhparam.pem'
end
openssl_ec_private_key resource
openssl_ec_private_key resource pageUse the openssl_ec_private_key resource to generate an elliptic curve (EC) private key file. If a valid EC key file can be opened at the specified location, no new file will be created. If the EC key file cannot be opened, either because it does not exist or because the password to the EC key file does not match the password in the recipe, then it will be overwritten.
New in Chef Infra Client 14.4.
Syntax
The full syntax for all of the properties that are available to the openssl_ec_private_key resource is:
openssl_ec_private_key 'name' do
force true, false # default value: false
group String, Integer
key_cipher String # default value: "des3"
key_curve String # default value: "prime256v1"
key_pass String
mode Integer, String # default value: "0600"
owner String, Integer
path String # default value: 'name' unless specified
action Symbol # defaults to :create if not specified
end
where:
openssl_ec_private_key
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.force
,group
,key_cipher
,key_curve
,key_pass
,mode
,owner
, andpath
are the properties available to this resource.
Actions
The openssl_ec_private_key resource has the following actions:
:create
- Generate the EC private key file. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The openssl_ec_private_key resource has the following properties:
force
- Ruby Type: true, false | Default Value:
false
Force creation of the key even if the same key already exists on the node.
group
- Ruby Type: String, Integer
The group ownership applied to all files created by the resource.
key_cipher
- Ruby Type: String | Default Value:
des3
The designed cipher to use when generating your key. Run
openssl list-cipher-algorithms
to see available options.
key_curve
- Ruby Type: String | Default Value:
prime256v1
Allowed Values:"prime256v1", "secp224r1", "secp256k1", "secp384r1", "secp521r1"
The desired curve of the generated key (if key_type is equal to ’ec’). Run openssl ecparam -list_curves to see available options.
key_pass
- Ruby Type: String
The desired passphrase for the key.
mode
- Ruby Type: Integer, String | Default Value:
0600
The permission mode applied to all files created by the resource.
owner
- Ruby Type: String, Integer
The owner applied to all files created by the resource.
path
- Ruby Type: String | Default Value:
The resource block's name
An optional property for specifying the path to write the file to if it differs from the resource block’s name.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the openssl_ec_private_key resource in recipes:
Generate a new ec privatekey with prime256v1 key curve and default des3 cipher
openssl_ec_private_key '/etc/ssl_files/eckey_prime256v1_des3.pem' do
key_curve 'prime256v1'
key_pass 'something'
action :create
end
Generate a new ec private key with prime256v1 key curve and aes-128-cbc cipher
openssl_ec_private_key '/etc/ssl_files/eckey_prime256v1_des3.pem' do
key_curve 'prime256v1'
key_cipher 'aes-128-cbc'
key_pass 'something'
action :create
end
openssl_ec_public_key resource
openssl_ec_public_key resource pageUse the openssl_ec_public_key resource to generate elliptic curve (EC) public key files from a given EC private key.
New in Chef Infra Client 14.4.
Syntax
The full syntax for all of the properties that are available to the openssl_ec_public_key resource is:
openssl_ec_public_key 'name' do
group String, Integer
mode Integer, String # default value: "0640"
owner String, Integer
path String # default value: 'name' unless specified
private_key_content String
private_key_pass String
private_key_path String
action Symbol # defaults to :create if not specified
end
where:
openssl_ec_public_key
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.group
,mode
,owner
,path
,private_key_content
,private_key_pass
, andprivate_key_path
are the properties available to this resource.
Actions
The openssl_ec_public_key resource has the following actions:
:create
- Generate the EC public key file from a private key. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The openssl_ec_public_key resource has the following properties:
group
- Ruby Type: String, Integer
The group ownership applied to all files created by the resource.
mode
- Ruby Type: Integer, String | Default Value:
0640
The permission mode applied to all files created by the resource.
owner
- Ruby Type: String, Integer
The owner applied to all files created by the resource.
path
- Ruby Type: String | Default Value:
The resource block's name
An optional property for specifying the path to write the file to if it differs from the resource block’s name.
private_key_content
- Ruby Type: String
The content of the private key including new lines. This property is used in place of private_key_path in instances where you want to avoid having to first write the private key to disk
private_key_pass
- Ruby Type: String
The passphrase of the provided private key.
private_key_path
- Ruby Type: String
The path to the private key file.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the openssl_ec_public_key resource in recipes:
Generate new EC public key from a private key on disk
openssl_ec_public_key '/etc/ssl_files/eckey_prime256v1_des3.pub' do
private_key_path '/etc/ssl_files/eckey_prime256v1_des3.pem'
private_key_pass 'something'
action :create
end
Generate new EC public key by passing in a private key
openssl_ec_public_key '/etc/ssl_files/eckey_prime256v1_des3_2.pub' do
private_key_content "-----BEGIN EC PRIVATE KEY-----
MHcCAQEEII2VAU9re44mAUzYPWCg+qqwdmP8CplsEg0b/DYPXLg2oAoGCCqGSM49
AwEHoUQDQgAEKkpMCbIQ2C6Qlp/B+Odp1a9Y06Sm8yqPvCVIkWYP7M8PX5+RmoIv
jGBVf/+mVBx77ji3NpTilMUt2KPZ87lZ3w==
-----END EC PRIVATE KEY-----
"
action :create
end
openssl_rsa_private_key resource
openssl_rsa_private_key resource pageUse the openssl_rsa_private_key resource to generate RSA private key files. If a valid RSA key file can be opened at the specified location, no new file will be created. If the RSA key file cannot be opened, either because it does not exist or because the password to the RSA key file does not match the password in the recipe, it will be overwritten.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the openssl_rsa_private_key resource is:
openssl_rsa_private_key 'name' do
force true, false # default value: false
group String, Integer
key_cipher String # default value: "des3"
key_length Integer # default value: 2048
key_pass String
mode Integer, String # default value: "0600"
owner String, Integer
path String # default value: 'name' unless specified
action Symbol # defaults to :create if not specified
end
where:
openssl_rsa_private_key
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.force
,group
,key_cipher
,key_length
,key_pass
,mode
,owner
, andpath
are the properties available to this resource.
Actions
The openssl_rsa_private_key resource has the following actions:
:create
- Create the RSA private key file. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The openssl_rsa_private_key resource has the following properties:
force
- Ruby Type: true, false | Default Value:
false
Force creation of the key even if the same key already exists on the node.
group
- Ruby Type: String, Integer
The group ownership applied to all files created by the resource.
key_cipher
- Ruby Type: String | Default Value:
des3
The designed cipher to use when generating your key. Run
openssl list-cipher-algorithms
to see available options.
key_length
- Ruby Type: Integer | Default Value:
2048
Allowed Values:1024, 2048, 4096, 8192
The desired bit length of the generated key.
key_pass
- Ruby Type: String
The desired passphrase for the key.
mode
- Ruby Type: Integer, String | Default Value:
0600
The permission mode applied to all files created by the resource.
owner
- Ruby Type: String, Integer
The owner applied to all files created by the resource.
path
- Ruby Type: String | Default Value:
The resource block's name
An optional property for specifying the path to write the file to if it differs from the resource block’s name.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the openssl_rsa_private_key resource in recipes:
Generate new 2048bit key with the default des3 cipher
openssl_rsa_private_key '/etc/ssl_files/rsakey_des3.pem' do
key_length 2048
action :create
end
Generate new 1024bit key with the aes-128-cbc cipher
openssl_rsa_private_key '/etc/ssl_files/rsakey_aes128cbc.pem' do
key_length 1024
key_cipher 'aes-128-cbc'
action :create
end
openssl_rsa_public_key resource
openssl_rsa_public_key resource pageUse the openssl_rsa_public_key resource to generate RSA public key files for a given RSA private key.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the openssl_rsa_public_key resource is:
openssl_rsa_public_key 'name' do
group String, Integer
mode Integer, String # default value: "0640"
owner String, Integer
path String # default value: 'name' unless specified
private_key_content String
private_key_pass String
private_key_path String
action Symbol # defaults to :create if not specified
end
where:
openssl_rsa_public_key
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.group
,mode
,owner
,path
,private_key_content
,private_key_pass
, andprivate_key_path
are the properties available to this resource.
Actions
The openssl_rsa_public_key resource has the following actions:
:create
- Create the RSA public key file. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The openssl_rsa_public_key resource has the following properties:
group
- Ruby Type: String, Integer
The group ownership applied to all files created by the resource.
mode
- Ruby Type: Integer, String | Default Value:
0640
The permission mode applied to all files created by the resource.
owner
- Ruby Type: String, Integer
The owner applied to all files created by the resource.
path
- Ruby Type: String | Default Value:
The resource block's name
An optional property for specifying the path to the public key if it differs from the resource block’s name.
private_key_content
- Ruby Type: String
The content of the private key, including new lines. This property is used in place of private_key_path in instances where you want to avoid having to first write the private key to disk.
private_key_pass
- Ruby Type: String
The passphrase of the provided private key.
private_key_path
- Ruby Type: String
The path to the private key file.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the openssl_rsa_public_key resource in recipes:
Generate new public key from a private key on disk
openssl_rsa_public_key '/etc/ssl_files/rsakey_des3.pub' do
private_key_path '/etc/ssl_files/rsakey_des3.pem'
private_key_pass 'something'
action :create
end
Generate new public key by passing in a private key
openssl_rsa_public_key '/etc/ssl_files/rsakey_2.pub' do
private_key_pass 'something'
private_key_content "-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: DES-EDE3-CBC,5EE0AE9A5FE3342E
yb930kj5/4/nd738dPx6XdbDrMCvqkldaz0rHNw8xsWvwARrl/QSPwROG3WY7ROl
EUttVlLaeVaqRPfQbmTUfzGI8kTMmDWKjw52gJUx2YJTYRgMHAB0dzYIRjeZAaeS
ypXnEfouVav+jKTmmehr1WuVKbzRhQDBSalzeUwsPi2+fb3Bfuo1dRW6xt8yFuc4
Akv1hCglymPzPHE2L0nSGjcgA2DZu+/S8/wZ4E63442NHPzO4VlLvpNvJrYpEWq9
B5mJzcdXPeOTjqd13olNTlOZMaKxu9QShu50GreCTVsl8VRkK8NtwbWuPGBZlIFa
jzlS/RaLuzNzfajaKMkcIYco9t7gN2DwnsACHKqEYT8248Ii3NQ+9/M5YcmpywQj
WGr0UFCSAdCky1lRjwT+zGQKohr+dVR1GaLem+rSZH94df4YBxDYw4rjsKoEhvXB
v2Vlx+G7Vl2NFiZzxUKh3MvQLr/NDElpG1pYWDiE0DIG13UqEG++cS870mcEyfFh
SF2SXYHLWyAhDK0viRDChJyFMduC4E7a2P9DJhL3ZvM0KZ1SLMwROc1XuZ704GwO
YUqtCX5OOIsTti1Z74jQm9uWFikhgWByhVtu6sYL1YTqtiPJDMFhA560zp/k/qLO
FKiM4eUWV8AI8AVwT6A4o45N2Ru8S48NQyvh/ADFNrgJbVSeDoYE23+DYKpzbaW9
00BD/EmUQqaQMc670vmI+CIdcdE7L1zqD6MZN7wtPaRIjx4FJBGsFoeDShr+LoTD
rwbadwrbc2Rf4DWlvFwLJ4pvNvdtY3wtBu79UCOol0+t8DVVSPVASsh+tp8XncDE
KRljj88WwBjX7/YlRWvQpe5y2UrsHI0pNy8TA1Xkf6GPr6aS2TvQD5gOrAVReSse
/kktCzZQotjmY1odvo90Zi6A9NCzkI4ZLgAuhiKDPhxZg61IeLppnfFw0v3H4331
V9SMYgr1Ftov0++x7q9hFPIHwZp6NHHOhdHNI80XkHqtY/hEvsh7MhFMYCgSY1pa
K/gMcZ/5Wdg9LwOK6nYRmtPtg6fuqj+jB3Rue5/p9dt4kfom4etCSeJPdvP1Mx2I
eNmyQ/7JN9N87FsfZsIj5OK9OB0fPdj0N0m1mlHM/mFt5UM5x39u13QkCt7skEF+
yOptXcL629/xwm8eg4EXnKFk330WcYSw+sYmAQ9ZTsBxpCMkz0K4PBTPWWXx63XS
c4J0r88kbCkMCNv41of8ceeGzFrC74dG7i3IUqZzMzRP8cFeps8auhweUHD2hULs
XwwtII0YQ6/Fw4hgGQ5//0ASdvAicvH0l1jOQScHzXC2QWNg3GttueB/kmhMeGGm
sHOJ1rXQ4oEckFvBHOvzjP3kuRHSWFYDx35RjWLAwLCG9odQUApHjLBgFNg9yOR0
jW9a2SGxRvBAfdjTa9ZBBrbjlaF57hq7mXws90P88RpAL+xxCAZUElqeW2Rb2rQ6
Cbz4/AtPekV1CYVodGkPutOsew2zjNqlNH+M8XzfonA60UAH20TEqAgLKwgfgr+a
c+rXp1AupBxat4EHYJiwXBB9XcVwyp5Z+/dXsYmLXzoMOnp8OFyQ9H8R7y9Y0PEu
-----END RSA PRIVATE KEY-----
"
action :create
end
openssl_x509_certificate resource
openssl_x509_certificate resource pageUse the openssl_x509_certificate resource to generate signed or self-signed, PEM-formatted x509 certificates. If no existing key is specified, the resource will automatically generate a passwordless key with the certificate. If a CA private key and certificate are provided, the certificate will be signed with them.
Note
This resource was renamed from openssl_x509 to openssl_x509_certificate. The legacy name will continue to function, but cookbook code should be updated for the new resource name.
New in Chef Infra Client 14.4.
Syntax
The full syntax for all of the properties that are available to the openssl_x509_certificate resource is:
openssl_x509_certificate 'name' do
ca_cert_file String
ca_key_file String
ca_key_pass String
city String
common_name String
country String
csr_file String
email String
expire Integer # default value: 365
extensions Hash # default value: {}
group String, Integer
key_curve String # default value: "prime256v1"
key_file String
key_length Integer # default value: 2048
key_pass String
key_type String # default value: "rsa"
mode Integer, String
org String
org_unit String
owner String, Integer
path String # default value: 'name' unless specified
renew_before_expiry Integer
state String
subject_alt_name Array # default value: []
action Symbol # defaults to :create if not specified
end
where:
openssl_x509_certificate
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.ca_cert_file
,ca_key_file
,ca_key_pass
,city
,common_name
,country
,csr_file
,email
,expire
,extensions
,group
,key_curve
,key_file
,key_length
,key_pass
,key_type
,mode
,org
,org_unit
,owner
,path
,renew_before_expiry
,state
, andsubject_alt_name
are the properties available to this resource.
Actions
The openssl_x509_certificate resource has the following actions:
:create
- Generate a certificate file. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The openssl_x509_certificate resource has the following properties:
ca_cert_file
- Ruby Type: String
The path to the CA X509 Certificate on the filesystem. If the
ca_cert_file
property is specified, theca_key_file
property must also be specified, the certificate will be signed with them.
ca_key_file
- Ruby Type: String
The path to the CA private key on the filesystem. If the
ca_key_file
property is specified, theca_cert_file
property must also be specified, the certificate will be signed with them.
ca_key_pass
- Ruby Type: String
The passphrase for CA private key’s passphrase.
city
- Ruby Type: String
Value for the
L
certificate field.
common_name
- Ruby Type: String
Value for the
CN
certificate field.
country
- Ruby Type: String
Value for the
C
certificate field.
csr_file
- Ruby Type: String
The path to a X509 Certificate Request (CSR) on the filesystem. If the
csr_file
property is specified, the resource will attempt to source a CSR from this location. If no CSR file is found, the resource will generate a Self-Signed Certificate and the certificate fields must be specified (common_name at last).
email
- Ruby Type: String
Value for the
email
certificate field.
expire
- Ruby Type: Integer | Default Value:
365
Value representing the number of days from now through which the issued certificate cert will remain valid. The certificate will expire after this period.
extensions
- Ruby Type: Hash | Default Value:
{}
Hash of X509 Extensions entries, in format
{ 'keyUsage' => { 'values' => %w( keyEncipherment digitalSignature), 'critical' => true } }
.
group
- Ruby Type: String, Integer
The group ownership applied to all files created by the resource.
key_curve
- Ruby Type: String | Default Value:
prime256v1
Allowed Values:"prime256v1", "secp384r1", "secp521r1"
The desired curve of the generated key (if key_type is equal to ’ec’). Run
openssl ecparam -list_curves
to see available options.
key_file
- Ruby Type: String
The path to a certificate key file on the filesystem. If the key_file property is specified, the resource will attempt to source a key from this location. If no key file is found, the resource will generate a new key file at this location. If the key_file property is not specified, the resource will generate a key file in the same directory as the generated certificate, with the same name as the generated certificate.
key_length
- Ruby Type: Integer | Default Value:
2048
Allowed Values:1024, 2048, 4096, 8192
The desired bit length of the generated key (if key_type is equal to ‘rsa’).
key_pass
- Ruby Type: String
The passphrase for an existing key’s passphrase.
key_type
- Ruby Type: String | Default Value:
rsa
Allowed Values:"ec", "rsa"
The desired type of the generated key.
mode
- Ruby Type: Integer, String
The permission mode applied to all files created by the resource.
org
- Ruby Type: String
Value for the
O
certificate field.
org_unit
- Ruby Type: String
Value for the
OU
certificate field.
owner
- Ruby Type: String, Integer
The owner applied to all files created by the resource.
path
- Ruby Type: String | Default Value:
The resource block's name
An optional property for specifying the path to write the file to if it differs from the resource block’s name.
renew_before_expiry
- Ruby Type: Integer
The number of days before the expiry. The certificate will be automatically renewed when the value is reached.
New in Chef Infra Client 15.7
state
- Ruby Type: String
Value for the
ST
certificate field.
subject_alt_name
- Ruby Type: Array | Default Value:
[]
Array of Subject Alternative Name entries, in format
DNS:example.com
orIP:1.2.3.4
.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the openssl_x509_certificate resource in recipes:
Create a simple self-signed certificate file
openssl_x509_certificate '/etc/httpd/ssl/mycert.pem' do
common_name 'www.f00bar.com'
org 'Foo Bar'
org_unit 'Lab'
country 'US'
end
Create a certificate using additional options
openssl_x509_certificate '/etc/ssl_files/my_signed_cert.crt' do
common_name 'www.f00bar.com'
ca_key_file '/etc/ssl_files/my_ca.key'
ca_cert_file '/etc/ssl_files/my_ca.crt'
expire 365
extensions(
'keyUsage' => {
'values' => %w(
keyEncipherment
digitalSignature),
'critical' => true,
},
'extendedKeyUsage' => {
'values' => %w(serverAuth),
'critical' => false,
}
)
subject_alt_name ['IP:127.0.0.1', 'DNS:localhost.localdomain']
end
openssl_x509_crl resource
openssl_x509_crl resource pageUse the openssl_x509_crl resource to generate PEM-formatted x509 certificate revocation list (CRL) files.
New in Chef Infra Client 14.4.
Syntax
The full syntax for all of the properties that are available to the openssl_x509_crl resource is:
openssl_x509_crl 'name' do
ca_cert_file String
ca_key_file String
ca_key_pass String
expire Integer # default value: 8
group String, Integer
mode Integer, String
owner String, Integer
path String # default value: 'name' unless specified
renewal_threshold Integer # default value: 1
revocation_reason Integer # default value: 0
serial_to_revoke Integer, String
action Symbol # defaults to :create if not specified
end
where:
openssl_x509_crl
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.ca_cert_file
,ca_key_file
,ca_key_pass
,expire
,group
,mode
,owner
,path
,renewal_threshold
,revocation_reason
, andserial_to_revoke
are the properties available to this resource.
Actions
The openssl_x509_crl resource has the following actions:
:create
- Create the certificate revocation list (CRL) file. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The openssl_x509_crl resource has the following properties:
ca_cert_file
- Ruby Type: String |
REQUIRED
The path to the CA X509 Certificate on the filesystem. If the
ca_cert_file
property is specified, theca_key_file
property must also be specified, the CRL will be signed with them.
ca_key_file
- Ruby Type: String |
REQUIRED
The path to the CA private key on the filesystem. If the
ca_key_file
property is specified, theca_cert_file
property must also be specified, the CRL will be signed with them.
ca_key_pass
- Ruby Type: String
The passphrase for CA private key’s passphrase.
expire
- Ruby Type: Integer | Default Value:
8
Value representing the number of days from now through which the issued CRL will remain valid. The CRL will expire after this period.
group
- Ruby Type: String, Integer
The group permission for the CRL file.
mode
- Ruby Type: Integer, String
The permission mode of the CRL file.
owner
- Ruby Type: String, Integer
The owner permission for the CRL file.
path
- Ruby Type: String | Default Value:
The resource block's name
An optional property for specifying the path to write the file to if it differs from the resource block’s name.
renewal_threshold
- Ruby Type: Integer | Default Value:
1
Number of days before the expiration. It this threshold is reached, the CRL will be renewed.
revocation_reason
- Ruby Type: Integer | Default Value:
0
Reason for the revocation.
serial_to_revoke
- Ruby Type: Integer, String
Serial of the X509 Certificate to revoke.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the openssl_x509_crl resource in recipes:
Create a certificate revocation file
openssl_x509_crl '/etc/ssl_test/my_ca.crl' do
ca_cert_file '/etc/ssl_test/my_ca.crt'
ca_key_file '/etc/ssl_test/my_ca.key'
end
Create a certificate revocation file for a particular serial
openssl_x509_crl '/etc/ssl_test/my_ca.crl' do
ca_cert_file '/etc/ssl_test/my_ca.crt'
ca_key_file '/etc/ssl_test/my_ca.key'
serial_to_revoke C7BCB6602A2E4251EF4E2827A228CB52BC0CEA2F
end
openssl_x509_request resource
openssl_x509_request resource pageUse the openssl_x509_request resource to generate PEM-formatted x509 certificates requests. If no existing key is specified, the resource will automatically generate a passwordless key with the certificate.
New in Chef Infra Client 14.4.
Syntax
The full syntax for all of the properties that are available to the openssl_x509_request resource is:
openssl_x509_request 'name' do
city String
common_name String
country String
email String
group String, Integer
key_curve String # default value: "prime256v1"
key_file String
key_length Integer # default value: 2048
key_pass String
key_type String # default value: "ec"
mode Integer, String
org String
org_unit String
owner String, Integer
path String # default value: 'name' unless specified
state String
action Symbol # defaults to :create if not specified
end
where:
openssl_x509_request
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.city
,common_name
,country
,email
,group
,key_curve
,key_file
,key_length
,key_pass
,key_type
,mode
,org
,org_unit
,owner
,path
, andstate
are the properties available to this resource.
Actions
The openssl_x509_request resource has the following actions:
:create
- Generate a certificate request file. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The openssl_x509_request resource has the following properties:
city
- Ruby Type: String
Value for the
L
certificate field.
common_name
- Ruby Type: String |
REQUIRED
Value for the
CN
certificate field.
country
- Ruby Type: String
Value for the
C
certificate field.
email
- Ruby Type: String
Value for the
email
certificate field.
group
- Ruby Type: String, Integer
The group ownership applied to all files created by the resource.
key_curve
- Ruby Type: String | Default Value:
prime256v1
Allowed Values:"prime256v1", "secp384r1", "secp521r1"
The desired curve of the generated key (if key_type is equal to
ec
). Runopenssl ecparam -list_curves
to see available options.
key_file
- Ruby Type: String
The path to a certificate key file on the filesystem. If the
key_file
property is specified, the resource will attempt to source a key from this location. If no key file is found, the resource will generate a new key file at this location. If thekey_file
property is not specified, the resource will generate a key file in the same directory as the generated certificate, with the same name as the generated certificate.
key_length
- Ruby Type: Integer | Default Value:
2048
Allowed Values:1024, 2048, 4096, 8192
The desired bit length of the generated key (if key_type is equal to
rsa
).
key_pass
- Ruby Type: String
The passphrase for an existing key’s passphrase.
key_type
- Ruby Type: String | Default Value:
ec
Allowed Values:"ec", "rsa"
The desired type of the generated key.
mode
- Ruby Type: Integer, String
The permission mode applied to all files created by the resource.
org
- Ruby Type: String
Value for the
O
certificate field.
org_unit
- Ruby Type: String
Value for the
OU
certificate field.
owner
- Ruby Type: String, Integer
The owner applied to all files created by the resource.
path
- Ruby Type: String | Default Value:
The resource block's name
An optional property for specifying the path to write the file to if it differs from the resource block’s name.
state
- Ruby Type: String
Value for the
ST
certificate field.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the openssl_x509_request resource in recipes:
Generate new EC key and CSR file
openssl_x509_request '/etc/ssl_files/my_ec_request.csr' do
common_name 'myecrequest.example.com'
org 'Test Kitchen Example'
org_unit 'Kitchens'
country 'UK'
end
Generate a new CSR file from an existing EC key
openssl_x509_request '/etc/ssl_files/my_ec_request2.csr' do
common_name 'myecrequest2.example.com'
org 'Test Kitchen Example'
org_unit 'Kitchens'
country 'UK'
key_file '/etc/ssl_files/my_ec_request.key'
end
Generate new RSA key and CSR file
openssl_x509_request '/etc/ssl_files/my_rsa_request.csr' do
common_name 'myrsarequest.example.com'
org 'Test Kitchen Example'
org_unit 'Kitchens'
country 'UK'
key_type 'rsa'
end
osx_profile resource
osx_profile resource pageUse the osx_profile resource to manage configuration profiles (.mobileconfig
files) on the macOS platform. The osx_profile resource installs profiles by using the uuidgen library to generate a unique ProfileUUID
, and then using the profiles
command to install the profile on the system.
New in Chef Infra Client 12.7.
Syntax
The full syntax for all of the properties that are available to the osx_profile resource is:
osx_profile 'name' do
identifier String
profile String, Hash
profile_name String # default value: 'name' unless specified
action Symbol # defaults to :install if not specified
end
where:
osx_profile
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.identifier
,profile
, andprofile_name
are the properties available to this resource.
Actions
The osx_profile resource has the following actions:
:install
- Install the specified configuration profile. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove the specified configuration profile.
Properties
The osx_profile resource has the following properties:
identifier
- Ruby Type: String
Use to specify the identifier for the profile, such as
com.company.screensaver
.
profile
- Ruby Type: String, Hash
Use to specify a profile. This may be the name of a profile contained in a cookbook or a Hash that contains the contents of the profile.
profile_name
- Ruby Type: String | Default Value:
The resource block's name
Use to specify the name of the profile, if different from the name of the resource block.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the osx_profile resource in recipes:
Install a profile from a cookbook file
osx_profile 'com.company.screensaver.mobileconfig'
Install profile from a hash
profile_hash = {
'PayloadIdentifier' => 'com.company.screensaver',
'PayloadRemovalDisallowed' => false,
'PayloadScope' => 'System',
'PayloadType' => 'Configuration',
'PayloadUUID' => '1781fbec-3325-565f-9022-8aa28135c3cc',
'PayloadOrganization' => 'Chef',
'PayloadVersion' => 1,
'PayloadDisplayName' => 'Screensaver Settings',
'PayloadContent' => [
{
'PayloadType' => 'com.apple.ManagedClient.preferences',
'PayloadVersion' => 1,
'PayloadIdentifier' => 'com.company.screensaver',
'PayloadUUID' => '73fc30e0-1e57-0131-c32d-000c2944c108',
'PayloadEnabled' => true,
'PayloadDisplayName' => 'com.apple.screensaver',
'PayloadContent' => {
'com.apple.screensaver' => {
'Forced' => [
{
'mcx_preference_settings' => {
'idleTime' => 0,
},
},
],
},
},
},
],
}
osx_profile 'Install screensaver profile' do
profile profile_hash
end
Remove profile using identifier in resource name
osx_profile 'com.company.screensaver' do
action :remove
end
Remove profile by identifier and user friendly resource name
osx_profile 'Remove screensaver profile' do
identifier 'com.company.screensaver'
action :remove
end
package resource
package resource pageUse the package resource to manage packages. When the package is installed from a local file (such as with RubyGems, dpkg, or RPM Package Manager), the file must be added to the node using the remote_file or cookbook_file resources.
This resource is the base resource for several other resources used for package management on specific platforms. While it is possible to use each of these specific resources, we recommend using the package resource as often as possible.
For more information about specific resources for specific platforms, see the following topics:
- apt_package
- bff_package
- cab_package
- chef_gem
- chocolatey_package
- dmg_package
- dnf_package
- dpkg_package
- freebsd_package
- gem_package
- homebrew_package
- ips_package
- macports_package
- msu_package
- openbsd_package
- pacman_package
- paludis_package
- portage_package
- rpm_package
- smartos_package
- snap_package
- solaris_package
- windows_package
- yum_package
- zypper_package
Syntax
A package resource block manages a package on a node, typically by installing it. The simplest use of the package resource is:
package 'httpd'
which will install Apache using all of the default options and the
default action (:install
).
For a package that has different package names, depending on the
platform, use a case
statement within the package:
package 'Install Apache' do
case node[:platform]
when 'redhat',
'centos'
package_name 'httpd'
when 'ubuntu', 'debian'
package_name
'apache2'
end
end
where:
'redhat', 'centos'
will install Apache using thehttpd
package and'ubuntu', 'debian'
will install it using theapache2
package
The full syntax for all of the properties that are available to the package resource is:
package 'name' do
options String, Array
package_name String, Array
source String
timeout String, Integer
version String, Array
action Symbol # defaults to :install if not specified
end
where:
package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.options
,package_name
,source
,timeout
, andversion
are the properties available to this resource.
Gem Package Options
The RubyGems package provider attempts to use the RubyGems API to install gems without spawning a new process, whenever possible. A gems command to install will be spawned under the following conditions:
- When a
gem_binary
property is specified (as a hash, a string, or by a .gemrc file), Chef Infra Client will run that command to examine its environment settings and then again to install the gem. - When install options are specified as a string, Chef Infra Client will span a gems command with those options when installing the gem.
- The Chef installer will search the
PATH
for a gem command rather than defaulting to the current gem environment. As part ofenforce_default_paths
, thebin
directories area added to thePATH
, which means when there are no other proceeding RubyGems, the installation will still be operated against it.
Specify with Hash
You should provide the install options as a hash if you are not using an explicit
gem_binary
parameter with the gem_package
resource. This approach allows the
provider to install the gem without needing to spawn an external gem process.
The following RubyGems options are available for inclusion within a hash and are passed to the RubyGems DependencyInstaller:
:env_shebang
:force
:format_executable
:ignore_dependencies
:prerelease
:security_policy
:wrappers
For more information about these options, see the RubyGems DependencyInstaller documentation.
Examplegem_package 'bundler' do
options(prerelease: true, format_executable: false)
end
Specify with String
When using an explicitgem_binary
, options must be passed as a string.
When not using an explicit gem_binary
, Chef Infra Client is forced to
spawn a gems process to install the gems (which uses more system
resources) when options are passed as a string. String options are
passed verbatim to the gems command and should be specified just as if
they were passed on a command line. For example, --prerelease
for a
pre-release gem.
Examplegem_package 'nokogiri' do
gem_binary('/opt/ree/bin/gem')
options('--prerelease --no-format-executable')
end
Specify with .gemrc File
Options can be specified in a .gemrc file. By default thegem_package
resource will use the Ruby interface to install gems which will ignore
the .gemrc file. The gem_package
resource can be forced to use the
gems command instead (and to read the .gemrc file) by adding the
gem_binary
attribute to a code block.A template named gemrc.erb
is located in a cookbook’s /templates
directory:
:sources:
- http://<%= node['gem_file']['host'] %>:<%= node['gem_file']['port'] %>/
A recipe can be built that does the following:
- Builds a
.gemrc
file based on agemrc.erb
template - Runs a
Gem.configuration
command - Installs a package using the
.gemrc
file
template '/root/.gemrc' do
source 'gemrc.erb'
action :create
notifies :run, 'ruby_block[refresh_gemrc]', :immediately
end
ruby_block 'refresh_gemrc' do
action :nothing
block do
Gem.configuration = Gem::ConfigFile.new []
end
end
gem_package 'di-ruby-lvm' do
gem_binary '/opt/chef/embedded/bin/gem'
action :install
end
Actions
The package resource has the following actions:
:install
- Install a package. If a version is specified, install the specified version of the package. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:purge
- Purge a package. This action typically removes the configuration files as well as the package.
:reconfig
- Reconfigure a package. This action requires a response file.
:remove
- Remove a package.
:upgrade
- Install a package and ensure that a package is the latest version.
Properties
The package resource has the following properties:
allow_downgrade
- Ruby Type: true, false | Default Value:
true
yum_package resource only. Downgrade a package to satisfy requested version requirements.
arch
- Ruby Type: String, Array
yum_package resource only. The architecture of the package to be installed or upgraded. This value can also be passed as part of the package name.
default_release
- Ruby Type: String
apt_package resource only. The default release. For example:
stable
.
flush_cache
- Ruby Type: Array
Flush the in-memory cache before or after a Yum operation that installs, upgrades, or removes a package. Default value:
[ :before, :after ]
. The value may also be a Hash:( { :before => true/false, :after => true/false } )
.Yum automatically synchronizes remote metadata to a local cache. Chef Infra Client creates a copy of the local cache, and then stores it in-memory during a Chef Infra Client run. The in-memory cache allows packages to be installed during a Chef Infra Client run without the need to continue synchronizing the remote metadata to the local cache while the Chef Infra Client run is in-progress.
As an array:
yum_package 'some-package' do #... flush_cache [ :before ] #... end
and as a Hash:
yum_package 'some-package' do #... flush_cache( { :after => true } ) #... end
Note
The
flush_cache
property does not flush the local Yum cache! Use Yum tools—yum clean headers
,yum clean packages
,yum clean all
—to clean the local Yum cache.
gem_binary
- Ruby Type: String
A property for the
gem_package
provider that is used to specify a gems binary.
homebrew_user
- Ruby Type: String, Integer
homebrew_package resource only. The name of the Homebrew owner to be used by Chef Infra Client when executing a command.
ignore_failure
- Ruby Type: true, false | Default Value:
false
Continue running a recipe if a resource fails for any reason.
notifies
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
notifies
is:notifies :action, 'resource[name]', :timer
options
- Ruby Type: String
One (or more) additional options that are passed to the command.
package_name
- Ruby Type: String, Array
The name of the package. Default value: the
name
of the resource block. See “Syntax” section above for more information.
response_file
- Ruby Type: String
apt_package and dpkg_package resources only. The direct path to the file used to pre-seed a package.
response_file_variables
- Ruby Type: Hash
apt_package and dpkg_package resources only. A Hash of response file variables in the form of
{"VARIABLE" => "VALUE"}
.
source
- Ruby Type: String
Optional. The path to a package in the local file system.
Note
The AIX platform requires
source
to be a local file system path becauseinstallp
does not retrieve packages using HTTP or FTP.
subscribes
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may listen to another resource, and then take action if the state of the resource being listened to changes. Specify a
'resource[name]'
, the:action
to be taken, and then the:timer
for that action.Note that
subscribes
does not apply the specified action to the resource that it listens to - for example:file '/etc/nginx/ssl/example.crt' do mode '0600' owner 'root' end service 'nginx' do subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately end
In this case the
subscribes
property reloads thenginx
service whenever its certificate file, located under/etc/nginx/ssl/example.crt
, is updated.subscribes
does not make any changes to the certificate file itself, it merely listens for a change to the file, and executes the:reload
action for its resource (in this examplenginx
) when a change is detected.If the other resource does not exist, the subscription will not raise an error. Contrast this with the stricter semantics of
notifies
, which will raise an error if the other resource does not exist.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
subscribes
is:subscribes :action, 'resource[name]', :timer
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String, Array
The version of a package to be installed or upgraded.
Multiple Packages
A resource may specify multiple packages and/or versions for platforms that use Apt, Chocolatey, DNF, Homebrew, Pacman, or Zypper package managers. Specifying multiple packages and/or versions allows a single transaction to:
- Download the specified packages and versions using a single HTTP transaction
- Update or install multiple packages with a single resource during a Chef Infra Client run
For example, installing multiple packages:
package %w(package1 package2)
Installing multiple packages with versions:
package %w(package1 package2) do
version [ '1.3.4-2', '4.3.6-1']
end
Upgrading multiple packages:
package %w(package1 package2) do
action :upgrade
end
Removing multiple packages:
package %w(package1 package2) do
action :remove
end
Purging multiple packages:
package %w(package1 package2) do
action :purge
end
Notifications, using an implicit name:
package %w(package1 package2) do
action :nothing
end
log 'call a notification' do
notifies :install, 'package[package1, package2]', :immediately
end
Note
Notifications and subscriptions do not need to be updated when packages
and versions are added or removed from the package_name
or version
properties.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Multiple Packages
A resource may specify multiple packages and/or versions for platforms that use Apt, Chocolatey, DNF, Homebrew, Pacman, or Zypper package managers. Specifying multiple packages and/or versions allows a single transaction to:
- Download the specified packages and versions using a single HTTP transaction
- Update or install multiple packages with a single resource during a Chef Infra Client run
For example, installing multiple packages:
package %w(package1 package2)
Installing multiple packages with versions:
package %w(package1 package2) do
version [ '1.3.4-2', '4.3.6-1']
end
Upgrading multiple packages:
package %w(package1 package2) do
action :upgrade
end
Removing multiple packages:
package %w(package1 package2) do
action :remove
end
Purging multiple packages:
package %w(package1 package2) do
action :purge
end
Notifications, using an implicit name:
package %w(package1 package2) do
action :nothing
end
log 'call a notification' do
notifies :install, 'package[package1, package2]', :immediately
end
Note
Notifications and subscriptions do not need to be updated when packages
and versions are added or removed from the package_name
or version
properties.
Examples
The following examples demonstrate various approaches for using the package resource in recipes:
Install a gems file for use in recipes
chef_gem 'right_aws' do
action :install
end
require 'right_aws'
Install a gems file from the local file system
gem_package 'right_aws' do
source '/tmp/right_aws-1.11.0.gem'
action :install
end
Install a package
package 'tar' do
action :install
end
Install a package version
package 'tar' do
version '1.16.1-1'
action :install
end
Install a package with options
package 'debian-archive-keyring' do
action :install
options '--force-yes'
end
Install a package with a response_file
Use of a response_file
is only supported on Debian and Ubuntu at this
time. Custom resources must be written to support the use of a
response_file
, which contains debconf answers to questions normally
asked by the package manager on installation. Put the file in
/files/default
of the cookbook where the package is specified and Chef
Infra Client will use the cookbook_file resource to retrieve it.
To install a package with a response_file
:
package 'sun-java6-jdk' do
response_file 'java.seed'
end
Install a specified architecture using a named provider
yum_package 'glibc-devel' do
arch 'i386'
end
Purge a package
package 'tar' do
action :purge
end
Remove a package
package 'tar' do
action :remove
end
Upgrade a package
package 'tar' do
action :upgrade
end
Use the ignore_failure
common attribute
gem_package 'syntax' do
action :install
ignore_failure true
end
Avoid unnecessary string interpolation
Do this:
package 'mysql-server' do
version node['mysql']['version']
action :install
end
and not this:
package 'mysql-server' do
version "#{node['mysql']['version']}"
action :install
end
Install a package in a platform
The following example shows how
to use the package resource to
install an application named app
and ensure
that the correct packages
are installed for the correct platform:
package 'app_name' do
action :install
end
case node[:platform]
when 'ubuntu','debian'
package 'app_name-doc' do
action :install
end
when 'centos'
package 'app_name-html' do
action :install
end
end
Install sudo, then configure /etc/sudoers/ file
The following example shows how to install sudo and then configure the
/etc/sudoers
file:
# the following code sample comes from the ``default``
# recipe in the ``sudo`` cookbook: https://github.com/chef-cookbooks/sudo
package 'sudo' do
action :install
end
if node['authorization']['sudo']['include_sudoers_d']
directory '/etc/sudoers.d' do
mode '0755'
owner 'root'
group 'root'
action :create
end
cookbook_file '/etc/sudoers.d/README' do
source 'README'
mode '0440'
owner 'root'
group 'root'
action :create
end
end
template '/etc/sudoers' do
source 'sudoers.erb'
mode '0440'
owner 'root'
group platform?('freebsd') ? 'wheel' : 'root'
variables(
:sudoers_groups => node['authorization']['sudo']['groups'],
:sudoers_users => node['authorization']['sudo']['users'],
:passwordless => node['authorization']['sudo']['passwordless']
)
end
where:
- the package resource is used to install sudo
- the
if
statement is used to ensure availability of the/etc/sudoers.d
directory - the template resource tells Chef Infra Client where to find the
sudoers
template - the
variables
property is a hash that passes values to template files (that are located in thetemplates/
directory for the cookbook
Use a case statement to specify the platform
The following example shows how to use a case statement to tell Chef Infra Client which platforms and packages to install using cURL.
package 'curl'
case node[:platform]
when 'redhat', 'centos'
package 'package_1'
package 'package_2'
package 'package_3'
when 'ubuntu', 'debian'
package 'package_a'
package 'package_b'
package 'package_c'
end
end
where node[:platform]
for each node is identified by Ohai during every Chef
Infra Client run. For example:
package 'curl'
case node[:platform]
when 'redhat', 'centos'
package 'zlib-devel'
package 'openssl-devel'
package 'libc6-dev'
when 'ubuntu', 'debian'
package 'openssl'
package 'pkg-config'
package 'subversion'
end
end
Use symbols to reference attributes
Symbols may be used to reference attributes:
package 'mysql-server' do
version node[:mysql][:version]
action :install
end
instead of strings:
package 'mysql-server' do
version node['mysql']['version']
action :install
end
Use a whitespace array to simplify a recipe
The following examples show different ways of doing the same thing. The first shows a series of packages that will be upgraded:
package 'package-a' do
action :upgrade
end
package 'package-b' do
action :upgrade
end
package 'package-c' do
action :upgrade
end
package 'package-d' do
action :upgrade
end
and the next uses a single package resource and a whitespace array (%w
):
package %w{package-a package-b package-c package-d} do
action :upgrade
end
Specify the Homebrew user with a UUID
homebrew_package 'emacs' do
homebrew_user 1001
end
Specify the Homebrew user with a string
homebrew_package 'vim' do
homebrew_user 'user1'
end
pacman_package resource
pacman_package resource pageUse the pacman_package resource to manage packages (using pacman) on the Arch Linux platform.
Note
Syntax
A pacman_package resource block manages a package on a node, typically by installing it. The simplest use of the pacman_package resource is:
pacman_package 'package_name'
which will install the named package using all of the default options
and the default action (:install
).
The full syntax for all of the properties that are available to the pacman_package resource is:
pacman_package 'name' do
options String, Array
package_name String, Array
source String
timeout String, Integer
version String, Array
action Symbol # defaults to :install if not specified
end
where:
pacman_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.options
,package_name
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The pacman_package resource has the following actions:
:install
- Install a package. If a version is specified, install the specified version of the package. (default)
:purge
- Purge a package. This action typically removes the configuration files as well as the package.
:remove
- Remove a package.
:upgrade
- Install a package and ensure that a package is the latest version.
Properties
The pacman_package resource has the following properties:
options
- Ruby Type: String, Array
One (or more) additional command options that are passed to the command.
package_name
- Ruby Type: String, Array
An optional property to set the package name if it differs from the resource block’s name.
source
- Ruby Type: String
The optional path to a package on the local file system.
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String, Array
The version of a package to be installed or upgraded.
Multiple Packages
A resource may specify multiple packages and/or versions for platforms that use Apt, Chocolatey, DNF, Homebrew, Pacman, or Zypper package managers. Specifying multiple packages and/or versions allows a single transaction to:
- Download the specified packages and versions using a single HTTP transaction
- Update or install multiple packages with a single resource during a Chef Infra Client run
For example, installing multiple packages:
package %w(package1 package2)
Installing multiple packages with versions:
package %w(package1 package2) do
version [ '1.3.4-2', '4.3.6-1']
end
Upgrading multiple packages:
package %w(package1 package2) do
action :upgrade
end
Removing multiple packages:
package %w(package1 package2) do
action :remove
end
Purging multiple packages:
package %w(package1 package2) do
action :purge
end
Notifications, using an implicit name:
package %w(package1 package2) do
action :nothing
end
log 'call a notification' do
notifies :install, 'package[package1, package2]', :immediately
end
Note
Notifications and subscriptions do not need to be updated when packages
and versions are added or removed from the package_name
or version
properties.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Multiple Packages
A resource may specify multiple packages and/or versions for platforms that use Apt, Chocolatey, DNF, Homebrew, Pacman, or Zypper package managers. Specifying multiple packages and/or versions allows a single transaction to:
- Download the specified packages and versions using a single HTTP transaction
- Update or install multiple packages with a single resource during a Chef Infra Client run
For example, installing multiple packages:
package %w(package1 package2)
Installing multiple packages with versions:
package %w(package1 package2) do
version [ '1.3.4-2', '4.3.6-1']
end
Upgrading multiple packages:
package %w(package1 package2) do
action :upgrade
end
Removing multiple packages:
package %w(package1 package2) do
action :remove
end
Purging multiple packages:
package %w(package1 package2) do
action :purge
end
Notifications, using an implicit name:
package %w(package1 package2) do
action :nothing
end
log 'call a notification' do
notifies :install, 'package[package1, package2]', :immediately
end
Note
Notifications and subscriptions do not need to be updated when packages
and versions are added or removed from the package_name
or version
properties.
Examples
The following examples demonstrate various approaches for using the pacman_package resource in recipes:
Install a package
pacman_package 'name of package' do
action :install
end
paludis_package resource
paludis_package resource pageUse the paludis_package resource to manage packages for the Paludis platform.
New in Chef Infra Client 12.1.
Syntax
A paludis_package resource block manages a package on a node, typically by installing it. The simplest use of the paludis_package resource is:
paludis_package 'package_name'
which will install the named package using all of the default options.
The full syntax for all of the properties that are available to the paludis_package resource is:
paludis_package 'name' do
options String, Array
package_name String
source String
timeout String, Integer # default value: 3600
version String
action Symbol # defaults to :install if not specified
end
where:
paludis_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.options
,package_name
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The paludis_package resource has the following actions:
:install
- Install a package. If a version is specified, install the specified version of the package. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove a package.
:upgrade
- Install a package and ensure that a package is the latest version.
Properties
The paludis_package resource has the following properties:
options
- Ruby Type: String, Array
One (or more) additional command options that are passed to the command.
package_name
- Ruby Type: String
An optional property to set the package name if it differs from the resource block’s name.
source
- Ruby Type: String
The optional path to a package on the local file system.
timeout
- Ruby Type: String, Integer | Default Value:
3600
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String
The version of a package to be installed or upgraded.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the paludis_package resource in recipes:
Install a package
paludis_package 'name of package' do
action :install
end
perl resource
perl resource pageUse the perl resource to execute scripts using the Perl interpreter. This resource may also use any of the actions and properties that are available to the execute resource. 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.
Syntax
A perl resource block executes scripts Perl:
perl 'hello world' do
code <<-EOH
print "Hello world! From Chef and Perl.";
EOH
end
where:
code
specifies the command to run.
where:
code
specifies the command to run
The full syntax for all of the properties that are available to the perl resource is:
perl 'name' do
code String
command String, Array # default value: 'name' unless specified
creates String
cwd String
default_env true, false # default value: false
domain String
elevated true, false # default value: false
environment Hash
flags String
group String, Integer
input String
interpreter String
live_stream true, false # default value: false
login true, false # default value: false
password String
returns Integer, Array # default value: 0
timeout Integer, String, Float # default value: 3600
user String, Integer
action Symbol # defaults to :run if not specified
end
where:
perl
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.code
,creates
,cwd
,environment
,flags
,group
,ignore_failure
,notifies
,returns
,subscribes
,timeout
,user
, andumask
are the properties available to this resource.
Actions
The perl resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:run
- Run a command. (default)
Properties
The perl resource has the following properties:
code
- Ruby Type: String |
REQUIRED
A quoted string of code to be executed.
creates
- Ruby Type: String
Prevent a command from creating a file when that file already exists.
cwd
- Ruby Type: String
The current working directory from which the command will be run.
environment
- Ruby Type: Hash
A Hash of environment variables in the form of
({"ENV_VARIABLE" => "VALUE"})
. (These variables must exist for a command to be run successfully.)
flags
- Ruby Type: String
One or more command line flags that are passed to the interpreter when a command is invoked.
group
- Ruby Type: String, Integer
The group name or group ID that must be changed before running a command.
ignore_failure
- Ruby Type: true, false
Continue running a recipe if a resource fails for any reason. (default false)
notifies
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
notifies
is:notifies :action, 'resource[name]', :timer
returns
- Ruby Type: Integer, Array | Default Value:
0
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.
subscribes
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may listen to another resource, and then take action if the state of the resource being listened to changes. Specify a
'resource[name]'
, the:action
to be taken, and then the:timer
for that action.Note that
subscribes
does not apply the specified action to the resource that it listens to - for example:file '/etc/nginx/ssl/example.crt' do mode '0600' owner 'root' end service 'nginx' do subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately end
In this case the
subscribes
property reloads thenginx
service whenever its certificate file, located under/etc/nginx/ssl/example.crt
, is updated.subscribes
does not make any changes to the certificate file itself, it merely listens for a change to the file, and executes the:reload
action for its resource (in this examplenginx
) when a change is detected.If the other resource does not exist, the subscription will not raise an error. Contrast this with the stricter semantics of
notifies
, which will raise an error if the other resource does not exist.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
subscribes
is:subscribes :action, 'resource[name]', :timer
timeout
- Ruby Type: Integer, String, Float | Default Value:
3600
The amount of time (in seconds) a command is to wait before timing out.
user
- Ruby Type: String, Integer
The user name or user ID that should be changed before running a command.
umask
- Ruby Type: String, Integer
The file mode creation mask, or umask.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
This resource does not have any examples.
plist resource
plist resource pageUse the plist resource to set config values in plist files on macOS systems.
New in Chef Infra Client 16.0.
Syntax
The full syntax for all of the properties that are available to the plist resource is:
plist 'name' do
encoding String # default value: "binary"
entry String
group String # default value: "wheel"
mode String, Integer
owner String # default value: "root"
path String # default value: 'name' unless specified
value true, false, String, Integer, Float, Hash
action Symbol # defaults to :set if not specified
end
where:
plist
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.encoding
,entry
,group
,mode
,owner
,path
, andvalue
are the properties available to this resource.
Actions
The plist resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:set
- Set a value in a plist file. (default)
Properties
The plist resource has the following properties:
encoding
- Ruby Type: String | Default Value:
binary
entry
- Ruby Type: String
group
- Ruby Type: String | Default Value:
wheel
The group of the plist file.
mode
- Ruby Type: String, Integer
The file mode of the plist file. Ex: ‘644’
owner
- Ruby Type: String | Default Value:
root
The owner of the plist file.
path
- Ruby Type: String | Default Value:
The resource block's name
The path on disk to the plist file.
value
- Ruby Type: true, false, String, Integer, Float, Hash
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the plist resource in recipes:
Show hidden files in finder:
plist 'show hidden files' do
path '/Users/vagrant/Library/Preferences/com.apple.finder.plist'
entry 'AppleShowAllFiles'
value true
end
portage_package resource
portage_package resource pageUse the portage_package resource to manage packages for the Gentoo platform.
Note
Syntax
The full syntax for all of the properties that are available to the portage_package resource is:
portage_package 'name' do
options String, Array
package_name String
source String
timeout String, Integer # default value: 3600
version String
action Symbol # defaults to :install if not specified
end
where:
portage_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.options
,package_name
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The portage_package resource has the following actions:
:install
- (default) Install a package. If a version is specified, install the specified version of the package.
:purge
- Purge a package. This action typically removes the configuration files as well as the package.
:remove
- Remove a package.
:upgrade
- Install a package and ensure that a package is the latest version.
Properties
The portage_package resource has the following properties:
options
- Ruby Type: String, Array
One (or more) additional command options that are passed to the command.
package_name
- Ruby Type: String
An optional property to set the package name if it differs from the resource block’s name.
source
- Ruby Type: String
The optional path to a package on the local file system.
timeout
- Ruby Type: String, Integer | Default Value:
3600
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String
The version of a package to be installed or upgraded.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the portage_package resource in recipes:
Install a package
portage_package 'name of package' do
action :install
end
powershell_package resource
powershell_package resource pageUse the powershell_package resource to install and manage packages with the PowerShell Package Manager for the Microsoft Windows platform. The powershell_package resource requires administrative access, and a source must be configured in the PowerShell Package Manager using the powershell_package_source resource.
New in Chef Infra Client 12.16.
Syntax
A powershell_package resource block manages a package on a node, typically by installing it. The simplest use of the powershell_package resource is:
powershell_package 'package_name'
which will install the named package using all of the default options and the default action (:install
).
The full syntax for all of the properties that are available to the powershell_package resource is:
powershell_package 'name' do
options String, Array
package_name String, Array
skip_publisher_check true, false # default value: false
source String
timeout String, Integer
version String, Array
action Symbol # defaults to :install if not specified
end
where:
powershell_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.options
,package_name
,skip_publisher_check
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The powershell_package resource has the following actions:
:install
- Install a package. If a version is specified, install the specified version of the package. (default)
:remove
- Remove a package.
Properties
The powershell_package resource has the following properties:
options
- Ruby Type: String, Array
One (or more) additional command options that are passed to the command.
package_name
- Ruby Type: String, Array
The name of the package. Default value: the name of the resource block.
skip_publisher_check
- Ruby Type: true, false | Default Value:
false
Skip validating module author.
New in Chef Client 14.3
source
- Ruby Type: String
Specify the source of the package.
New in Chef Client 14.0
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String, Array
The version of a package to be installed or upgraded.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the powershell_package resource in recipes:
Install a specific version of a package:
powershell_package 'xCertificate' do
action :install
version '1.1.0.0'
end
Install multiple packages:
powershell_package 'Install Multiple Packages' do
action :install
package_name %w(xCertificate xNetworking)
end
Install a package from a custom source:
powershell_package 'xCertificate' do
action :install
source 'MyGallery'
end
Install multiple packages, and specify package versions:
powershell_package 'Install Multiple Packages' do
action :install
package_name %w(xCertificate xNetworking)
version ['2.0.0.0', '2.12.0.0']
end
Install multiple packages, specifying the package version for one package but not the other:
powershell_package 'Install Multiple Packages' do
action :install
package_name %w(xCertificate xNetworking)
version [nil, '2.12.0.0']
end
In this example, the nil
tells powershell_package
to install the
most up to date version of xCertificate
that is available, while
pinning xNetworking
to version 2.12.0.0.
Remove a package:
powershell_package 'xCertificate' do
action :remove
end
powershell_package_source resource
powershell_package_source resource pageUse the powershell_package_source resource to register a PowerShell package source and a Powershell package provider. There are two distinct objects we care about here. The first is a package source like a PowerShell repository or a NuGet Source. The second object is a provider that PowerShell uses to get to that source with, like PowerShellGet, NuGet, Chocolatey, etc.
New in Chef Infra Client 14.3.
Syntax
The full syntax for all of the properties that are available to the powershell_package_source resource is:
powershell_package_source 'name' do
new_name String
password String
provider_name String # default value: "NuGet"
publish_location String
script_publish_location String
script_source_location String
source_location String
source_name String # default value: 'name' unless specified
trusted true, false # default value: false
user String
action Symbol # defaults to :register if not specified
end
where:
powershell_package_source
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.new_name
,password
,provider_name
,publish_location
,script_publish_location
,script_source_location
,source_location
,source_name
,trusted
, anduser
are the properties available to this resource.
Actions
The powershell_package_source resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:register
- Registers a PowerShell package source. (default)
:set
- Updates an existing PowerShell repository or package source.
:unregister
- Unregisters the PowerShell package source.
Properties
The powershell_package_source resource has the following properties:
new_name
- Ruby Type: String
Used to change the name of a standard package source.
New in Chef Infra Client 17.6
password
- Ruby Type: String
A password that, as part of a credential object, is used to register a repository or other package source with.
New in Chef Infra Client 17.6
provider_name
- Ruby Type: String | Default Value:
NuGet
Allowed Values:"NuGet", "PowerShellGet", "Programs", "chocolatey", "msi", "msu", "psl", "winget"
The package management provider for the package source. The default is
PowerShellGet
. Only change this option in specific use cases.
publish_location
- Ruby Type: String
The URL where modules will be published to. Only valid if the provider is
PowerShellGet
.
script_publish_location
- Ruby Type: String
The location where scripts will be published to for this source. Only valid if the provider is
PowerShellGet
.
script_source_location
- Ruby Type: String
The URL where scripts are located for this source. Only valid if the provider is
PowerShellGet
.
source_location
- Ruby Type: String
The URL to the location to retrieve modules from.
New in Chef Infra Client 17.6
source_name
- Ruby Type: String | Default Value:
The resource block's name
A label that names your package source.
trusted
- Ruby Type: true, false | Default Value:
false
Whether or not to trust packages from this source. Used when creating a non-PowerShell repository package source.
user
- Ruby Type: String
A username that, as part of a credential object, is used to register a repository or other package source with.
New in Chef Infra Client 17.6
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the powershell_package_source resource in recipes:
Add a new PowerShell repository that is not trusted and which requires credentials to connect to:
powershell_package_source 'PowerShellModules' do
source_name "PowerShellModules"
source_location "https://pkgs.dev.azure.com/some-org/some-project/_packaging/some_feed/nuget/v2"
publish_location "https://pkgs.dev.azure.com/some-org/some-project/_packaging/some_feed/nuget/v2"
trusted false
user "someuser@somelocation.io"
password "my_password"
provider_name "PSRepository"
action :register
end
Add a new package source that uses Chocolatey as the package provider:
powershell_package_source 'PowerShellModules' do
source_name "PowerShellModules"
source_location "https://pkgs.dev.azure.com/some-org/some-project/_packaging/some_feed/nuget/v2"
publish_location "https://pkgs.dev.azure.com/some-org/some-project/_packaging/some_feed/nuget/v2"
trusted true
provider_name "chocolatey"
action :register
end
Add a new PowerShell script source that is trusted:
powershell_package_source 'MyDodgyScript' do
source_name "MyDodgyScript"
script_source_location "https://pkgs.dev.azure.com/some-org/some-project/_packaging/some_feed/nuget/v2"
script_publish_location "https://pkgs.dev.azure.com/some-org/some-project/_packaging/some_feed/nuget/v2"
trusted true
action :register
end
Update an existing PowerShell repository to make it trusted:
powershell_package_source 'MyPSModule' do
source_name "MyPSModule"
trusted true
action :set
end
Update a Nuget package source with a new name and make it trusted:
powershell_package_source 'PowerShellModules -> GoldFishBowl' do
source_name "PowerShellModules"
new_name "GoldFishBowl"
provider_name "Nuget"
trusted true
action :set
end
Update a Nuget package source with a new name when the source is secured with a username and password:
powershell_package_source 'PowerShellModules -> GoldFishBowl' do
source_name "PowerShellModules"
new_name "GoldFishBowl"
trusted true
user "user@domain.io"
password "some_secret_password"
action :set
end
Unregister a package source:
powershell_package_source 'PowerShellModules' do
source_name "PowerShellModules"
action :unregister
end
powershell_script resource
powershell_script resource pageUse the powershell_script resource to execute a script using the Windows PowerShell interpreter, much like how the script and script-based resources bash, csh, perl, python, and ruby are used. The powershell_script resource is specific to the Microsoft Windows platform, but may use both the Windows PowerShell interpreter or the PowerShell Core (pwsh) interpreter as of Chef Infra Client 16.6 and later.
The powershell_script resource creates and executes a temporary file rather than running the command inline. 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
conditionals to guard this resource for idempotence.
Syntax
A powershell_script resource block executes a batch script using the Windows PowerShell interpreter. For example, writing to an interpolated path:
powershell_script 'write-to-interpolated-path' do
code <<-EOH
$stream = [System.IO.StreamWriter] "#{Chef::Config[:file_cache_path]}/powershell-test.txt"
$stream.WriteLine("In #{Chef::Config[:file_cache_path]}...word.")
$stream.close()
EOH
end
The full syntax for all of the properties that are available to the powershell_script resource is:
powershell_script 'name' do
code String
command String, Array # default value: 'name' unless specified
convert_boolean_return true, false # default value: false
creates String
cwd String
domain String
elevated true, false # default value: false
environment Hash
flags String
group String, Integer
input String
interpreter String # default value: "powershell"
live_stream true, false # default value: false
password String
returns Integer, Array # default value: 0
timeout Integer, String, Float # default value: 3600
use_inline_powershell true, false # default value: false
user String, Integer
action Symbol # defaults to :run if not specified
end
where:
powershell_script
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.code
,command
,convert_boolean_return
,creates
,cwd
,domain
,elevated
,environment
,flags
,group
,input
,interpreter
,live_stream
,password
,returns
,timeout
,use_inline_powershell
, anduser
are the properties available to this resource.
Actions
The powershell_script resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:run
- Run a command. (default)
Properties
The powershell_script resource has the following properties:
code
- Ruby Type: String |
REQUIRED
A quoted string of code to be executed.
command
- Ruby Type: String, Array | Default Value:
The resource block's name
An optional property to set the command to be executed if it differs from the resource block’s name.
convert_boolean_return
- Ruby Type: true, false | Default Value:
false
Return
0
if the last line of a command is evaluated to be true or to return1
if the last line is evaluated to be false.When the
guard_interpreter
common attribute is set to:powershell_script
, a string command will be evaluated as if this value were set totrue
. This is because the behavior of this attribute is similar to the value of the"$?"
expression common in UNIX interpreters. For example, this:powershell_script 'make_safe_backup' do guard_interpreter :powershell_script code 'cp ~/data/nodes.json ~/data/nodes.bak' not_if 'test-path ~/data/nodes.bak' end
is similar to:
bash 'make_safe_backup' do code 'cp ~/data/nodes.json ~/data/nodes.bak' not_if 'test -e ~/data/nodes.bak' end
creates
- Ruby Type: String
Prevent a command from creating a file when that file already exists.
cwd
- Ruby Type: String
The current working directory from which the command will be run.
domain
- Ruby Type: String
Windows only: The domain of the user specified by the user property. If not specified, the username and password specified by the
user
andpassword
properties will be used to resolve that user against the domain in which the system running Chef Infra 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.New in Chef Client 12.21
elevated
- Ruby Type: true, false | Default Value:
false
Determines whether the script will run with elevated permissions to circumvent User Access Control (UAC) from interactively blocking the process. This will cause the process to be run under a batch login instead of an interactive login. The user running chef-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. Because this requires a login, the user and password properties are required.
New in Chef Client 13.3
environment
- Ruby Type: Hash
A Hash of environment variables in the form of
({'ENV_VARIABLE' => 'VALUE'})
. Note: These variables must exist for a command to be run successfully.
flags
- Ruby Type: String
A string that is passed to the Windows PowerShell command value (Windows PowerShell 3.0+):
-NoLogo
-NonInteractive
-NoProfile
-ExecutionPolicy Bypass
-InputFormat None
group
- Ruby Type: String, Integer
The group name or group ID that must be changed before running a command.
guard_interpreter
- Ruby Type: Symbol | Default Value:
:powershell_script
When this property is set to
:powershell_script
, the 64-bit version of the Windows PowerShell shell will be used to evaluate strings values for thenot_if
andonly_if
properties. Set this value to:default
to use the 32-bit version of the cmd.exe shell.
input
- Ruby Type: String
An optional property to set the input sent to the command as STDIN.
New in Chef Infra Client 16.2
interpreter
- Ruby Type: String | Default Value:
powershell
Allowed Values:"powershell", "pwsh"
The interpreter type,
powershell
orpwsh
(PowerShell Core)
live_stream
- Ruby Type: true, false | Default Value:
false
Send the output of the command run by this execute resource block to the Chef Infra Client event stream.
password
- Ruby Type: String
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.
New in Chef Client 12.21
returns
- Ruby Type: Integer, Array | Default Value:
0
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.
timeout
- Ruby Type: Integer, String, Float | Default Value:
3600
The amount of time (in seconds) a command is to wait before timing out.
use_inline_powershell
- Ruby Type: true, false | Default Value:
false
Use the inline PowerShell DLL rather than shelling out. The PowerShell DLL is faster, but its semantics could be different from shelling out. In particular, it doesn’t allow for streaming output, nor does it allow for passing custom parameters to the interpreter.
New in Chef Infra Client 18.4
user
- Ruby Type: String, Integer
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.
domain\user
oruser@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.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the powershell_script resource in recipes:
Write to an interpolated path:
powershell_script 'write-to-interpolated-path' do
code <<-EOH
$stream = [System.IO.StreamWriter] "#{Chef::Config[:file_cache_path]}/powershell-test.txt"
$stream.WriteLine("In #{Chef::Config[:file_cache_path]}...word.")
$stream.close()
EOH
end
Change the working directory:
powershell_script 'cwd-then-write' do
cwd Chef::Config[:file_cache_path]
code <<-EOH
$stream = [System.IO.StreamWriter] "C:/powershell-test2.txt"
$pwd = pwd
$stream.WriteLine("This is the contents of: $pwd")
$dirs = dir
foreach ($dir in $dirs) {
$stream.WriteLine($dir.fullname)
}
$stream.close()
EOH
end
Change the working directory in Microsoft Windows:
powershell_script 'cwd-to-win-env-var' do
cwd '%TEMP%'
code <<-EOH
$stream = [System.IO.StreamWriter] "./temp-write-from-chef.txt"
$stream.WriteLine("chef on windows rox yo!")
$stream.close()
EOH
end
Pass an environment variable to a script:
powershell_script 'read-env-var' do
cwd Chef::Config[:file_cache_path]
environment ({'foo' => 'BAZ'})
code <<-EOH
$stream = [System.IO.StreamWriter] "./test-read-env-var.txt"
$stream.WriteLine("FOO is $env:foo")
$stream.close()
EOH
end
Evaluate for true and/or false:
Use the convert_boolean_return
attribute to raise an exception when
certain conditions are met. For example, the following fragments will
run successfully without error:
powershell_script 'false' do
code '$false'
end
and:
powershell_script 'true' do
code '$true'
end
whereas the following will raise an exception:
powershell_script 'false' do
convert_boolean_return true
code '$false'
end
Use the flags attribute:
powershell_script 'Install IIS' do
code <<-EOH
Import-Module ServerManager
Add-WindowsFeature Web-Server
EOH
flags '-NoLogo, -NonInteractive, -NoProfile, -ExecutionPolicy Unrestricted, -InputFormat None, -File'
guard_interpreter :powershell_script
not_if '(Get-WindowsFeature -Name Web-Server).Installed'
end
Rename computer, join domain, reboot:
The following example shows how to rename a computer, join a domain, and then reboot the computer:
reboot 'Restart Computer' do
action :nothing
end
powershell_script 'Rename and Join Domain' do
code <<-EOH
...your rename and domain join logic here...
EOH
not_if <<-EOH
$ComputerSystem = gwmi win32_computersystem
($ComputerSystem.Name -like '#{node['some_attribute_that_has_the_new_name']}') -and
$ComputerSystem.partofdomain)
EOH
notifies :reboot_now, 'reboot[Restart Computer]', :immediately
end
where:
- The powershell_script resource block renames a computer, and then joins a domain.
- The reboot resource restarts the computer.
- The
not_if
guard prevents the Windows PowerShell script from running when the settings in thenot_if
guard match the desired state. - The
notifies
statement tells the reboot resource block to run if the powershell_script block was executed during a Chef Infra Client run.
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:
# 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.
# Passing only username and password
powershell_script 'mkdir test_dir' do
code "mkdir test_dir"
cwd Chef::Config[:file_cache_path]
user "username"
password "password"
end
# Passing username and domain
powershell_script 'mkdir test_dir' do
code "mkdir test_dir"
cwd Chef::Config[:file_cache_path]
domain "domain"
user "username"
password "password"
end
# Passing username = 'domain-name\\username'. No domain is passed
powershell_script 'mkdir test_dir' do
code "mkdir test_dir"
cwd Chef::Config[:file_cache_path]
user "domain-name\\username"
password "password"
end
# Passing username = 'username@domain-name'. No domain is passed
powershell_script 'mkdir test_dir' do
code "mkdir test_dir"
cwd Chef::Config[:file_cache_path]
user "username@domain-name"
password "password"
end
# Work around User Access Control (UAC)
powershell_script 'mkdir test_dir' do
code "mkdir test_dir"
cwd Chef::Config[:file_cache_path]
user "username"
password "password"
elevated true
end
python resource
python resource pageUse the python resource to execute scripts using the Python interpreter. This resource may also use any of the actions and properties that are available to the execute resource. 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.
Syntax
The python resource has the following syntax:
python 'hello world' do
code <<-EOH
print "Hello world! From Chef and Python."
EOH
end
The full syntax for all of the properties that are available to the python resource is:
python 'name' do
code String
command String, Array # default value: 'name' unless specified
creates String
cwd String
default_env true, false # default value: false
domain String
elevated true, false # default value: false
environment Hash
flags String
group String, Integer
input String
interpreter String
live_stream true, false # default value: false
login true, false # default value: false
password String
returns Integer, Array # default value: 0
timeout Integer, String, Float # default value: 3600
user String, Integer
action Symbol # defaults to :run if not specified
end
where:
python
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.code
,command
,creates
,cwd
,default_env
,domain
,elevated
,environment
,flags
,group
,input
,interpreter
,live_stream
,login
,password
,returns
,timeout
, anduser
are the properties available to this resource.
Actions
The python resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:run
- Run a command. (default)
Properties
The python resource has the following properties:
code
- Ruby Type: String |
REQUIRED
A quoted string of code to be executed.
creates
- Ruby Type: String
Prevent a command from creating a file when that file already exists.
cwd
- Ruby Type: String
The current working directory from which the command will be run.
environment
- Ruby Type: Hash
A Hash of environment variables in the form of
({'ENV_VARIABLE' => 'VALUE'})
. Note: These variables must exist for a command to be run successfully.
flags
- Ruby Type: String
One or more command line flags that are passed to the interpreter when a command is invoked.
group
- Ruby Type: String, Integer
The group name or group ID that must be changed before running a command.
ignore_failure
- Ruby Type: true, false | Default Value:
false
Continue running a recipe if a resource fails for any reason.
notifies
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
notifies
is:notifies :action, 'resource[name]', :timer
returns
- Ruby Type: Integer, Array | Default Value:
0
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.
subscribes
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may listen to another resource, and then take action if the state of the resource being listened to changes. Specify a
'resource[name]'
, the:action
to be taken, and then the:timer
for that action.Note that
subscribes
does not apply the specified action to the resource that it listens to - for example:file '/etc/nginx/ssl/example.crt' do mode '0600' owner 'root' end service 'nginx' do subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately end
In this case the
subscribes
property reloads thenginx
service whenever its certificate file, located under/etc/nginx/ssl/example.crt
, is updated.subscribes
does not make any changes to the certificate file itself, it merely listens for a change to the file, and executes the:reload
action for its resource (in this examplenginx
) when a change is detected.If the other resource does not exist, the subscription will not raise an error. Contrast this with the stricter semantics of
notifies
, which will raise an error if the other resource does not exist.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
subscribes
is:subscribes :action, 'resource[name]', :timer
timeout
- Ruby Type: Integer, String, Float | Default Value:
3600
The amount of time (in seconds) a command is to wait before timing out.
umask
- Ruby Type: String, Integer
The file mode creation mask, or umask.
user
- Ruby Type: String, Integer
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.
domain\user
oruser@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.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
This resource does not have any examples.
reboot resource
reboot resource pageUse the reboot resource to reboot a node, a necessary step with some installations on certain platforms. This resource is supported for use on the Microsoft Windows, macOS, and Linux platforms. In using this resource via notifications, it’s important to only use immediate notifications. Delayed notifications produce unintuitive and probably undesired results.
New in Chef Infra Client 12.0.
Syntax
The full syntax for all of the properties that are available to the reboot resource is:
reboot 'name' do
delay_mins Integer # default value: 0
reason String # default value: "Reboot by Chef Infra Client"
action Symbol # defaults to :nothing if not specified
end
where:
reboot
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.delay_mins
andreason
are the properties available to this resource.
Actions
The reboot resource has the following actions:
:cancel
- Cancel a pending reboot request.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run. (default)
:reboot_now
- Reboot a node so that the Chef Infra Client may continue the installation process.
:request_reboot
- Reboot a node at the end of a Chef Infra Client run.
Properties
The reboot resource has the following properties:
delay_mins
- Ruby Type: Integer | Default Value:
0
The amount of time (in minutes) to delay a reboot request.
reason
- Ruby Type: String | Default Value:
Reboot by Chef Infra Client
A string that describes the reboot action.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the reboot resource in recipes:
Reboot a node immediately
reboot 'now' do
action :nothing
reason 'Cannot continue Chef run without a reboot.'
delay_mins 2
end
execute 'foo' do
command '...'
notifies :reboot_now, 'reboot[now]', :immediately
end
Reboot a node at the end of a Chef Infra Client run
reboot 'app_requires_reboot' do
action :request_reboot
reason 'Need to reboot when the run completes successfully.'
delay_mins 5
end
Cancel a reboot
reboot 'cancel_reboot_request' do
action :cancel
reason 'Cancel a previous end-of-run reboot request.'
end
registry_key resource
registry_key resource pageUse the registry_key resource to create and delete registry keys in Microsoft Windows.
Note
64-bit versions of Microsoft Windows have a 32-bit compatibility layer in the registry that reflects and redirects certain keys (and their values) into specific locations (or logical views) of the registry hive.
Chef Infra Client can access any reflected or redirected registry key. The machine architecture of the system on which Chef Infra Client is running is used as the default (non-redirected) location. Access to the SysWow64 location is redirected must be specified. Typically, this is only necessary to ensure compatibility with 32-bit applications that are running on a 64-bit operating system.
For more information, see Microsoft’s documentation on Registry Reflection.
Syntax
A registry_key resource block creates and deletes registry keys in Microsoft Windows:
registry_key 'HKEY_LOCAL_MACHINE\\...\\System' do
values [{
name: 'NewRegistryKeyValue',
type: :multi_string,
data: %w(foo bar baz),
}]
action :create
end
Use multiple registry key entries with key values that are based on node attributes:
registry_key 'HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\name_of_registry_key' do
values [{name: 'key_name', type: :string, data: 'C:\Windows\System32\file_name.bmp'},
{name: 'key_name', type: :string, data: node['node_name']['attribute']['value']},
{name: 'key_name', type: :string, data: node['node_name']['attribute']['value']}
]
action :create
end
The full syntax for all of the properties that are available to the registry_key resource is:
registry_key 'name' do
architecture Symbol # default value: :machine
key String # default value: 'name' unless specified
recursive true, false # default value: false
values Hash, Array # default value: []
action Symbol # defaults to :create if not specified
end
where:
registry_key
is the resourcename
is the name of the resource blockvalues
is a hash that contains at least one registry key to be created or deleted. Each registry key in the hash is grouped by brackets in which thename:
,type:
, anddata:
values for that registry key are specified.type:
represents the values available for registry keys in Microsoft Windows::binary
for REG_BINARY:string
for REG_SZ:multi_string
for REG_MULTI_SZ:expand_string
for REG_EXPAND_SZ:dword
for REG_DWORD:dword_big_endian
for REG_DWORD_BIG_ENDIAN:qword
for REG_QWORD
Warning
:multi_string
must be an array, even if there is only a single string.action
identifies the steps Chef Infra Client will take to bring the node into the desired statearchitecture
,key
,recursive
andvalues
are properties of this resource, with the Ruby type shown. See “Properties” section below for more information about all of the properties that may be used with this resource.
Registry Key Path Separators
A Windows registry key can be used as a string in Ruby code,
such as when a registry key is used as the name of a recipe. In Ruby,
when a registry key is enclosed in a double-quoted string (" "
), the
same backslash character (\
) that is used to define the registry key
path separator is also used in Ruby to define an escape character.
Therefore, the registry key path separators must be escaped when they
are enclosed in a double-quoted string. For example, the following
registry key:
HKCU\SOFTWARE\Policies\Microsoft\Windows\CurrentVersion\Themes
may be enclosed in a single-quoted string with a single backslash:
'HKCU\SOFTWARE\path\to\key\Themes'
or may be enclosed in a double-quoted string with an extra backslash as an escape character:
"HKCU\\SOFTWARE\\path\\to\\key\\Themes"
Chef Infra Language Methods
Six methods are present in the Chef Infra Language to help verify the registry during a Chef Infra Client run on the Windows platform—registry_data_exists?
, registry_get_subkeys
,
registry_get_values
, registry_has_subkeys?
, registry_key_exists?
,
and registry_value_exists?
—these helpers ensure the
powershell_script resource is idempotent.registry_data_exists?
Use theregistry_data_exists?
method to find out if a Microsoft
Windows registry key contains the specified data of the specified type
under the value.Note
not_if
and
only_if
blocks in resources. This method is not designed to create or
modify a registry key. If a registry key needs to be modified, use the
registry_key resource.The syntax for the registry_data_exists?
method is as follows:
registry_data_exists?(
KEY_PATH,
{ name: 'NAME', type: TYPE, data: DATA },
ARCHITECTURE
)
where:
KEY_PATH
is the path to the registry key value. The path must include the registry hive, which can be specified either as its full name or as the 3- or 4-letter abbreviation. For example, bothHKLM\SECURITY
andHKEY_LOCAL_MACHINE\SECURITY
are both valid and equivalent. The following hives are valid:HKEY_LOCAL_MACHINE
,HKLM
,HKEY_CURRENT_CONFIG
,HKCC
,HKEY_CLASSES_ROOT
,HKCR
,HKEY_USERS
,HKU
,HKEY_CURRENT_USER
, andHKCU
.{ name: 'NAME', type: TYPE, data: DATA }
is a hash that contains the expected name, type, and data of the registry key valuetype:
represents the values available for registry keys in Windows. Use:binary
for REG_BINARY,:string
for REG_SZ,:multi_string
for REG_MULTI_SZ,:expand_string
for REG_EXPAND_SZ,:dword
for REG_DWORD,:dword_big_endian
for REG_DWORD_BIG_ENDIAN, or:qword
for REG_QWORD.ARCHITECTURE
is one of the following values::x86_64
,:i386
, or:machine
. Set to:i386
to read or write 32-bit registry keys on 64-bit machines running Windows. Set to:x86_64
to force write to a 64-bit registry location, however Chef Infra Client returns an exception if:x86_64
is used on a 32-bit machine. Set to:machine
to allow Chef Infra Client to allow Chef Infra Client to use the appropriate key location based on your node’s architecture. Default value::machine
.
This method will return true
or false
.
registry_get_subkeys
Use theregistry_get_subkeys
method to get a list of registry key
values that are present for a Windows registry key.Note
not_if
and
only_if
blocks in resources. This method is not designed to create or
modify a registry key. If a registry key needs to be modified, use the
registry_key resource.The syntax for the registry_get_subkeys
method is as follows:
subkey_array = registry_get_subkeys(KEY_PATH, ARCHITECTURE)
where:
KEY_PATH
is the path to the registry key. The path must include the registry hive, which can be specified either as its full name or as the 3- or 4-letter abbreviation. For example, bothHKLM\SECURITY
andHKEY_LOCAL_MACHINE\SECURITY
are both valid and equivalent. The following hives are valid:HKEY_LOCAL_MACHINE
,HKLM
,HKEY_CURRENT_CONFIG
,HKCC
,HKEY_CLASSES_ROOT
,HKCR
,HKEY_USERS
,HKU
,HKEY_CURRENT_USER
, andHKCU
.ARCHITECTURE
is one of the following values::x86_64
,:i386
, or:machine
. Set to:i386
to read or write 32-bit registry keys on 64-bit machines running Windows. Set to:x86_64
to force write to a 64-bit registry location, however Chef Infra Client returns an exception if:x86_64
is used on a 32-bit machine. Set to:machine
to allow Chef Infra Client to allow Chef Infra Client to use the appropriate key location based on your node’s architecture. Default value::machine
.
This returns an array of registry key values.
registry_get_values
Use theregistry_get_values
method to get the registry key values
(name, type, and data) for a Windows registry key.Note
not_if
and
only_if
blocks in resources. This method is not designed to create or
modify a registry key. If a registry key needs to be modified, use the
registry_key resource.The syntax for the registry_get_values
method is as follows:
subkey_array = registry_get_values(KEY_PATH, ARCHITECTURE)
where:
KEY_PATH
is the path to the registry key. The path must include the registry hive, which can be specified either as its full name or as the 3- or 4-letter abbreviation. For example, bothHKLM\SECURITY
andHKEY_LOCAL_MACHINE\SECURITY
are both valid and equivalent. The following hives are valid:HKEY_LOCAL_MACHINE
,HKLM
,HKEY_CURRENT_CONFIG
,HKCC
,HKEY_CLASSES_ROOT
,HKCR
,HKEY_USERS
,HKU
,HKEY_CURRENT_USER
, andHKCU
.ARCHITECTURE
is one of the following values::x86_64
,:i386
, or:machine
. Set to:i386
to read or write 32-bit registry keys on 64-bit machines running Windows. Set to:x86_64
to force write to a 64-bit registry location, however Chef Infra Client returns an exception if:x86_64
is used on a 32-bit machine. Set to:machine
to allow Chef Infra Client to allow Chef Infra Client to use the appropriate key location based on your node’s architecture. Default value::machine
.
This returns an array of registry key values.
registry_has_subkeys?
Use theregistry_has_subkeys?
method to find out if a Microsoft
Windows registry key has one (or more) values.Note
not_if
and
only_if
blocks in resources. This method is not designed to create or
modify a registry key. If a registry key needs to be modified, use the
registry_key resource.The syntax for the registry_has_subkeys?
method is as follows:
registry_has_subkeys?(KEY_PATH, ARCHITECTURE)
where:
KEY_PATH
is the path to the registry key. The path must include the registry hive, which can be specified either as its full name or as the 3- or 4-letter abbreviation. For example, bothHKLM\SECURITY
andHKEY_LOCAL_MACHINE\SECURITY
are both valid and equivalent. The following hives are valid:HKEY_LOCAL_MACHINE
,HKLM
,HKEY_CURRENT_CONFIG
,HKCC
,HKEY_CLASSES_ROOT
,HKCR
,HKEY_USERS
,HKU
,HKEY_CURRENT_USER
, andHKCU
.ARCHITECTURE
is one of the following values::x86_64
,:i386
, or:machine
. Set to:i386
to read or write 32-bit registry keys on 64-bit machines running Windows. Set to:x86_64
to force write to a 64-bit registry location, however Chef Infra Client returns an exception if:x86_64
is used on a 32-bit machine. Set to:machine
to allow Chef Infra Client to allow Chef Infra Client to use the appropriate key location based on your node’s architecture. Default value::machine
.
This method will return true
or false
.
registry_key_exists?
Use theregistry_key_exists?
method to find out if a Windows
registry key exists at the specified path.Note
not_if
and
only_if
blocks in resources. This method is not designed to create or
modify a registry key. If a registry key needs to be modified, use the
registry_key resource.The syntax for the registry_key_exists?
method is as follows:
registry_key_exists?(KEY_PATH, ARCHITECTURE)
where:
KEY_PATH
is the path to the registry key. The path must include the registry hive, which can be specified either as its full name or as the 3- or 4-letter abbreviation. For example, bothHKLM\SECURITY
andHKEY_LOCAL_MACHINE\SECURITY
are both valid and equivalent. The following hives are valid:HKEY_LOCAL_MACHINE
,HKLM
,HKEY_CURRENT_CONFIG
,HKCC
,HKEY_CLASSES_ROOT
,HKCR
,HKEY_USERS
,HKU
,HKEY_CURRENT_USER
, andHKCU
.ARCHITECTURE
is one of the following values::x86_64
,:i386
, or:machine
. Set to:i386
to read or write 32-bit registry keys on 64-bit machines running Windows. Set to:x86_64
to force write to a 64-bit registry location, however Chef Infra Client returns an exception if:x86_64
is used on a 32-bit machine. Set to:machine
to allow Chef Infra Client to allow Chef Infra Client to use the appropriate key location based on your node’s architecture. Default value::machine
.
This method will return true
or false
. (Any registry key values that
are associated with this registry key are ignored.)
registry_value_exists?
Use theregistry_value_exists?
method to find out if a registry key
value exists. Use registry_data_exists?
to test for the type and data
of a registry key value.Note
not_if
and
only_if
blocks in resources. This method is not designed to create or
modify a registry key. If a registry key needs to be modified, use the
registry_key resource.The syntax for the registry_dvalue_exists?
method is as follows:
registry_value_exists?(
KEY_PATH,
{ name: 'NAME' },
ARCHITECTURE
)
where:
KEY_PATH
is the path to the registry key. The path must include the registry hive, which can be specified either as its full name or as the 3- or 4-letter abbreviation. For example, bothHKLM\SECURITY
andHKEY_LOCAL_MACHINE\SECURITY
are both valid and equivalent. The following hives are valid:HKEY_LOCAL_MACHINE
,HKLM
,HKEY_CURRENT_CONFIG
,HKCC
,HKEY_CLASSES_ROOT
,HKCR
,HKEY_USERS
,HKU
,HKEY_CURRENT_USER
, andHKCU
.{ name: 'NAME' }
is a hash that contains the name of the registry key value; if eithertype:
or:value
are specified in the hash, they are ignoredtype:
represents the values available for registry keys in Windows. Use:binary
for REG_BINARY,:string
for REG_SZ,:multi_string
for REG_MULTI_SZ,:expand_string
for REG_EXPAND_SZ,:dword
for REG_DWORD,:dword_big_endian
for REG_DWORD_BIG_ENDIAN, or:qword
for REG_QWORD.ARCHITECTURE
is one of the following values::x86_64
,:i386
, or:machine
. Set to:i386
to read or write 32-bit registry keys on 64-bit machines running Windows. Set to:x86_64
to force write to a 64-bit registry location, however Chef Infra Client returns an exception if:x86_64
is used on a 32-bit machine. Set to:machine
to allow Chef Infra Client to allow Chef Infra Client to use the appropriate key location based on your node’s architecture. Default value::machine
.
This method will return true
or false
.
Actions
The registry_key resource has the following actions:
:create
- (default) Create a registry key. If a registry key already exists (but does not match), update that registry key to match.
:create_if_missing
- Create a registry key if it does not exist. Also, create a registry key value if it does not exist.
:delete
- Delete the specified values for a registry key.
:delete_key
- Delete the specified registry key and all of its subkeys. The
:delete_key
action with therecursive
attribute will delete the registry key, all of its values and all of the names, types, and data associated with them. This cannot be undone by Chef Infra Client. :nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The registry_key resource has the following properties:
architecture
- Ruby Type: Symbol | Default Value:
:machine
Allowed Values::i386, :machine, :x86_64
The architecture of the node for which keys are to be created or deleted. Possible values:
:i386
(for nodes with a 32-bit registry),:x86_64
(for nodes with a 64-bit registry), and:machine
(to have Chef Infra Client determine the architecture during a Chef Infra Client run).In order to read or write 32-bit registry keys on 64-bit machines running Microsoft Windows, the
architecture
property must be set to:i386
. The:x86_64
value can be used to force writing to a 64-bit registry location, but this value is less useful than the default (:machine
) because Chef Infra Client returns an exception if:x86_64
is used and the machine turns out to be a 32-bit machine (whereas with:machine
, Chef Infra Client is able to access the registry key on the 32-bit machine).
key
- Ruby Type: String | Default Value:
The resource block's name
The path to the location in which a registry key is to be created or from which a registry key is to be deleted. Default value: the
name
of the resource block. See “Syntax” section above for more information. The path must include the registry hive, which can be specified either as its full name or as the 3- or 4-letter abbreviation. For example, bothHKLM\SECURITY
andHKEY_LOCAL_MACHINE\SECURITY
are both valid and equivalent. The following hives are valid:HKEY_LOCAL_MACHINE
,HKLM
,HKEY_CURRENT_CONFIG
,HKCC
,HKEY_CLASSES_ROOT
,HKCR
,HKEY_USERS
,HKU
,HKEY_CURRENT_USER
, andHKCU
.
recursive
- Ruby Type: true, false | Default Value:
false
When creating a key, this value specifies that the required keys for the specified path are to be created. When using the
:delete_key
action in a recipe, and if the registry key has subkeys, then set the value for this property totrue
. The:delete_key
action with therecursive
attribute will delete the registry key, all of its values and all of the names, types, and data associated with them. This cannot be undone by Chef Infra Client.
values
- Ruby Type: Hash, Array | Default Value:
[]
An array of hashes, where each Hash contains the values that are to be set under a registry key. Each Hash must contain
name:
,type:
, anddata:
(and must contain no other key values).type:
represents the values available for registry keys in Microsoft Windows. Use:binary
for REG_BINARY,:string
for REG_SZ,:multi_string
for REG_MULTI_SZ,:expand_string
for REG_EXPAND_SZ,:dword
for REG_DWORD,:dword_big_endian
for REG_DWORD_BIG_ENDIAN, or:qword
for REG_QWORD.Warning
:multi_string
must be an array, even if there is only a single string.
Examples
The following examples demonstrate various approaches for using the registry_key resource in recipes:
Create a registry key:
registry_key 'HKEY_LOCAL_MACHINE\\path-to-key\\Policies\\System' do
values [{
name: 'EnableLUA',
type: :dword,
data: 0
}]
action :create
end
Create a registry key with binary data: “\x01\x02\x03”:
registry_key 'HKEY_CURRENT_USER\ChefTest' do
values [{
:name => "test",
:type => :binary,
:data => [0, 1, 2].map(&:chr).join
}]
action :create
end
Create 32-bit key in redirected wow6432 tree:
In 64-bit versions of Microsoft Windows, HKEY_LOCAL_MACHINE\SOFTWARE\Example is a re-directed key. In the following examples, because HKEY_LOCAL_MACHINE\SOFTWARE\Example is a 32-bit key, the output will be �Found 32-bit key� if they are run on a version of Microsoft Windows that is 64-bit:
registry_key 'HKEY_LOCAL_MACHINE\SOFTWARE\Example' do
architecture :i386
recursive true
action :create
end
Set proxy settings to be the same as those used by #{ChefUtils::Dist::Infra::PRODUCT}:
proxy = URI.parse(Chef::Config[:http_proxy])
registry_key 'HKCU\Software\Microsoft\path\to\key\Internet Settings' do
values [{name: 'ProxyEnable', type: :reg_dword, data: 1},
{name: 'ProxyServer', data: "#{proxy.host}:#{proxy.port}"},
{name: 'ProxyOverride', type: :reg_string, data: <local>},
]
action :create
end
Set the name of a registry key to “(Default)”:
registry_key 'Set (Default) value' do
key 'HKLM\Software\Test\Key\Path'
values [
{name: '', type: :string, data: 'test'},
]
action :create
end
Delete a registry key value:
registry_key 'HKEY_LOCAL_MACHINE\SOFTWARE\path\to\key\AU' do
values [{
name: 'NoAutoRebootWithLoggedOnUsers',
type: :dword,
data: ''
}]
action :delete
end
Note: If data is not specified, Chef Infra Client returns error: “Missing data key in RegistryKey values hash”.
Delete a registry key and its subkeys, recursively:
registry_key 'HKCU\SOFTWARE\Policies\path\to\key\Themes' do
recursive true
action :delete_key
end
Note: Be careful when using the :delete_key
action with the recursive attribute. This will delete the registry key, all of its values
and all of the names, types, and data associated with them. This cannot be undone by #{ChefUtils::Dist::Infra::PRODUCT}
.
remote_directory resource
remote_directory resource pageUse the remote_directory resource to incrementally transfer a directory from a cookbook to a node. The directory that is copied from the cookbook should be located under COOKBOOK_NAME/files/default/REMOTE_DIRECTORY
. The remote_directory
resource will obey file specificity.
Syntax
A remote_directory resource block transfers a directory from a cookbook to a node, and then assigns the permissions needed on that directory. For example:
remote_directory '/etc/apache2' do
source 'apache2'
owner 'root'
group 'root'
mode '0755'
action :create
end
The full syntax for all of the properties that are available to the remote_directory resource is:
remote_directory 'name' do
cookbook String
files_backup Integer, false # default value: 5
files_group String, Integer
files_mode String, Integer # default value: "0644 on *nix systems"
files_owner String, Integer
group
mode
overwrite true, false # default value: true
owner
path String # default value: 'name' unless specified
purge true, false # default value: false
recursive true, false # default value: true
source String
action Symbol # defaults to :create if not specified
end
where:
remote_directory
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.cookbook
,files_backup
,files_group
,files_mode
,files_owner
,group
,mode
,overwrite
,owner
,path
,purge
,recursive
, andsource
are the properties available to this resource.
Actions
The remote_directory resource has the following actions:
:create
- Create a directory. If a directory already exists (but does not match), update that directory to match. (default)
:create_if_missing
- Create a directory and/or the contents of that directory, but only if it does not exist.
:delete
- Delete a directory, including the contents of that directory.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The remote_directory resource has the following properties:
cookbook
- Ruby Type: String
The cookbook in which a file is located (if it is not located in the current cookbook). The default value is the current cookbook.
files_backup
- Ruby Type: Integer, false | Default Value:
5
The number of backup copies to keep for files in the directory.
files_group
- Ruby Type: String, Integer
Configure group permissions for files. A string or ID that identifies the group owner by group name, including fully qualified group names such as
domain\group
orgroup@domain
. If this value is not specified, existing groups remain unchanged and new group assignments use the default POSIX group (if available).
files_mode
- Ruby Type: String, Integer | Default Value:
0644 on *nix systems
The octal mode for a file.
UNIX- and Linux-based systems: A quoted 3-5 character string that defines the octal mode that is passed to chmod. For example:
'755'
,'0755'
, or'00755'
. If the value is specified as a quoted string, it works exactly as if the chmod command was passed. If the value is specified as an integer, prepend a zero (0) to the value to ensure that it is interpreted as an octal number. For example, to assign read, write, and execute rights for all users, use'0777'
or'777'
; for the same rights, plus the sticky bit, use'01777'
or'1777'
.Microsoft Windows: A quoted 3-5 character string that defines the octal mode that is translated into rights for Microsoft Windows security. For example:
'755'
,'0755'
, or'00755'
. Values up to'0777'
are allowed (no sticky bits) and mean the same in Microsoft Windows as they do in UNIX, where 4 equals GENERIC_READ, 2 equals GENERIC_WRITE, and 1 equals GENERIC_EXECUTE. This property cannot be used to set:full_control
. This property has no effect if not specified, but when it and rights are both specified, the effects are cumulative.
files_owner
- Ruby Type: String, Integer
Configure owner permissions for files. A string or ID that identifies the group owner by user name, including fully qualified user names such as
domain\user
oruser@domain
. If this value is not specified, existing owners remain unchanged and new owner assignments use the current user (when necessary).
group
- Ruby Type: Integer, String
Use to configure permissions for directories. A string or ID that identifies the group owner by group name or SID, including fully qualified group names such as
domain\group
orgroup@domain
. If this value is not specified, existing groups remain unchanged and new group assignments use the defaultPOSIX
group (if available).
inherits
- Ruby Type: true, false | Default Value:
true
Microsoft Windows only. Whether a file inherits rights from its parent directory.
mode
- Ruby Type: Integer, String
A quoted 3-5 character string that defines the octal mode. For example:
'755'
,'0755'
, or00755
. Ifmode
is not specified and if the directory already exists, the existing mode on the directory is used. Ifmode
is not specified, the directory does not exist, and the:create
action is specified, Chef Infra Client assumes a mask value of'0777'
, and then applies the umask for the system on which the directory is to be created to themask
value. For example, if the umask on a system is'022'
, Chef Infra Client uses the default value of'0755'
.The behavior is different depending on the platform.
UNIX- and Linux-based systems: A quoted 3-5 character string that defines the octal mode that is passed to chmod. For example:
'755'
,'0755'
, or00755
. If the value is specified as a quoted string, it works exactly as if thechmod
command was passed. If the value is specified as an integer, prepend a zero (0
) to the value to ensure that it is interpreted as an octal number. For example, to assign read, write, and execute rights for all users, use'0777'
or'777'
; for the same rights, plus the sticky bit, use01777
or'1777'
.Microsoft Windows: A quoted 3-5 character string that defines the octal mode that is translated into rights for Microsoft Windows security. For example:
'755'
,'0755'
, or00755
. Values up to'0777'
are allowed (no sticky bits) and mean the same in Microsoft Windows as they do in UNIX, where4
equalsGENERIC_READ
,2
equalsGENERIC_WRITE
, and1
equalsGENERIC_EXECUTE
. This property cannot be used to set:full_control
. This property has no effect if not specified, but when it andrights
are both specified, the effects are cumulative.
overwrite
- Ruby Type: true, false | Default Value:
true
Overwrite a file when it is different.
owner
- Ruby Type: Integer, String
Use to configure permissions for directories. A string or ID that identifies the group owner by user name or SID, including fully qualified user names such as
domain\user
oruser@domain
. If this value is not specified, existing owners remain unchanged and new owner assignments use the current user (when necessary).
path
- Ruby Type: String | Default Value:
The resource block's name
The path to the directory. Using a fully qualified path is recommended, but is not always required.
purge
- Ruby Type: true, false | Default Value:
false
Purge extra files found in the target directory.
recursive
- Ruby Type: true, false | Default Value:
true
Create or delete parent directories recursively. For the owner, group, and mode properties, the value of this attribute applies only to the leaf directory.
rights
- Ruby Type: Integer, String
Microsoft Windows only. The permissions for users and groups in a Microsoft Windows environment. For example: rights
, , where specifies the rights granted to the principal, is the group or user name, and is a Hash with one (or more) advanced rights options.
source
- Ruby Type: String | Default Value:
The base portion of the 'path' property. For example '/some/path/' would be 'path'.
The base name of the source file (and inferred from the
path
property). For example, in the default value, ‘/some/path/’ would be ‘path’.
Recursive Directories
The remote_directory resource can be used to recursively create the
path outside of remote directory structures, but the permissions of
those outside paths are not managed. This is because the recursive
attribute only applies group
, mode
, and owner
attribute values to
the remote directory itself and any inner directories the resource
copies.
A directory structure:
/foo
/bar
/baz
The following example shows a way create a file in the /baz
directory:
remote_directory '/foo/bar/baz' do
owner 'root'
group 'root'
mode '0755'
action :create
end
But with this example, the group
, mode
, and owner
attribute values
will only be applied to /baz
. Which is fine, if that’s what you want.
But most of the time, when the entire /foo/bar/baz
directory structure
is not there, you must be explicit about each directory. For example:
%w( /foo /foo/bar /foo/bar/baz ).each do |path|
remote_directory path do
owner 'root'
group 'root'
mode '0755'
end
end
This approach will create the correct hierarchy—/foo
, then /bar
in
/foo
, and then /baz
in /bar
—and also with the correct attribute
values for group
, mode
, and owner
.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Recursive Directories
The remote_directory resource can be used to recursively create the
path outside of remote directory structures, but the permissions of
those outside paths are not managed. This is because the recursive
attribute only applies group
, mode
, and owner
attribute values to
the remote directory itself and any inner directories the resource
copies.
A directory structure:
/foo
/bar
/baz
The following example shows a way create a file in the /baz
directory:
remote_directory '/foo/bar/baz' do
owner 'root'
group 'root'
mode '0755'
action :create
end
But with this example, the group
, mode
, and owner
attribute values
will only be applied to /baz
. Which is fine, if that’s what you want.
But most of the time, when the entire /foo/bar/baz
directory structure
is not there, you must be explicit about each directory. For example:
%w( /foo /foo/bar /foo/bar/baz ).each do |path|
remote_directory path do
owner 'root'
group 'root'
mode '0755'
end
end
This approach will create the correct hierarchy—/foo
, then /bar
in
/foo
, and then /baz
in /bar
—and also with the correct attribute
values for group
, mode
, and owner
.
Example
This section contains a more detailed example of how Chef Infra Client manages recursive directory structures:
- A cookbook named
cumbria
that is used to build a website - A subfolder in the
/files/default
directory named/website
- A file named
index.html
, which is the root page for the website - Directories within
/website
named/cities
,/places
, and/football
, which contains pages about cities, places, and football teams - A directory named
/images
, which contains images
These files are placed in the /files/default
directory in the
cumbria
cookbook, like this:
cumbria
/files
/default
/website
index.html
/cities
carisle.html
kendal.html
penrith.html
windermere.html
/football
carisle_united.html
/images
carisle_united.png
furness_abbey.png
hadrians_wall.png
kendal.png
/places
furness_abbey.html
hadrians_wall.html
The remote_directory resource can be used to build a website using these files. This website is being run on an Apache web server. The resource would be similar to the following:
remote_directory '/var/www/html' do
files_mode '0440'
files_owner 'yan'
mode '0770'
owner 'hamilton'
source 'website'
end
When Chef Infra Client runs, the remote_directory resource will tell Chef Infra Client to copy the directory tree from the cookbook to the file system using the structure defined in cookbook:
/var
/www
/html
index.html
/cities
carisle.html
kendal.html
penrith.html
windermere.html
/football
carisle_united.html
/images
carisle_united.png
furness_abbey.png
hadrians_wall.png
kendal.png
/places
furness_abbey.html
hadrians_wall.html
Chef Infra Client will manage the permissions of the entire directory
structure below /html
, for a total of 12 files and 4 directories. For
example:
dr-xr-xr-x 2 root root 4096 /var/www/html
dr--r----- 1 yan root 4096 /var/www/html/index.html
drwxrwx--- 2 hamilton root 4096 /var/www/html/cities
dr--r----- 1 yan root 4096 /var/www/html/cities/carlisle.html
dr--r----- 1 yan root 4096 /var/www/html/cities/kendal.html
dr--r----- 1 yan root 4096 /var/www/html/cities/penrith.html
dr--r----- 1 yan root 4096 /var/www/html/cities/windermere.html
drwxrwx--- 2 hamilton root 4096 /var/www/html/football
dr--r----- 1 yan root 4096 /var/www/html/football/carlisle_united.html
drwxrwx--- 2 hamilton root 4096 /var/www/html/images
dr--r----- 1 yan root 4096 /var/www/html/images/carlisle_united/png
dr--r----- 1 yan root 4096 /var/www/html/images/furness_abbey/png
dr--r----- 1 yan root 4096 /var/www/html/images/hadrians_wall.png
dr--r----- 1 yan root 4096 /var/www/html/images/kendal.png
drwxrwx--- 2 hamilton root 4096 /var/www/html/places
dr--r----- 1 yan root 4096 /var/www/html/places/furness_abbey.html
dr--r----- 1 yan root 4096 /var/www/html/places/hadrians_wall.html
Windows File Security
To support Windows security, the template, file, remote_file, cookbook_file, directory, and remote_directory resources support the use of inheritance and access control lists (ACLs) within recipes. Access Control Lists (ACLs)The rights
property can be used in a recipe to manage access control
lists (ACLs), which allow permissions to be given to multiple users and
groups. Use the rights
property can be used as many times as
necessary; Chef Infra Client will apply them to the file or directory as
required. The syntax for the rights
property is as follows:
rights permission, principal, option_type => value
where
permission
Use to specify which rights are granted to the
principal
. The possible values are::read
,:write
,read_execute
,:modify
,:full_control
, or an integer.Integers used for permissions must match the following list FileSystemRights Enum fields.
These permissions are cumulative. If
:write
is specified, then it includes:read
. If:full_control
is specified, then it includes both:write
and:read
.(For those who know the Windows API:
:read
corresponds toGENERIC_READ
;:write
corresponds toGENERIC_WRITE
;:read_execute
corresponds toGENERIC_READ
andGENERIC_EXECUTE
;:modify
corresponds toGENERIC_WRITE
,GENERIC_READ
,GENERIC_EXECUTE
, andDELETE
;:full_control
corresponds toGENERIC_ALL
, which allows a user to change the owner and other metadata about a file.)principal
Use to specify a group or user. The principal can be specified by either name or SID. When using name, this is identical to what is entered in the login box for Windows, such as
user_name
,domain\user_name
, oruser_name@fully_qualified_domain_name
. When using a SID, you may use either the standard string representation of a SID (S-R-I-S-S) or one of the SDDL string constants. Chef Infra Client does not need to know if a principal is a user or a group.option_type
A hash that contains advanced rights options. For example, the rights to a directory that only applies to the first level of children might look something like:
rights :write, 'domain\group_name', :one_level_deep => true
.Possible option types:
:applies_to_children
Specify how permissions are applied to children. Possible values:
true
to inherit both child directories and files;false
to not inherit any child directories or files;:containers_only
to inherit only child directories (and not files);:objects_only
to recursively inherit files (and not child directories).:applies_to_self
Indicates whether a permission is applied to the parent directory. Possible values:
true
to apply to the parent directory or file and its children;false
to not apply only to child directories and files.:one_level_deep
Indicates the depth to which permissions will be applied. Possible values:
true
to apply only to the first level of children;false
to apply to all children.
For example:
resource 'x.txt' do
rights :read, 'S-1-1-0'
rights :write, 'domain\group'
rights :full_control, 'group_name_or_user_name'
rights :full_control, 'user_name', applies_to_children: true
end
or:
rights :read, %w(Administrators Everyone)
rights :full_control, 'Users', applies_to_children: true
rights :write, 'Sally', applies_to_children: :containers_only, applies_to_self: false, one_level_deep: true
Some other important things to know when using the rights
attribute:
- Only inherited rights remain. All existing explicit rights on the object are removed and replaced.
- If rights are not specified, nothing will be changed. Chef Infra Client does not clear out the rights on a file or directory if rights are not specified.
- Changing inherited rights can be expensive. Windows will propagate rights to all children recursively due to inheritance. This is a normal aspect of Windows, so consider the frequency with which this type of action is necessary and take steps to control this type of action if performance is the primary consideration.
Use the deny_rights
property to deny specific rights to specific
users. The ordering is independent of using the rights
property. For
example, it doesn’t matter if rights are granted to everyone is placed
before or after deny_rights :read, ['Julian', 'Lewis']
, both Julian
and Lewis will be unable to read the document. For example:
resource 'x.txt' do
rights :read, 'Everyone'
rights :write, 'domain\group'
rights :full_control, 'group_name_or_user_name'
rights :full_control, 'user_name', applies_to_children: true
deny_rights :read, %w(Julian Lewis)
end
or:
deny_rights :full_control, ['Sally']
By default, a file or directory inherits rights from its parent
directory. Most of the time this is the preferred behavior, but
sometimes it may be necessary to take steps to more specifically control
rights. The inherits
property can be used to specifically tell Chef
Infra Client to apply (or not apply) inherited rights from its parent
directory.
For example, the following example specifies the rights for a directory:
directory 'C:\mordor' do
rights :read, 'MORDOR\Minions'
rights :full_control, 'MORDOR\Sauron'
end
and then the following example specifies how to use inheritance to deny access to the child directory:
directory 'C:\mordor\mount_doom' do
rights :full_control, 'MORDOR\Sauron'
inherits false # Sauron is the only person who should have any sort of access
end
If the deny_rights
permission were to be used instead, something could
slip through unless all users and groups were denied.
Another example also shows how to specify rights for a directory:
directory 'C:\mordor' do
rights :read, 'MORDOR\Minions'
rights :full_control, 'MORDOR\Sauron'
rights :write, 'SHIRE\Frodo' # Who put that there I didn't put that there
end
but then not use the inherits
property to deny those rights on a child
directory:
directory 'C:\mordor\mount_doom' do
deny_rights :read, 'MORDOR\Minions' # Oops, not specific enough
end
Because the inherits
property is not specified, Chef Infra Client will
default it to true
, which will ensure that security settings for
existing files remain unchanged.
Examples
The following examples demonstrate various approaches for using the remote_directory resource in recipes:
Recursively transfer a directory from a remote location
# create up to 10 backups of the files
# set the files owner different from the directory
remote_directory '/tmp/remote_something' do
source 'something'
files_backup 10
files_owner 'root'
files_group 'root'
files_mode '0644'
owner 'nobody'
group 'nobody'
mode '0755'
end
Use with the chef_handler resource
The following example shows how to use the remote_directory
resource and the chef_handler resource to reboot a handler named
WindowsRebootHandler
:
# the following code sample comes from the
# ``reboot_handler`` recipe in the ``windows`` cookbook:
# https://github.com/chef-cookbooks/windows
remote_directory node['chef_handler']['handler_path'] do
source 'handlers'
recursive true
action :create
end
chef_handler 'WindowsRebootHandler' do
source "#{node['chef_handler']['handler_path']}/windows_reboot_handler.rb"
arguments node['windows']['allow_pending_reboots']
supports :report => true, :exception => false
action :enable
end
remote_file resource
remote_file resource pageUse the remote_file resource to transfer a file from a remote location using file specificity. This resource is similar to the file resource.
Note
Fetching files from the files/
directory in a cookbook should be done with the cookbook_file resource.
Syntax
A remote_file resource block manages files by using files that exist remotely. For example, to write the home page for an Apache website:
remote_file '/var/www/customers/public_html/index.html' do
source 'http://somesite.com/index.html'
owner 'web_admin'
group 'web_admin'
mode '0755'
action :create
end
where:
'/var/www/customers/public_html/index.html'
is path to the file to be created'http://somesite.com/index.html'
specifies the location of the remote file, the file is downloaded from thereowner
,group
, andmode
define the permissions
The full syntax for all of the properties that are available to the remote_file resource is:
remote_file 'name' do
atomic_update true, false
authentication Symbol # default value: :remote
backup Integer, false # default value: 5
checksum String
content String
deny_rights
force_unlink true, false # default value: false
ftp_active_mode true, false # default value: false
headers Hash # default value: {}
http_options Hash # default value: {}
manage_symlink_source true, false
path String # default value: 'name' unless specified
remote_domain String
remote_password String
remote_user String
rights
show_progress true, false # default value: false
ssl_verify_mode Symbol
use_conditional_get true, false # default value: true
use_etag true, false # default value: true
use_last_modified true, false # default value: true
action Symbol # defaults to :create if not specified
end
where:
remote_file
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.atomic_update
,authentication
,backup
,checksum
,content
,deny_rights
,force_unlink
,ftp_active_mode
,headers
,http_options
,manage_symlink_source
,path
,remote_domain
,remote_password
,remote_user
,rights
,show_progress
,ssl_verify_mode
,use_conditional_get
,use_etag
, anduse_last_modified
are the properties available to this resource.
Actions
The remote_file resource has the following actions:
:create
- (default) Create a file. If a file already exists (but does not match), update that file to match.
:create_if_missing
- Create a file only if the file does not exist. When the file exists, nothing happens.
:delete
- Delete a file.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:touch
- Touch a file. This updates the access (atime) and file modification (mtime) times for a file. (This action may be used with this resource, but is typically only used with the file resource.)
Properties
The remote_file resource has the following properties:
atomic_update
- Ruby Type: true, false | Default Value:
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.
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 theclient.rb
file.
authentication
- Ruby Type: Symbol | Default Value:
:remote
Allowed Values::local, :remote
backup
- Ruby Type: Integer, false | Default Value:
5
The number of backups to be kept in
/var/chef/backup
(for UNIX- and Linux-based platforms) orC:/chef/backup
(for the Microsoft Windows platform). Set tofalse
to prevent backups from being kept.
checksum
- Ruby Type: String
Optional, see
use_conditional_get
. The SHA-256 checksum of the file. Use to prevent a file from being re-downloaded. When the local file matches the checksum, Chef Infra Client does not download it.
content
- Ruby Type: String
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.
force_unlink
- Ruby Type: true, false | Default Value:
false
How Chef Infra 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 Chef Infra Client to delete the non-file target and replace it with the specified file. Set tofalse
for Chef Infra Client to raise an error.
ftp_active_mode
- Ruby Type: true, false | Default Value:
false
Whether Chef Infra Client uses active or passive FTP. Set to
true
to use active FTP.
group
- Ruby Type: Integer, String
A string or ID that identifies the group owner by group name or SID, including fully qualified group names such as
domain\group
orgroup@domain
. If this value is not specified, existing groups remain unchanged and new group assignments use the defaultPOSIX
group (if available).
headers
- Ruby Type: Hash | Default Value:
{}
A Hash of custom headers. For example:
headers({ "Cookie" => "user=some_user; pass=p@ssw0rd!" })
or:
headers({ "Referer" => "#{header}" })
or:
headers( "Authorization"=>"Basic #{ Base64.encode64("#{username}:#{password}").gsub("\n", "") }" )
http_options
- Ruby Type: Hash | Default Value:
{}
A Hash of custom HTTP options. For example:
http_options({ http_retry_count: 0, http_retry_delay: 2 })
New in Chef Infra Client 17.5
manage_symlink_source
- Ruby Type: true, false | Default Value:
true
Change the behavior of the file resource if it is pointed at a symlink. When this value is set to true, Chef Infra 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 Infra Client 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.
mode
- Ruby Type: Integer, String
A quoted 3-5 character string that defines the octal mode. For example:
'755'
,'0755'
, or00755
. Ifmode
is not specified and if the file already exists, the existing mode on the file is used. Ifmode
is not specified, the file does not exist, and the:create
action is specified, Chef Infra Client assumes a mask value of'0777'
and then applies the umask for the system on which the file is to be created to themask
value. For example, if the umask on a system is'022'
, Chef Infra Client uses the default value of'0755'
. The behavior is different depending on the platform. UNIX- and Linux-based systems: A quoted 3-5 character string that defines the octal mode that is passed to chmod. For example:'755'
,'0755'
, or00755
. If the value is specified as a quoted string, it works exactly as if thechmod
command was passed. If the value is specified as an integer, prepend a zero (0
) to the value to ensure that it is interpreted as an octal number. For example, to assign read, write, and execute rights for all users, use'0777'
or'777'
; for the same rights, plus the sticky bit, use01777
or'1777'
. Microsoft Windows: A quoted 3-5 character string that defines the octal mode that is translated into rights for Microsoft Windows security. For example:'755'
,'0755'
, or00755
. Values up to'0777'
are allowed (no sticky bits) and mean the same in Microsoft Windows as they do in UNIX, where4
equalsGENERIC_READ
,2
equalsGENERIC_WRITE
, and1
equalsGENERIC_EXECUTE
. This property cannot be used to set:full_control
. This property has no effect if not specified, but when it andrights
are both specified, the effects are cumulative.
owner
- Ruby Type: Integer, String
A string or ID that identifies the group owner by user name or SID, including fully qualified user names such as
domain\user
oruser@domain
. If this value is not specified, existing owners remain unchanged and new owner assignments use the current user (when necessary).
path
- Ruby Type: String | Default Value:
The resource block's name
The full path to the file, including the file name and its extension. Default value: the
name
of the resource block. See “Syntax” section above for more information.
remote_domain
- Ruby Type: String
Windows only The domain of the user specified by the
remote_user
property. By default the resource will authenticate against the domain of the remote system, or as a local account if the remote system is not joined to a domain. If the remote system is not part of a domain, it is necessary to authenticate as a local user on the remote system by setting the domain to.
, for example: remote_domain ‘.’. The domain may also be specified as part of theremote_user
property.New in Chef Client 13.4
remote_password
- Ruby Type: String
Windows only The password of the user specified by the
remote_user
property. This property is required ifremote_user
is specified and may only be specified ifremote_user
is specified. Thesensitive
property for this resource will automatically be set totrue
ifremote_password
is specified.New in Chef Client 13.4
remote_user
- Ruby Type: String
Windows only The name of a user with access to the remote file specified by the source property. The user name may optionally be specified with a domain, such as:
domain\user
oruser@my.dns.domain.com
via Universal Principal Name (UPN) format. The domain may also be set using theremote_domain
property. Note that this property is ignored if source is not a UNC path. If this property is specified, theremote_password
property is required.New in Chef Client 13.4
rights
- Ruby Type: Integer, String
Microsoft Windows only. The permissions for users and groups in a Microsoft Windows environment. For example:
rights <permissions>, <principal>, <options>
where<permissions>
specifies the rights granted to the principal,<principal>
is the group or user name, and<options>
is a Hash with one (or more) advanced rights options.
source
- Ruby Type: String, Array
Required. The location of the source file. The location of the source file may be HTTP (
http://
), FTP (ftp://
), SFTP (sftp://
), local (file:///
), or UNC (\\host\share\file.tar.gz
). There are many ways to define the location of a source file. By using a path:ruby source 'http://couchdb.apache.org/img/sketch.png'
By using FTP:ruby source 'ftp://remote_host/path/to/img/sketch.png'
By using SFTP:ruby source 'sftp://username:password@remote_host:22/path/to/img/sketch.png'
By using a local path:ruby source 'file:///path/to/img/sketch.png'
By using a Microsoft Windows UNC:ruby source '\\\\path\\to\\img\\sketch.png'
By using a node attribute:ruby source node['nginx']['foo123']['url']
By using attributes to define paths:ruby source "#{node['python']['url']}/#{version}/Python-#{version}.tar.bz2"
By defining multiple paths for multiple locations:ruby source 'http://seapower/spring.png', 'http://seapower/has_sprung.png'
By defining those same multiple paths as an array:ruby source ['http://seapower/spring.png', 'http://seapower/has_sprung.png']
When multiple paths are specified, Chef Infra Client will attempt to download the files in the order listed, stopping after the first successful download.
show_progress
- Ruby Type: true, false | Default Value:
false
Displays the progress of the file download.
ssl_verify_mode
- Ruby Type: SymbolAllowed Values:
:verify_none, :verify_peer
Optional property to override SSL policy. If not specified, uses the SSL policy from
config.rb
.New in Chef Infra Client 16.2
use_conditional_get
- Ruby Type: true, false | Default Value:
true
Enable conditional HTTP requests by using a conditional
GET
(with the If-Modified-Since header) or an opaque identifier (ETag). To use If-Modified-Since headers,use_last_modified
must also be set totrue
. To use ETag headers,use_etag
must also be set totrue
.
use_etag
- Ruby Type: true, false | Default Value:
true
Enable ETag headers. Set to
false
to disable ETag headers. To use this setting,use_conditional_get
must also be set to true.
use_last_modified
- Ruby Type: true, false | Default Value:
true
Enable
If-Modified-Since
headers. Set tofalse
to disableIf-Modified-Since
headers. To use this setting,use_conditional_get
must also be set totrue
.
verify
- Ruby Type: String, Block
A block or a string that returns
true
orfalse
. A string, whentrue
is executed as a system command.A block is arbitrary Ruby defined within the resource block by using the
verify
property. When a block istrue
, Chef Infra Client will continue to update the file as appropriate.For example, this should return
true
:remote_file '/tmp/baz' do verify { 1 == 1 } end
This should return
true
:remote_file '/etc/nginx.conf' do verify 'nginx -t -c %{path}' end
This should return
true
:remote_file '/tmp/bar' do verify { 1 == 1} end
And this should return
true
:remote_file '/tmp/foo' do verify do |path| true end end
Whereas, this should return
false
:remote_file '/tmp/turtle' do verify '/usr/bin/false' end
If a string or a block return
false
, the Chef Infra Client run will stop and an error is returned.
Atomic File Updates
Atomic updates are used with file-based resources to help ensure that file updates can be made when updating a binary or if disk space runs out.
Atomic updates are enabled by default. They can be managed globally
using the file_atomic_update
setting in the client.rb
file. They can
be managed for each resource using the atomic_update
property
that is available with the cookbook_file, file,
remote_file, and template resources.
Note
On certain platforms, and after a file has been moved into place, Chef
Infra Client may modify file permissions to support features specific to
those platforms. On platforms with SELinux enabled, Chef Infra Client
will fix up the security contexts after a file has been moved into the
correct location by running the restorecon
command. On the Microsoft
Windows platform, Chef Infra Client will create files so that ACL
inheritance works as expected.
Windows File Security
To support Windows security, the template, file, remote_file, cookbook_file, directory, and remote_directory resources support the use of inheritance and access control lists (ACLs) within recipes. Access Control Lists (ACLs)The rights
property can be used in a recipe to manage access control
lists (ACLs), which allow permissions to be given to multiple users and
groups. Use the rights
property can be used as many times as
necessary; Chef Infra Client will apply them to the file or directory as
required. The syntax for the rights
property is as follows:
rights permission, principal, option_type => value
where
permission
Use to specify which rights are granted to the
principal
. The possible values are::read
,:write
,read_execute
,:modify
,:full_control
, or an integer.Integers used for permissions must match the following list FileSystemRights Enum fields.
These permissions are cumulative. If
:write
is specified, then it includes:read
. If:full_control
is specified, then it includes both:write
and:read
.(For those who know the Windows API:
:read
corresponds toGENERIC_READ
;:write
corresponds toGENERIC_WRITE
;:read_execute
corresponds toGENERIC_READ
andGENERIC_EXECUTE
;:modify
corresponds toGENERIC_WRITE
,GENERIC_READ
,GENERIC_EXECUTE
, andDELETE
;:full_control
corresponds toGENERIC_ALL
, which allows a user to change the owner and other metadata about a file.)principal
Use to specify a group or user. The principal can be specified by either name or SID. When using name, this is identical to what is entered in the login box for Windows, such as
user_name
,domain\user_name
, oruser_name@fully_qualified_domain_name
. When using a SID, you may use either the standard string representation of a SID (S-R-I-S-S) or one of the SDDL string constants. Chef Infra Client does not need to know if a principal is a user or a group.option_type
A hash that contains advanced rights options. For example, the rights to a directory that only applies to the first level of children might look something like:
rights :write, 'domain\group_name', :one_level_deep => true
.Possible option types:
:applies_to_children
Specify how permissions are applied to children. Possible values:
true
to inherit both child directories and files;false
to not inherit any child directories or files;:containers_only
to inherit only child directories (and not files);:objects_only
to recursively inherit files (and not child directories).:applies_to_self
Indicates whether a permission is applied to the parent directory. Possible values:
true
to apply to the parent directory or file and its children;false
to not apply only to child directories and files.:one_level_deep
Indicates the depth to which permissions will be applied. Possible values:
true
to apply only to the first level of children;false
to apply to all children.
For example:
resource 'x.txt' do
rights :read, 'S-1-1-0'
rights :write, 'domain\group'
rights :full_control, 'group_name_or_user_name'
rights :full_control, 'user_name', applies_to_children: true
end
or:
rights :read, %w(Administrators Everyone)
rights :full_control, 'Users', applies_to_children: true
rights :write, 'Sally', applies_to_children: :containers_only, applies_to_self: false, one_level_deep: true
Some other important things to know when using the rights
attribute:
- Only inherited rights remain. All existing explicit rights on the object are removed and replaced.
- If rights are not specified, nothing will be changed. Chef Infra Client does not clear out the rights on a file or directory if rights are not specified.
- Changing inherited rights can be expensive. Windows will propagate rights to all children recursively due to inheritance. This is a normal aspect of Windows, so consider the frequency with which this type of action is necessary and take steps to control this type of action if performance is the primary consideration.
Use the deny_rights
property to deny specific rights to specific
users. The ordering is independent of using the rights
property. For
example, it doesn’t matter if rights are granted to everyone is placed
before or after deny_rights :read, ['Julian', 'Lewis']
, both Julian
and Lewis will be unable to read the document. For example:
resource 'x.txt' do
rights :read, 'Everyone'
rights :write, 'domain\group'
rights :full_control, 'group_name_or_user_name'
rights :full_control, 'user_name', applies_to_children: true
deny_rights :read, %w(Julian Lewis)
end
or:
deny_rights :full_control, ['Sally']
By default, a file or directory inherits rights from its parent
directory. Most of the time this is the preferred behavior, but
sometimes it may be necessary to take steps to more specifically control
rights. The inherits
property can be used to specifically tell Chef
Infra Client to apply (or not apply) inherited rights from its parent
directory.
For example, the following example specifies the rights for a directory:
directory 'C:\mordor' do
rights :read, 'MORDOR\Minions'
rights :full_control, 'MORDOR\Sauron'
end
and then the following example specifies how to use inheritance to deny access to the child directory:
directory 'C:\mordor\mount_doom' do
rights :full_control, 'MORDOR\Sauron'
inherits false # Sauron is the only person who should have any sort of access
end
If the deny_rights
permission were to be used instead, something could
slip through unless all users and groups were denied.
Another example also shows how to specify rights for a directory:
directory 'C:\mordor' do
rights :read, 'MORDOR\Minions'
rights :full_control, 'MORDOR\Sauron'
rights :write, 'SHIRE\Frodo' # Who put that there I didn't put that there
end
but then not use the inherits
property to deny those rights on a child
directory:
directory 'C:\mordor\mount_doom' do
deny_rights :read, 'MORDOR\Minions' # Oops, not specific enough
end
Because the inherits
property is not specified, Chef Infra Client will
default it to true
, which will ensure that security settings for
existing files remain unchanged.
Prevent Re-downloads
To prevent Chef Infra Client from re-downloading files that are already
present on a node, use one of the following attributes in a recipe:
use_conditional_get
(default) or checksum
.
- The
use_conditional_get
attribute is the default behavior of Chef Infra Client. If the remote file is located on a server that supports ETag and/or If-Modified-Since headers, Chef Infra Client will use a conditionalGET
to determine if the file has been updated. If the file has been updated, Chef Infra Client will re-download the file. - The
checksum
attribute will ask Chef Infra Client to compare the checksum for the local file to the one at the remote location. If they match, Chef Infra Client will not re-download the file. Using a local checksum for comparison requires that the local checksum be the correct checksum.
The desired approach just depends on the desired workflow. For example,
if a node requires a new file every day, using the checksum approach
would require that the local checksum be updated and/or verified every
day as well, to ensure that the local checksum was the correct
one. Using a conditional GET
in this scenario will greatly simplify
the management required to ensure files are being updated accurately.
Access a remote UNC path on Windows
The remote_file
resource on Windows supports accessing files from a
remote SMB/CIFS share. The file name should be specified in the source
property as a UNC path e.g. \myserver\myshare\mydirectory\myfile.txt
.
This allows access to the file at that path location even if the Chef
Infra Client process identity does not have permission to access the
file. Credentials for authenticating to the remote system can be
specified using the remote_user
, remote_domain
, and
remote_password
properties when the user that Chef Infra Client is
running does not have access to the remote file. See the “Properties”
section for more details on these options.
Note: This is primarily for accessing remote files when the user
that Chef Infra Client is running as does not have sufficient access,
and alternative credentials need to be specified. If the user already
has access, the credentials do not need to be specified. In a case where
the local system and remote system are in the same domain, the
remote_user
and remote_password
properties often do not need to be
specified, as the user may already have access to the remote file share.
Examples:
Access a file from a different domain account:
remote_file 'E:/domain_test.txt' do
source '\\myserver\myshare\mydirectory\myfile.txt'
remote_domain 'domain'
remote_user 'username'
remote_password 'password'
end
OR
remote_file 'E:/domain_test.txt' do
source '\\myserver\myshare\mydirectory\myfile.txt'
remote_user 'domain\username'
remote_password 'password'
end
Access a file using a local account on the remote machine:
remote_file 'E:/domain_test.txt' do
source '\\myserver\myshare\mydirectory\myfile.txt'
remote_domain '.'
remote_user 'username'
remote_password 'password'
end
OR
remote_file 'E:/domain_test.txt' do
source '\\myserver\myshare\mydirectory\myfile.txt'
remote_user '.\username'
remote_password 'password'
end
Examples
The following examples demonstrate various approaches for using the remote_file resource in recipes:
Download a file without checking the checksum:
remote_file '/tmp/remote.txt' do
source 'https://example.org/remote.txt'
end
Download a file with a checksum to validate:
remote_file '/tmp/test_file' do
source 'http://www.example.com/tempfiles/test_file'
mode '0755'
checksum '3a7dac00b1' # A SHA256 (or portion thereof) of the file.
end
Download a file only if it’s not already present:
remote_file '/tmp/remote.txt' do
source 'https://example.org/remote.txt'
checksum '3a7dac00b1' # A SHA256 (or portion thereof) of the file.
action :create_if_missing
end
Using HTTP Basic Authentication in Headers:
remote_file '/tmp/remote.txt' do
source 'https://example.org/remote.txt'
headers('Authorization' => "Basic #{Base64.encode64("USERNAME_VALUE:PASSWORD_VALUE").delete("\n")}")
checksum '3a7dac00b1' # A SHA256 (or portion thereof) of the file.
action :create_if_missing
end
Downloading a file to the Chef file cache dir for execution:
remote_file '#{Chef::Config['file_cache_path']}/install.sh' do
source 'https://example.org/install.sh'
action :create_if_missing
end
execute '#{Chef::Config['file_cache_path']}/install.sh'
Specify advanced HTTP connection options including Net::HTTP (nethttp) options:
remote_file '/tmp/remote.txt' do
source 'https://example.org/remote.txt'
http_options({
http_retry_delay: 0,
http_retry_count: 0,
keepalives: false,
nethttp: {
continue_timeout: 5,
max_retries: 5,
read_timeout: 5,
write_timeout: 5,
ssl_timeout: 5,
},
})
end
rhsm_errata resource
rhsm_errata resource pageUse the rhsm_errata resource to install packages associated with a given Red Hat Subscription Manager Errata ID. This is helpful if packages to mitigate a single vulnerability must be installed on your hosts.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the rhsm_errata resource is:
rhsm_errata 'name' do
errata_id String # default value: 'name' unless specified
action Symbol # defaults to :install if not specified
end
where:
rhsm_errata
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.errata_id
is the property available to this resource.
Actions
The rhsm_errata resource has the following actions:
:install
- Install a package for a specific errata ID. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The rhsm_errata resource has the following properties:
errata_id
- Ruby Type: String | Default Value:
The resource block's name
An optional property for specifying the errata ID if it differs from the resource block’s name.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the rhsm_errata resource in recipes:
Install a package from an Errata ID
rhsm_errata 'RHSA:2018-1234'
Specify an Errata ID that differs from the resource name
rhsm_errata 'errata-install'
errata_id 'RHSA:2018-1234'
end
rhsm_errata_level resource
rhsm_errata_level resource pageUse the rhsm_errata_level resource to install all packages of a specified errata level from the Red Hat Subscription Manager. For example, you can ensure that all packages associated with errata marked at a ‘Critical’ security level are installed.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the rhsm_errata_level resource is:
rhsm_errata_level 'name' do
errata_level String # default value: 'name' unless specified
action Symbol # defaults to :install if not specified
end
where:
rhsm_errata_level
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.errata_level
is the property available to this resource.
Actions
The rhsm_errata_level resource has the following actions:
:install
- Install all packages of the specified errata level. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The rhsm_errata_level resource has the following properties:
errata_level
- Ruby Type: String | Default Value:
The resource block's name
Allowed Values:"critical", "important", "low", "moderate"
An optional property for specifying the errata level of packages to install if it differs from the resource block’s name.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the rhsm_errata_level resource in recipes:
Specify an errata level that differs from the resource name
rhsm_errata_level 'example_install_moderate' do
errata_level 'moderate'
end
rhsm_register resource
rhsm_register resource pageUse the rhsm_register resource to register a node with the Red Hat Subscription Manager or a local Red Hat Satellite server.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the rhsm_register resource is:
rhsm_register 'name' do
activation_key String, Array
auto_attach true, false # default value: false
base_url String
environment String
force true, false # default value: false
https_for_ca_consumer true, false # default value: false
install_katello_agent true, false # default value: true
organization String
password String
release Float, String
satellite_host String
server_url String
service_level String
system_name String
username String
action Symbol # defaults to :register if not specified
end
where:
rhsm_register
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.activation_key
,auto_attach
,base_url
,environment
,force
,https_for_ca_consumer
,install_katello_agent
,organization
,password
,release
,satellite_host
,server_url
,service_level
,system_name
, andusername
are the properties available to this resource.
Actions
The rhsm_register resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:register
- Register the node with RHSM. (default)
:unregister
- Unregister the node from RHSM.
Properties
The rhsm_register resource has the following properties:
activation_key
- Ruby Type: String, Array
A string or array of activation keys to use when registering; you must also specify the ‘organization’ property when using this property.
auto_attach
- Ruby Type: true, false | Default Value:
false
If true, RHSM will attempt to automatically attach the host to applicable subscriptions. It is generally better to use an activation key with the subscriptions pre-defined.
base_url
- Ruby Type: String
The hostname of the content delivery server to use to receive updates. Both Customer Portal Subscription Management and Subscription Asset Manager use Red Hat’s hosted content delivery services, with the URL https://cdn.redhat.com. Since Satellite 6 hosts its own content, the URL must be used for systems registered with Satellite 6.
New in Chef Infra Client 17.8
environment
- Ruby Type: String
The environment to use when registering; required when using the username and password properties.
force
- Ruby Type: true, false | Default Value:
false
If true, the system will be registered even if it is already registered. Normally, any register operations will fail if the machine has already been registered.
https_for_ca_consumer
- Ruby Type: true, false | Default Value:
false
If true, Chef Infra Client will fetch the katello-ca-consumer-latest.noarch.rpm from the satellite_host using HTTPS.
New in Chef Infra Client 15.9
install_katello_agent
- Ruby Type: true, false | Default Value:
true
If true, the ‘katello-agent’ RPM will be installed.
organization
- Ruby Type: String
The organization to use when registering; required when using the ‘activation_key’ property.
password
- Ruby Type: String
The password to use when registering. This property is not applicable if using an activation key. If specified, username and environment are also required.
release
- Ruby Type: Float, String
Sets the operating system minor release to use for subscriptions for the system. Products and updates are limited to the specified minor release version. This is used with the
auto_attach
oractivation_key
options. For example,release '6.4'
will append--release=6.4
to the register command.New in Chef Infra Client 17.8
satellite_host
- Ruby Type: String
The FQDN of the Satellite host to register with. If this property is not specified, the host will register with Red Hat’s public RHSM service.
server_url
- Ruby Type: String
The hostname of the subscription service to use. The default is Customer Portal Subscription Management, subscription.rhn.redhat.com. If you do not use this option, the system registers with Customer Portal Subscription Management.
New in Chef Infra Client 17.8
service_level
- Ruby Type: String
Sets the service level to use for subscriptions on the registering machine. This is only used with the
auto_attach
option.New in Chef Infra Client 17.8
system_name
- Ruby Type: String
The name of the system to register, defaults to the hostname.
New in Chef Infra Client 16.5
username
- Ruby Type: String
The username to use when registering. This property is not applicable if using an activation key. If specified, password and environment properties are also required.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the rhsm_register resource in recipes:
Register a node with RHSM
rhsm_register 'my-host' do
activation_key 'ABCD1234'
organization 'my_org'
end
rhsm_repo resource
rhsm_repo resource pageUse the rhsm_repo resource to enable or disable Red Hat Subscription Manager repositories that are made available via attached subscriptions.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the rhsm_repo resource is:
rhsm_repo 'name' do
repo_name String # default value: 'name' unless specified
action Symbol # defaults to :enable if not specified
end
where:
rhsm_repo
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.repo_name
is the property available to this resource.
Actions
The rhsm_repo resource has the following actions:
:disable
- Disable a RHSM repository.
:enable
- Enable a RHSM repository. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The rhsm_repo resource has the following properties:
repo_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property for specifying the repository name if it differs from the resource block’s name.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the rhsm_repo resource in recipes:
Enable an RHSM repository
rhsm_repo 'rhel-7-server-extras-rpms'
Disable an RHSM repository
rhsm_repo 'rhel-7-server-extras-rpms' do
action :disable
end
rhsm_subscription resource
rhsm_subscription resource pageUse the rhsm_subscription resource to add or remove Red Hat Subscription Manager subscriptions from your host. This can be used when a host’s activation_key does not attach all necessary subscriptions to your host.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the rhsm_subscription resource is:
rhsm_subscription 'name' do
pool_id String # default value: 'name' unless specified
action Symbol # defaults to :attach if not specified
end
where:
rhsm_subscription
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.pool_id
is the property available to this resource.
Actions
The rhsm_subscription resource has the following actions:
:attach
- Attach the node to a subscription pool. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove the node from a subscription pool.
Properties
The rhsm_subscription resource has the following properties:
pool_id
- Ruby Type: String | Default Value:
The resource block's name
An optional property for specifying the Pool ID if it differs from the resource block’s name.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
This resource does not have any examples.
route resource
route resource pageUse the route resource to manage the system routing table in a Linux environment.
Syntax
A route resource block manages the system routing table in a Linux environment:
route '10.0.1.10/32' do
gateway '10.0.0.20'
device 'eth1'
end
The full syntax for all of the properties that are available to the route resource is:
route 'name' do
comment String
device String
gateway String
metric Integer
netmask String
route_type Symbol, String # default value: :host
target String # default value: 'name' unless specified
action Symbol # defaults to :add if not specified
end
where:
route
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.comment
,device
,gateway
,metric
,netmask
,route_type
, andtarget
are the properties available to this resource.
Actions
The route resource has the following actions:
:add
- (default) Add a route.
:delete
- Delete a route.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The route resource has the following properties:
comment
- Ruby Type: String
Add a comment for the route.
New in Chef Client 14.0
device
- Ruby Type: String
The network interface to which the route applies.
gateway
- Ruby Type: String
The gateway for the route.
metric
- Ruby Type: Integer
The route metric value.
netmask
- Ruby Type: String
The decimal representation of the network mask. For example:
255.255.255.0
.
route_type
- Ruby Type: Symbol, String | Default Value:
:host
Allowed Values::host, :net
target
- Ruby Type: String | Default Value:
The resource block's name
The IP address of the target route.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
This resource does not have any examples.
rpm_package resource
rpm_package resource pageUse the rpm_package resource to manage packages using the RPM Package Manager.
Syntax
The full syntax for all of the properties that are available to the rpm_package resource is:
rpm_package 'name' do
allow_downgrade true, false # default value: true
options String, Array
package_name String
source String
timeout String, Integer
version String
action Symbol # defaults to :install if not specified
end
where:
rpm_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.allow_downgrade
,options
,package_name
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The rpm_package resource has the following actions:
:install
- Install a package. If a version is specified, install the specified version of the package. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove a package.
:upgrade
- Install a package and ensure that a package is the latest version.
Properties
The rpm_package resource has the following properties:
allow_downgrade
- Ruby Type: true, false | Default Value:
true
Allow downgrading a package to satisfy requested version requirements.
options
- Ruby Type: String, Array
One (or more) additional command options that are passed to the command.
package_name
- Ruby Type: String
An optional property to set the package name if it differs from the resource block’s name.
source
- Ruby Type: String
The optional path to a package on the local file system.
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String
The version of a package to be installed or upgraded.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the rpm_package resource in recipes:
Install a package
rpm_package 'name of package' do
action :install
end
ruby resource
ruby resource pageUse the ruby resource to execute scripts using the Ruby interpreter. This resource may also use any of the actions and properties that are available to the execute resource. 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.
Syntax
A ruby resource block executes scripts using Ruby:
ruby 'hello world' do
code <<-EOH
puts "Hello world! From Chef and Ruby."
EOH
end
where:
cwd
specifies the directory from which the command is runcode
specifies the command to run
The full syntax for all of the properties that are available to the ruby resource is:
ruby 'name' do
code String
creates String
cwd String
environment Hash
flags String
group String, Integer
ignore_failure True, False
notifies Symbol
returns Integer, Array # default value: 0
subscribes Symbol
timeout Integer, String, Float # default value: 3600
user String, Integer
umask String, Integer
action Symbol # defaults to :run if not specified
end
where:
ruby
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.code
,creates
,cwd
,environment
,flags
,group
,ignore_failure
,notifies
,returns
,subscribes
timeout
,user
, andumask
are the properties available to this resource.
Actions
The ruby resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:run
- Run a command. (default)
Properties
The ruby resource has the following properties:
code
- Ruby Type: String |
REQUIRED
A quoted string of code to be executed.
creates
- Ruby Type: String
Prevent a command from creating a file when that file already exists.
cwd
- Ruby Type: String
The current working directory from which the command will be run.
environment
- Ruby Type: Hash
A Hash of environment variables in the form of
({'ENV_VARIABLE' => 'VALUE'})
. Note: These variables must exist for a command to be run successfully.
flags
- Ruby Type: String
One or more command line flags that are passed to the interpreter when a command is invoked.
group
- Ruby Type: String, Integer
The group name or group ID that must be changed before running a command.
ignore_failure
- Ruby Type: true, false | Default Value:
false
Continue running a recipe if a resource fails for any reason.
notifies
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
notifies
is:notifies :action, 'resource[name]', :timer
returns
- Ruby Type: Integer, Array | Default Value:
0
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.
subscribes
- Ruby Type: Symbol, Chef::Resource\[String\]
A resource may listen to another resource, and then take action if the state of the resource being listened to changes. Specify a
'resource[name]'
, the:action
to be taken, and then the:timer
for that action.Note that
subscribes
does not apply the specified action to the resource that it listens to - for example:file '/etc/nginx/ssl/example.crt' do mode '0600' owner 'root' end service 'nginx' do subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately end
In this case the
subscribes
property reloads thenginx
service whenever its certificate file, located under/etc/nginx/ssl/example.crt
, is updated.subscribes
does not make any changes to the certificate file itself, it merely listens for a change to the file, and executes the:reload
action for its resource (in this examplenginx
) when a change is detected.If the other resource does not exist, the subscription will not raise an error. Contrast this with the stricter semantics of
notifies
, which will raise an error if the other resource does not exist.A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for
subscribes
is:subscribes :action, 'resource[name]', :timer
timeout
- Ruby Type: Integer, String, Float | Default Value:
3600
The amount of time (in seconds) a command is to wait before timing out.
umask
- Ruby Type: String, Integer
The file mode creation mask, or umask.
user
- Ruby Type: String, Integer
The user name or user ID that should be changed before running a command.
Examples
This resource does not have any examples.
ruby_block resource
ruby_block resource pageUse the ruby_block resource to execute Ruby code during a Chef Infra Client run. Ruby code in the ruby_block
resource is evaluated with other resources during convergence, whereas Ruby code outside of a ruby_block
resource is evaluated before other resources, as the recipe is compiled.
Syntax
A ruby_block resource block executes a block of arbitrary Ruby code. For example, to reload the client.rb file during a Chef Infra Client run:
ruby_block 'reload_client_config' do
block do
Chef::Config.from_file("/etc/chef/client.rb")
end
action :run
end
The full syntax for all of the properties that are available to the ruby_block resource is:
ruby_block 'name' do
block Block
block_name String # default value: 'name' unless specified
action Symbol # defaults to :run if not specified
end
where:
ruby_block
is the resource.name
is the name given to the resource block.block
is the block of Ruby code to be executed.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.block
andblock_name
are properties of this resource, with the Ruby type shown. See “Properties” section below for more information about all of the properties that may be used with this resource.
Actions
The ruby_block resource has the following actions:
:create
- The same as
:run
. :nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:run
- Run a Ruby block. (default)
Properties
The ruby_block resource has the following properties:
block
- Ruby Type: block
A block of Ruby code.
block_name
- Ruby Type: String | Default Value:
The resource block's name
The name of the Ruby block. Default value: the
name
of the resource block. See “Syntax” section above for more information.
Examples
The following examples demonstrate various approaches for using the ruby_block resource in recipes:
Reload Chef Infra Client configuration data
ruby_block 'reload_client_config' do
block do
Chef::Config.from_file('/etc/chef/client.rb')
end
action :run
end
Run a block on a particular platform
The following example shows how an if statement can be used with the windows?
method in the Chef Infra Language to run code specific to Microsoft Windows. The code is defined using the ruby_block resource:
if windows?
ruby_block 'copy libmysql.dll into ruby path' do
block do
require 'fileutils'
FileUtils.cp "#{node['mysql']['client']['lib_dir']}\\libmysql.dll",
node['mysql']['client']['ruby_dir']
end
not_if { ::File.exist?("#{node['mysql']['client']['ruby_dir']}\\libmysql.dll") }
end
end
Stash a file in a data bag
The following example shows how to use the ruby_block resource to stash a BitTorrent file in a data bag so that it can be distributed to nodes in the organization.
ruby_block 'share the torrent file' do
block do
f = File.open(node['bittorrent']['torrent'],'rb')
#read the .torrent file and base64 encode it
enc = Base64.encode64(f.read)
data = {
'id'=>bittorrent_item_id(node['bittorrent']['file']),
'seed'=>node.ipaddress,
'torrent'=>enc
}
item = Chef::DataBagItem.new
item.data_bag('bittorrent')
item.raw_data = data
item.save
end
action :nothing
subscribes :create, "bittorrent_torrent[#{node['bittorrent']['torrent']}]", :immediately
end
Update the /etc/hosts file
The following example shows how the ruby_block resource can be used to update the /etc/hosts file:
ruby_block 'edit etc hosts' do
block do
rc = Chef::Util::FileEdit.new('/etc/hosts')
rc.search_file_replace_line(/^127\.0\.0\.1 localhost$/,
'127.0.0.1 #{new_fqdn} #{new_hostname} localhost')
rc.write_file
end
end
Set environment variables
The following example shows how to use variables within a Ruby block to set environment variables using rbenv.
node.override[:rbenv][:root] = rbenv_root
node.override[:ruby_build][:bin_path] = rbenv_binary_path
ruby_block 'initialize' do
block do
ENV['RBENV_ROOT'] = node[:rbenv][:root]
ENV['PATH'] = "#{node[:rbenv][:root]}/bin:#{node[:ruby_build][:bin_path]}:#{ENV['PATH']}"
end
end
Call methods in a gem
The following example shows how to call methods in gems not shipped in Chef Infra Client
chef_gem 'mongodb'
ruby_block 'config_replicaset' do
block do
MongoDB.configure_replicaset(node, replicaset_name, rs_nodes)
end
action :run
end
script resource
script resource pageUse the script resource to execute scripts using a specified interpreter, such as Bash, csh, Perl, Python, or Ruby. This resource may also use any of the actions and properties that are available to the execute resource. 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.
This resource is the base resource for several other resources used for scripting on specific platforms. For more information about specific resources for specific platforms, see the following topics: - bash - csh - ksh - perl - python - ruby Changed in 12.19 to support windows alternate user identity in execute resources
Syntax
A script resource block typically executes scripts using a specified interpreter, such as Bash, csh, Perl, Python, or Ruby:
script 'extract_module' do
interpreter "bash"
cwd ::File.dirname(src_filepath)
code <<-EOH
mkdir -p #{extract_path}
tar xzf #{src_filename} -C #{extract_path}
mv #{extract_path}/*/* #{extract_path}/
EOH
not_if { ::File.exist?(extract_path) }
end
where:
interpreter
specifies the command shell to usecwd
specifies the directory from which the command is runcode
specifies the command to run It is more common to use the script-based resource that is specific to the command shell. Chef has shell-specific resources for Bash, csh, ksh, Perl, Python, and Ruby. The same command as above, but run using the bash resource:bash 'extract_module' do cwd ::File.dirname(src_filepath) code <<-EOH mkdir -p #{extract_path} tar xzf #{src_filename} -C #{extract_path} mv #{extract_path}/*/* #{extract_path}/ EOH not_if { ::File.exist?(extract_path) } end
The full syntax for all of the properties that are available to the script resource is:
script 'name' do
code String
creates String
cwd String
domain String
environment Hash
flags String
group String, Integer
interpreter String
password String
returns Integer, Array # default value: 0
timeout Integer, String, Float # default value: 3600
umask String, Integer
user String, Integer
action Symbol # defaults to :run if not specified
end
where:
script
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.code
,creates
,cwd
,domain
,environment
,flags
,group
,interpreter
,password
,returns
,timeout
,umask
, anduser
are the properties available to this resource.
Actions
The script resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:run
- Run a command. (default)
Properties
The script resource has the following properties:
code
- Ruby Type: String |
REQUIRED
A quoted string of code to be executed.
creates
- Ruby Type: String
Prevent a command from creating a file when that file already exists.
cwd
- Ruby Type: String
The current working directory from which the command will be run.
domain
- Ruby Type: String
Windows only: The domain of the user user specified by the user property. Default value: nil. 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.
environment
- Ruby Type: Hash
A Hash of environment variables in the form of
({'ENV_VARIABLE' => 'VALUE'})
. Note: These variables must exist for a command to be run successfully.
flags
- Ruby Type: String
One or more command line flags that are passed to the interpreter when a command is invoked.
group
- Ruby Type: String, Integer
The group name or group ID that must be changed before running a command.
interpreter
- Ruby Type: String
The script interpreter to use during code execution.
password
- Ruby Type: String
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.
New in Chef Client 12.21
returns
- Ruby Type: Integer, Array | Default Value:
0
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.
timeout
- Ruby Type: Integer, String, Float | Default Value:
3600
The amount of time (in seconds) a command is to wait before timing out.
umask
- Ruby Type: String, Integer
The file mode creation mask, or umask.
user
- Ruby Type: String, Integer
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.
domain\user
oruser@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.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Guard Interpreter
Any resource that passes a string command may also specify the
interpreter that will be used to evaluate that string command. This is
done by using the guard_interpreter
property to specify a
script-based resource.
The guard_interpreter
property may be set to any of the following
values:
:bash
Evaluates a string command using the bash resource.
:batch
Evaluates a string command using the batch resource. Default value (within a batch resource block):
:batch
.:csh
Evaluates a string command using the csh resource.
:default
Default. Executes the default interpreter as identified by Chef Infra Client.
:perl
Evaluates a string command using the perl resource.
:powershell_script
Evaluates a string command using the powershell_script resource. Default value (within a powershell_script resource block):
:powershell_script
.:python
Evaluates a string command using the python resource.
:ruby
Evaluates a string command using the ruby resource.
The guard_interpreter
property is set to :default
by default for the
bash, csh, perl, python, and ruby resources. When
the guard_interpreter
property is set to :default
, not_if
or
only_if
guard statements do not inherit properties that are
defined by the script-based resource.
Warning
The batch and powershell_script resources inherit properties by
default. The guard_interpreter
property is set to :batch
or
:powershell_script
automatically when using a not_if
or only_if
guard statement within a batch or powershell_script resource,
respectively.
bash 'javatooling' do
environment 'JAVA_HOME' => '/usr/lib/java/jdk1.7/home'
code 'java-based-daemon-ctl.sh -start'
not_if 'java-based-daemon-ctl.sh -test-started'
end
and requires adding the environment
property to the not_if
guard
statement so that it may use the JAVA_HOME
path as part of its
evaluation:
bash 'javatooling' do
environment 'JAVA_HOME' => '/usr/lib/java/jdk1.7/home'
code 'java-based-daemon-ctl.sh -start'
not_if 'java-based-daemon-ctl.sh -test-started', :environment => 'JAVA_HOME' => '/usr/lib/java/jdk1.7/home'
end
To inherit properties, add the guard_interpreter
property to the
resource block and set it to the appropriate value:
:bash
for bash:csh
for csh:perl
for perl:python
for python:ruby
for ruby
For example, using the same example as from above, but this time adding
the guard_interpreter
property and setting it to :bash
:
bash 'javatooling' do
guard_interpreter :bash
environment 'JAVA_HOME' => '/usr/lib/java/jdk1.7/home'
code 'java-based-daemon-ctl.sh -start'
not_if 'java-based-daemon-ctl.sh -test-started'
end
The not_if
statement now inherits the environment
property and will
use the JAVA_HOME
path as part of its evaluation.
For example, the following code block will ensure the command is evaluated using the default interpreter as identified by Chef Infra Client:
resource 'name' do
guard_interpreter :default
# code
end
Examples
The following examples demonstrate various approaches for using the script resource in recipes:
Use a named provider to run a script
bash 'install_something' do
user 'root'
cwd '/tmp'
code <<-EOH
wget http://www.example.com/tarball.tar.gz
tar -zxf tarball.tar.gz
cd tarball
./configure
make
make install
EOH
end
Run a script
script 'install_something' do
interpreter 'bash'
user 'root'
cwd '/tmp'
code <<-EOH
wget http://www.example.com/tarball.tar.gz
tar -zxf tarball.tar.gz
cd tarball
./configure
make
make install
EOH
end
or something like:
bash 'openvpn-server-key' do
environment('KEY_CN' => 'server')
code <<-EOF
openssl req -batch -days #{node['openvpn']['key']['expire']} \
-nodes -new -newkey rsa:#{key_size} -keyout #{key_dir}/server.key \
-out #{key_dir}/server.csr -extensions server \
-config #{key_dir}/openssl.cnf
EOF
not_if { File.exist?('#{key_dir}/server.crt') }
end
where code
contains the OpenSSL command to be run. The not_if
property tells Chef Infra Client not to run the command if the file
already exists.
Install a file from a remote location using bash
The following is an example of how to install the foo123
module for
Nginx. This module adds shell-style functionality to an Nginx
configuration file and does the following:
- Declares three variables
- Gets the Nginx file from a remote location
- Installs the file using Bash to the path specified by the
src_filepath
variable
# the following code sample is similar to the ``upload_progress_module``
# recipe in the ``nginx`` cookbook:
# https://github.com/chef-cookbooks/nginx
src_filename = "foo123-nginx-module-v#{
node['nginx']['foo123']['version']
}.tar.gz"
src_filepath = "#{Chef::Config['file_cache_path']}/#{src_filename}"
extract_path = "#{
Chef::Config['file_cache_path']
}/nginx_foo123_module/#{
node['nginx']['foo123']['checksum']
}"
remote_file 'src_filepath' do
source node['nginx']['foo123']['url']
checksum node['nginx']['foo123']['checksum']
owner 'root'
group 'root'
mode '0755'
end
bash 'extract_module' do
cwd ::File.dirname(src_filepath)
code <<-EOH
mkdir -p #{extract_path}
tar xzf #{src_filename} -C #{extract_path}
mv #{extract_path}/*/* #{extract_path}/
EOH
not_if { ::File.exist?(extract_path) }
end
Install an application from git using bash
The following example shows how Bash can be used to install a plug-in
for rbenv named ruby-build
, which is located in git version source
control. First, the application is synchronized, and then Bash changes
its working directory to the location in which ruby-build
is located,
and then runs a command.
git "#{Chef::Config[:file_cache_path]}/ruby-build" do
repository 'git://github.com/sstephenson/ruby-build.git'
revision 'master'
action :sync
end
bash 'install_ruby_build' do
cwd "#{Chef::Config[:file_cache_path]}/ruby-build"
user 'rbenv'
group 'rbenv'
code <<-EOH
./install.sh
EOH
environment 'PREFIX' => '/usr/local'
end
To read more about ruby-build
, see here:
https://github.com/sstephenson/ruby-build.
Store certain settings
The following recipe shows how an attributes file can be used to store
certain settings. An attributes file is located in the attributes/
directory in the same cookbook as the recipe which calls the attributes
file. In this example, the attributes file specifies certain settings
for Python that are then used across all nodes against which this recipe
will run.
Python packages have versions, installation directories, URLs, and checksum files. An attributes file that exists to support this type of recipe would include settings like the following:
default['python']['version'] = '2.7.1'
if python['install_method'] == 'package'
default['python']['prefix_dir'] = '/usr'
else
default['python']['prefix_dir'] = '/usr/local'
end
default['python']['url'] = 'http://www.python.org/ftp/python'
default['python']['checksum'] = '80e387...85fd61'
and then the methods in the recipe may refer to these values. A recipe that is used to install Python will need to do the following:
- Identify each package to be installed (implied in this example, not shown)
- Define variables for the package
version
and theinstall_path
- Get the package from a remote location, but only if the package does not already exist on the target system
- Use the bash resource to install the package on the node, but only when the package is not already installed
# the following code sample comes from the ``oc-nginx`` cookbook on |github|: https://github.com/cookbooks/oc-nginx
version = node['python']['version']
install_path = "#{node['python']['prefix_dir']}/lib/python#{version.split(/(^\d+\.\d+)/)[1]}"
remote_file "#{Chef::Config[:file_cache_path]}/Python-#{version}.tar.bz2" do
source "#{node['python']['url']}/#{version}/Python-#{version}.tar.bz2"
checksum node['python']['checksum']
mode '0755'
not_if { ::File.exist?(install_path) }
end
bash 'build-and-install-python' do
cwd Chef::Config[:file_cache_path]
code <<-EOF
tar -jxvf Python-#{version}.tar.bz2
(cd Python-#{version} && ./configure #{configure_options})
(cd Python-#{version} && make && make install)
EOF
not_if { ::File.exist?(install_path) }
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:
# 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.
# Passing only username and password
script 'mkdir test_dir' do
interpreter "bash"
code "mkdir test_dir"
cwd Chef::Config[:file_cache_path]
user "username"
password "password"
end
# Passing username and domain
script 'mkdir test_dir' do
interpreter "bash"
code "mkdir test_dir"
cwd Chef::Config[:file_cache_path]
domain "domain-name"
user "username"
password "password"
end
# Passing username = 'domain-name\\username'. No domain is passed
script 'mkdir test_dir' do
interpreter "bash"
code "mkdir test_dir"
cwd Chef::Config[:file_cache_path]
user "domain-name\\username"
password "password"
end
# Passing username = 'username@domain-name'. No domain is passed
script 'mkdir test_dir' do
interpreter "bash"
code "mkdir test_dir"
cwd Chef::Config[:file_cache_path]
user "username@domain-name"
password "password"
end
selinux_boolean resource
selinux_boolean resource pageUse the selinux_boolean resource to set SELinux boolean values.
New in Chef Infra Client 18.0.
Syntax
The full syntax for all of the properties that are available to the selinux_boolean resource is:
selinux_boolean 'name' do
boolean String # default value: 'name' unless specified
persistent true, false # default value: true
value Integer, String, true, false
action Symbol # defaults to :set if not specified
end
where:
selinux_boolean
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.boolean
,persistent
, andvalue
are the properties available to this resource.
Actions
The selinux_boolean resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:set
- Set the state of the boolean. (default)
Properties
The selinux_boolean resource has the following properties:
boolean
- Ruby Type: String | Default Value:
The resource block's name.
SELinux boolean to set.
persistent
- Ruby Type: true, false | Default Value:
true
Set to
true
for value setting to survive reboot.
value
- Ruby Type: Integer, String, true, false |
REQUIRED
Allowed Values:"on", "off", true, false, 0, 1
SELinux boolean value.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the selinux_boolean resource in recipes:
Set ssh_keysign to true:
selinux_boolean 'ssh_keysign' do
value true
end
Set ssh_sysadm_login to ‘on’:
selinux_boolean 'ssh_sysadm_login' do
value 'on'
end
selinux_fcontext resource
selinux_fcontext resource pageUse the selinux_fcontext resource to set the SELinux context of files using the semanage fcontext
command.
New in Chef Infra Client 18.0.
Syntax
The full syntax for all of the properties that are available to the selinux_fcontext resource is:
selinux_fcontext 'name' do
file_spec String # default value: 'name' unless specified
file_type String # default value: "a"
secontext String
action Symbol # defaults to :manage if not specified
end
where:
selinux_fcontext
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.file_spec
,file_type
, andsecontext
are the properties available to this resource.
Actions
The selinux_fcontext resource has the following actions:
:add
- Assign the file context if not set.
:addormodify
- Assign the file context if not set. Update the file context if previously set.
:delete
- Removes the file context if set.
:manage
- Assign the file to the right context regardless of previous state. (default)
:modify
- Update the file context if previously set.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The selinux_fcontext resource has the following properties:
file_spec
- Ruby Type: String | Default Value:
The resource block's name.
Path to or regex matching the files or directories to label.
file_type
- Ruby Type: String | Default Value:
a
Allowed Values:"a", "b", "c", "d", "f", "l", "p", "s"
The type of the file being labeled.
secontext
- Ruby Type: String |
REQUIRED
SELinux context to assign.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the selinux_fcontext resource in recipes:
Allow http servers (e.g. nginx/apache) to modify Moodle files:
selinux_fcontext '/var/www/moodle(/.*)?' do
secontext 'httpd_sys_rw_content_t'
end
Adapt a symbolic link:
selinux_fcontext '/var/www/symlink_to_webroot' do
secontext 'httpd_sys_rw_content_t'
file_type 'l'
end
selinux_install resource
selinux_install resource pageUse the selinux_install resource to encapsulate the set of SELinux packages to install in order to manage SELinux. It also ensures the directory /etc/selinux
is created.
New in Chef Infra Client 18.0.
Syntax
The full syntax for all of the properties that are available to the selinux_install resource is:
selinux_install 'name' do
packages String, Array
action Symbol # defaults to :install if not specified
end
where:
selinux_install
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.packages
is the property available to this resource.
Actions
The selinux_install resource has the following actions:
:install
- Install required packages. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove any SELinux-related packages.
:upgrade
- Upgrade required packages.
Properties
The selinux_install resource has the following properties:
packages
- Ruby Type: String, Array | Default Value:
lazy default
SELinux packages for system.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the selinux_install resource in recipes:
Default installation:
selinux_install 'example'
Install with custom packages:
selinux_install 'example' do
packages %w(policycoreutils selinux-policy selinux-policy-targeted)
end
Uninstall
selinux_install 'example' do
action :remove
end
selinux_login resource
selinux_login resource pageUse the selinux_login resource to add, update, or remove SELinux user to OS login mappings.
New in Chef Infra Client 18.1.
Syntax
The full syntax for all of the properties that are available to the selinux_login resource is:
selinux_login 'name' do
login String # default value: 'name' unless specified
range String
user String
action Symbol # defaults to :manage if not specified
end
where:
selinux_login
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.login
,range
, anduser
are the properties available to this resource.
Actions
The selinux_login resource has the following actions:
:add
- Creates the SELinux login mapping if not previously created.
:delete
- Removes the SELinux login mapping if previously created.
:manage
- Sets the SELinux login mapping to the desired settings regardless of previous state. (default)
:modify
- Updates the SELinux login mapping if previously created.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The selinux_login resource has the following properties:
login
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the OS user login value if it differs from the resource block’s name.
range
- Ruby Type: String
Multi-Level Security (MLS) or Multi-Category Security (MCS) range for the SELinux user.
user
- Ruby Type: String
SELinux user to be mapped.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the selinux_login resource in recipes:
Manage test OS user mapping with a range of s0 and associated SELinux user test_u:
selinux_login 'test' do
user 'test_u'
range 's0'
end
selinux_module resource
selinux_module resource pageUse the selinux_module module resource to create an SELinux policy module from a cookbook file or content provided as a string.
New in Chef Infra Client 18.0.
Syntax
The full syntax for all of the properties that are available to the selinux_module resource is:
selinux_module 'name' do
base_dir String # default value: "/etc/selinux/local"
content String
cookbook String
module_name String # default value: 'name' unless specified
source String
action Symbol # defaults to :create if not specified
end
where:
selinux_module
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.base_dir
,content
,cookbook
,module_name
, andsource
are the properties available to this resource.
Actions
The selinux_module resource has the following actions:
:create
- Compile a module and install it. (default)
:delete
- Remove module source files from
/etc/selinux/local
. :install
- Install a compiled module into the system.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove a module from the system.
Properties
The selinux_module resource has the following properties:
base_dir
- Ruby Type: String | Default Value:
/etc/selinux/local
Directory to create module source file in.
content
- Ruby Type: String
Module source as String.
cookbook
- Ruby Type: String
Cookbook to source module source file from (if it is not located in the current cookbook). The default value is the current cookbook.
module_name
- Ruby Type: String | Default Value:
The resource block's name.
Override the module name.
source
- Ruby Type: String
Module source file name.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the selinux_module resource in recipes:
Create an SElinux module from a TE file located at files
directory of your cookbook:
selinux_module 'my_policy_module' do
source 'my_policy_module.te'
action :create
end
selinux_permissive resource
selinux_permissive resource pageUse the selinux_permissive resource to allow some domains to misbehave without stopping them. This is not as good as setting specific policies, but better than disabling SELinux entirely.
New in Chef Infra Client 18.0.
Syntax
The full syntax for all of the properties that are available to the selinux_permissive resource is:
selinux_permissive 'name' do
context String # default value: 'name' unless specified
action Symbol # defaults to :add if not specified
end
where:
selinux_permissive
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.context
is the property available to this resource.
Actions
The selinux_permissive resource has the following actions:
:add
- Make a domain permissive, unless already set. (default)
:delete
- Stop a domain from being permissive, if set.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The selinux_permissive resource has the following properties:
context
- Ruby Type: String | Default Value:
The resource block's name
The SELinux context to permit.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the selinux_permissive resource in recipes:
Disable enforcement on Apache:
selinux_permissive 'httpd_t' do
notifies :restart, 'service[httpd]'
end
selinux_port resource
selinux_port resource pageUse the selinux_port resource to assign a network port to a specific SELinux context. For example, running a web server on a non-standard port.
New in Chef Infra Client 18.0.
Syntax
The full syntax for all of the properties that are available to the selinux_port resource is:
selinux_port 'name' do
port Integer, String # default value: 'name' unless specified
protocol String
secontext String
action Symbol # defaults to :manage if not specified
end
where:
selinux_port
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.port
,protocol
, andsecontext
are the properties available to this resource.
Actions
The selinux_port resource has the following actions:
:add
- Assign the port context if not set.
:addormodify
- Assigns the port context if not set. Updates the port context if previously set.
:delete
- Removes the port context if set.
:manage
- Assign the port to the right context regardless of previous state. (default)
:modify
- Update the port context if previously set.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The selinux_port resource has the following properties:
port
- Ruby Type: Integer, String | Default Value:
The resource block's name.
Port to modify.
protocol
- Ruby Type: String |
REQUIRED
Allowed Values:"tcp", "udp"
Protocol to modify.
secontext
- Ruby Type: String |
REQUIRED
SELinux context to assign to the port.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the selinux_port resource in recipes:
Allow Nginx or Apache to bind to port 5678 by giving it the http_port_t
context:
selinux_port '5678' do
protocol 'tcp'
secontext 'http_port_t'
end
selinux_state resource
selinux_state resource pageUse the selinux_state resource to manage the SELinux state on a system. It does this by using the setenforce
command and rendering the /etc/selinux/config
file from a template.
New in Chef Infra Client 18.0.
Syntax
The full syntax for all of the properties that are available to the selinux_state resource is:
selinux_state 'name' do
automatic_reboot true, false, Symbol # default value: false
config_file String # default value: "/etc/selinux/config"
persistent true, false # default value: true
policy String
action Symbol # defaults to :enforcing if not specified
end
where:
selinux_state
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.automatic_reboot
,config_file
,persistent
, andpolicy
are the properties available to this resource.
Actions
The selinux_state resource has the following actions:
:disabled
- Set the SELinux state to disabled. NOTE: Switching to or from disabled requires a reboot!
:enforcing
- Set the SELinux state to enforcing. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:permissive
- Set the SELinux state to permissive.
Properties
The selinux_state resource has the following properties:
automatic_reboot
- Ruby Type: true, false, Symbol | Default Value:
false
Perform an automatic node reboot if required for state change.
config_file
- Ruby Type: String | Default Value:
/etc/selinux/config
Path to the SELinux config file on disk.
persistent
- Ruby Type: true, false | Default Value:
true
Set the status update in the SELinux configuration file.
policy
- Ruby Type: String | Default Value:
lazy default
Allowed Values:"default", "minimum", "mls", "src", "strict", "targeted"
SELinux policy type.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the selinux_state resource in recipes:
Set SELinux state to permissive:
selinux_state 'permissive' do
action :permissive
end
Set SELinux state to enforcing:
selinux_state 'enforcing' do
action :enforcing
end
Set SELinux state to disabled:
selinux_state 'disabled' do
action :disabled
end
selinux_user resource
selinux_user resource pageUse the selinux_user resource to add, update, or remove SELinux users.
New in Chef Infra Client 18.1.
Syntax
The full syntax for all of the properties that are available to the selinux_user resource is:
selinux_user 'name' do
level String
range String
roles Array
user String # default value: 'name' unless specified
action Symbol # defaults to :manage if not specified
end
where:
selinux_user
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.level
,range
,roles
, anduser
are the properties available to this resource.
Actions
The selinux_user resource has the following actions:
:add
- Creates the SELinux user if not previously created.
:delete
- Removes the SELinux user if previously created.
:manage
- Sets the SELinux user to the desired settings regardless of previous state. (default)
:modify
- Updates the SELinux user if previously created.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The selinux_user resource has the following properties:
level
- Ruby Type: String
Multi-Level Security (MLS) or Multi-Category Security (MCS) security level for the SELinux user.
range
- Ruby Type: String
Multi-Level Security (MLS) or Multi-Category Security (MCS) security range for the SELinux user.
roles
- Ruby Type: Array
Associated SELinux roles for the user.
user
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the SELinux user value if it differs from the resource block’s name.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the selinux_user resource in recipes:
Set an SELinux user with a level and range of s0
and roles sysadm_r
and staff_r
:
selinux_user 'username' do
level 's0'
range 's0'
roles %w(sysadm_r staff_r)
end
service resource
service resource pageUse the service resource to manage a service.
Syntax
The full syntax for all of the properties that are available to the service resource is:
service 'name' do
init_command String
options Array, String
parameters Hash
pattern String
priority Integer, String, Hash
reload_command String, false
restart_command String, false
run_levels Array
service_name String # default value: 'name' unless specified
start_command String, false
status_command String, false
stop_command String, false
supports Hash # default value: {"restart"=>nil, "reload"=>nil, "status"=>nil}
timeout Integer # default value: 900
user String
action Symbol # defaults to :nothing if not specified
end
where:
service
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.init_command
,options
,parameters
,pattern
,priority
,reload_command
,restart_command
,run_levels
,service_name
,start_command
,status_command
,stop_command
,supports
,timeout
, anduser
are the properties available to this resource.
Actions
The service resource has the following actions:
:disable
- Disable a service. This action is equivalent to a
Disabled
startup type on the Microsoft Windows platform. This action is not supported when using System Resource Controller (SRC) on the AIX platform because System Resource Controller (SRC) does not have a standard mechanism for enabling and disabling services on system boot. :enable
- Enable a service at boot. This action is equivalent to an
Automatic
startup type on the Microsoft Windows platform. This action is not supported when using System Resource Controller (SRC) on the AIX platform because System Resource Controller (SRC) does not have a standard mechanism for enabling and disabling services on system boot. :nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:start
- Start a service, and keep it running until stopped or disabled.
:stop
- Stop a service.
Properties
The service resource has the following properties:
init_command
- Ruby Type: String
The path to the init script that is associated with the service. Use
init_command
to prevent the need to specify overrides for thestart_command
,stop_command
, andrestart_command
properties. When this property is not specified, the Chef Infra Client will use the default init command for the service provider being used.
options
- Ruby Type: Array, String
Solaris platform only. Options to pass to the service command. See the svcadm manual for details of possible options.
parameters
- Ruby Type: Hash
Upstart only: A hash of parameters to pass to the service command for use in the service definition.
pattern
- Ruby Type: String | Default Value:
The value provided to 'service_name' or the resource block's name
The pattern to look for in the process table.
priority
- Ruby Type: Integer, String, Hash
Debian platform only. The relative priority of the program for start and shutdown ordering. May be an integer or a Hash. An integer is used to define the start run levels; stop run levels are then 100-integer. A Hash is used to define values for specific run levels. For example,
{ 2 => [:start, 20], 3 => [:stop, 55] }
will set a priority of twenty for run level two and a priority of fifty-five for run level three.
reload_command
- Ruby Type: String, false
The command used to tell a service to reload its configuration.
restart_command
- Ruby Type: String, false
The command used to restart a service.
run_levels
- Ruby Type: Array
RHEL platforms only: Specific run_levels the service will run under.
service_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the service name if it differs from the resource block’s name.
start_command
- Ruby Type: String, false
The command used to start a service.
status_command
- Ruby Type: String, false
The command used to check the run status for a service.
stop_command
- Ruby Type: String, false
The command used to stop a service.
supports
- Ruby Type: Hash | Default Value:
{"restart" => nil, "reload" => nil, "status" => nil}
A list of properties that controls how Chef Infra Client is to attempt to manage a service:
:restart
,:reload
,:status
. For:restart
, the init script or other service provider can use a restart command; if:restart
is not specified, the Chef Infra Client attempts to stop and then start a service. For :reload, the init script or other service provider can use a reload command. For:status
, the init script or other service provider can use a status command to determine if the service is running; if:status
is not specified, the Chef Infra Client attempts to match the service_name against the process table as a regular expression, unless a pattern is specified as a parameter property. Default value:{ restart: false, reload: false, status: false }
for all platforms (except for the Red Hat platform family, which defaults to{ restart: false, reload: false, status: true }
.)
timeout
- Ruby Type: Integer | Default Value:
900
The amount of time (in seconds) to wait before timing out.
user
- Ruby Type: String
systemd only: A username to run the service under.
New in Chef Client 12.21
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the service resource in recipes:
Start a service
service 'example_service' do
action :start
end
Start a service, enable it
service 'example_service' do
supports status: true, restart: true, reload: true
action [ :enable, :start ]
end
Use a pattern
service 'samba' do
pattern 'smbd'
action [:enable, :start]
end
Use the :nothing common action
service 'memcached' do
action :nothing
end
Use the retries common attribute
service 'apache' do
action [ :enable, :start ]
retries 3
end
Manage a service, depending on the node platform
service 'example_service' do
if redhat?
service_name 'redhat_name'
else
service_name 'other_name'
end
supports restart: true
action [ :enable, :start ]
end
Reload a service using a template
To reload a service that is based on a template, use the template and service resources together in the same recipe, similar to the following:
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
end
service 'apache' do
action :enable
subscribes :reload, 'template[/tmp/somefile]', :immediately
end
where the subscribes
notification is used to reload the service
whenever the template is modified.
Enable a service after a restart or reload
service 'apache' do
supports restart: true, reload: true
action :enable
end
Set an IP address using variables and a template
The following example shows how the template resource can be used in a recipe to combine settings stored in an attributes file, variables within a recipe, and a template to set the IP addresses that are used by the Nginx service. The attributes file contains the following:
default['nginx']['dir'] = '/etc/nginx'
The recipe then does the following to:
- Declare two variables at the beginning of the recipe, one for the remote IP address and the other for the authorized IP address
- Use the service resource to restart and reload the Nginx service
- Load a template named
authorized_ip.erb
from the/templates
directory that is used to set the IP address values based on the variables specified in the recipe
node.default['nginx']['remote_ip_var'] = 'remote_addr'
node.default['nginx']['authorized_ips'] = ['127.0.0.1/32']
service 'nginx' do
supports :status => true, :restart => true, :reload => true
end
template 'authorized_ip' do
path "#{node['nginx']['dir']}/authorized_ip"
source 'modules/authorized_ip.erb'
owner 'root'
group 'root'
mode '0755'
variables(
:remote_ip_var => node['nginx']['remote_ip_var'],
:authorized_ips => node['nginx']['authorized_ips']
)
notifies :reload, 'service[nginx]', :immediately
end
where the variables
property tells the template to use the variables
set at the beginning of the recipe and the source
property is used to
call a template file located in the cookbook’s /templates
directory.
The template file looks similar to:
geo $<%= @remote_ip_var %> $authorized_ip {
default no;
<% @authorized_ips.each do |ip| %>
<%= "#{ip} yes;" %>
<% end %>
}
Use a cron timer to manage a service
The following example shows how to install the crond application using two resources and a variable:
# the following code sample comes from the ``cron`` cookbook:
# https://github.com/chef-cookbooks/cron
cron_package = case node['platform']
when 'redhat', 'centos', 'scientific', 'fedora', 'amazon'
node['platform_version'].to_f >= 6.0 ? 'cronie' : 'vixie-cron'
else
'cron'
end
package cron_package do
action :install
end
service 'crond' do
case node['platform']
when 'redhat', 'centos', 'scientific', 'fedora', 'amazon'
service_name 'crond'
when 'debian', 'ubuntu', 'suse'
service_name 'cron'
end
action [:start, :enable]
end
where
cron_package
is a variable that is used to identify which platforms apply to which install packages- the package resource uses the
cron_package
variable to determine how to install the crond application on various nodes (with various platforms) - the service resource enables the crond application on nodes that have Red Hat, CentOS, Red Hat Enterprise Linux, Fedora, or Amazon Web Services (AWS), and the cron service on nodes that run Debian, Ubuntu, or openSUSE
Restart a service, and then notify a different service
The following example shows how start a service named example_service
and immediately notify the Nginx service to restart.
service 'example_service' do
action :start
notifies :restart, 'service[nginx]', :immediately
end
Restart one service before restarting another
This example uses the :before
notification to restart the php-fpm
service before restarting nginx
:
service 'nginx' do
action :restart
notifies :restart, 'service[php-fpm]', :before
end
With the :before
notification, the action specified for the nginx
resource will not run until action has been taken on the notified
resource (php-fpm
).
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
# 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 do FileTest.directory?(node['mysql']['ec2_path']) end
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
Control a service using the execute resource
Warning
This is an example of something that should NOT be done. Use the service resource to control a service, not the execute resource.
Do something like this:
service 'tomcat' do
action :start
end
and NOT something like this:
execute 'start-tomcat' do
command '/etc/init.d/tomcat6 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.
Enable a service on AIX using the mkitab command
The service resource does not support using the :enable
and
:disable
actions with resources that are managed using System Resource
Controller (SRC). This is because System Resource Controller (SRC) does
not have a standard mechanism for enabling and disabling services on
system boot.
One approach for enabling or disabling services that are managed by
System Resource Controller (SRC) is to use the execute resource to
invoke mkitab
, and then use that command to enable or disable the
service.
The following example shows how to install a service:
execute "install #{node['chef_client']['svc_name']} in SRC" do
command "mkssys -s #{node['chef_client']['svc_name']}
-p #{node['chef_client']['bin']}
-u root
-S
-n 15
-f 9
-o #{node['chef_client']['log_dir']}/client.log
-e #{node['chef_client']['log_dir']}/client.log -a '
-i #{node['chef_client']['interval']}
-s #{node['chef_client']['splay']}'"
not_if "lssrc -s #{node['chef_client']['svc_name']}"
action :run
end
and then enable it using the mkitab
command:
execute "enable #{node['chef_client']['svc_name']}" do
command "mkitab '#{node['chef_client']['svc_name']}:2:once:/usr/bin/startsrc
-s #{node['chef_client']['svc_name']} > /dev/console 2>&1'"
not_if "lsitab #{node['chef_client']['svc_name']}"
end
smartos_package resource
smartos_package resource pageUse the smartos_package resource to manage packages for the SmartOS platform.
Note
Syntax
The full syntax for all of the properties that are available to the smartos_package resource is:
smartos_package 'name' do
options String, Array
package_name String
source String
timeout String, Integer
version String
action Symbol # defaults to :install if not specified
end
where:
smartos_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.options
,package_name
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The smartos_package resource has the following actions:
:install
- Install a package. If a version is specified, install the specified version of the package. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove a package.
:upgrade
- Install a package and ensure that a package is the latest version.
Properties
The smartos_package resource has the following properties:
options
- Ruby Type: String, Array
One (or more) additional command options that are passed to the command.
package_name
- Ruby Type: String
An optional property to set the package name if it differs from the resource block’s name.
source
- Ruby Type: String
The optional path to a package on the local file system.
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String
The version of a package to be installed or upgraded.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
This resource does not have any examples.
snap_package resource
snap_package resource pageUse the snap_package resource to manage snap packages on Debian and Ubuntu platforms.
New in Chef Infra Client 15.0.
Syntax
The full syntax for all of the properties that are available to the snap_package resource is:
snap_package 'name' do
channel String # default value: "stable"
options String, Array
package_name String, Array
source String
timeout String, Integer
version String, Array
action Symbol # defaults to :install if not specified
end
where:
snap_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.channel
,options
,package_name
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The snap_package resource has the following actions:
:install
- Install a package. If a version is specified, install the specified version of the package. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:purge
- Purge a package. This action typically removes the configuration files as well as the package.
:remove
- Remove a package.
:upgrade
- Install a package and ensure that a package is the latest version.
Properties
The snap_package resource has the following properties:
channel
- Ruby Type: String | Default Value:
stable
Allowed Values:"beta", "candidate", "edge", "stable"
The default channel. For example: stable.
options
- Ruby Type: String, Array
One (or more) additional command options that are passed to the command.
package_name
- Ruby Type: String, Array
An optional property to set the package name if it differs from the resource block’s name.
source
- Ruby Type: String
The optional path to a package on the local file system.
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String, Array
The version of a package to be installed or upgraded.
Multiple Packages
A resource may specify multiple packages and/or versions for platforms that use Apt, Chocolatey, DNF, Homebrew, Pacman, or Zypper package managers. Specifying multiple packages and/or versions allows a single transaction to:
- Download the specified packages and versions using a single HTTP transaction
- Update or install multiple packages with a single resource during a Chef Infra Client run
For example, installing multiple packages:
package %w(package1 package2)
Installing multiple packages with versions:
package %w(package1 package2) do
version [ '1.3.4-2', '4.3.6-1']
end
Upgrading multiple packages:
package %w(package1 package2) do
action :upgrade
end
Removing multiple packages:
package %w(package1 package2) do
action :remove
end
Purging multiple packages:
package %w(package1 package2) do
action :purge
end
Notifications, using an implicit name:
package %w(package1 package2) do
action :nothing
end
log 'call a notification' do
notifies :install, 'package[package1, package2]', :immediately
end
Note
Notifications and subscriptions do not need to be updated when packages
and versions are added or removed from the package_name
or version
properties.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Multiple Packages
A resource may specify multiple packages and/or versions for platforms that use Apt, Chocolatey, DNF, Homebrew, Pacman, or Zypper package managers. Specifying multiple packages and/or versions allows a single transaction to:
- Download the specified packages and versions using a single HTTP transaction
- Update or install multiple packages with a single resource during a Chef Infra Client run
For example, installing multiple packages:
package %w(package1 package2)
Installing multiple packages with versions:
package %w(package1 package2) do
version [ '1.3.4-2', '4.3.6-1']
end
Upgrading multiple packages:
package %w(package1 package2) do
action :upgrade
end
Removing multiple packages:
package %w(package1 package2) do
action :remove
end
Purging multiple packages:
package %w(package1 package2) do
action :purge
end
Notifications, using an implicit name:
package %w(package1 package2) do
action :nothing
end
log 'call a notification' do
notifies :install, 'package[package1, package2]', :immediately
end
Note
Notifications and subscriptions do not need to be updated when packages
and versions are added or removed from the package_name
or version
properties.
Examples
This resource does not have any examples.
solaris_package resource
solaris_package resource pageUse the solaris_package resource to manage packages on the Solaris platform.
Syntax
The full syntax for all of the properties that are available to the solaris_package resource is:
solaris_package 'name' do
options String, Array
package_name String
source String
timeout String, Integer
version String
action Symbol # defaults to :install if not specified
end
where:
solaris_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.options
,package_name
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The solaris_package resource has the following actions:
:install
- Install a package. If a version is specified, install the specified version of the package. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove a package.
Properties
The solaris_package resource has the following properties:
options
- Ruby Type: String, Array
One (or more) additional command options that are passed to the command.
package_name
- Ruby Type: String
An optional property to set the package name if it differs from the resource block’s name.
source
- Ruby Type: String
The optional path to a package on the local file system.
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String
The version of a package to be installed or upgraded.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the solaris_package resource in recipes:
Install a package
solaris_package 'name of package' do
source '/packages_directory'
action :install
end
ssh_known_hosts_entry resource
ssh_known_hosts_entry resource pageUse the ssh_known_hosts_entry resource to add an entry for the specified host in /etc/ssh/ssh_known_hosts or a user’s known hosts file if specified.
New in Chef Infra Client 14.3.
Syntax
The full syntax for all of the properties that are available to the ssh_known_hosts_entry resource is:
ssh_known_hosts_entry 'name' do
file_location String # default value: "/etc/ssh/ssh_known_hosts"
group String, Integer # default value: The root user's group depending on platform.
hash_entries true, false # default value: false
host String # default value: 'name' unless specified
key String
key_type String # default value: "rsa"
mode String # default value: "0644"
owner String, Integer # default value: "root"
port Integer # default value: 22
timeout Integer # default value: 30
action Symbol # defaults to :create if not specified
end
where:
ssh_known_hosts_entry
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.file_location
,group
,hash_entries
,host
,key
,key_type
,mode
,owner
,port
, andtimeout
are the properties available to this resource.
Actions
The ssh_known_hosts_entry resource has the following actions:
:create
- Create an entry in the ssh_known_hosts file. (default)
:flush
- Immediately flush the entries to the config file. Without this the actual writing of the file is delayed in the Chef Infra Client run so all entries can be accumulated before writing the file out.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The ssh_known_hosts_entry resource has the following properties:
file_location
- Ruby Type: String | Default Value:
/etc/ssh/ssh_known_hosts
The location of the ssh known hosts file. Change this to set a known host file for a particular user.
group
- Ruby Type: String, Integer | Default Value:
The root user's group depending on platform.
The file group for the ssh_known_hosts file.
hash_entries
- Ruby Type: true, false | Default Value:
false
Hash the hostname and addresses in the ssh_known_hosts file for privacy.
host
- Ruby Type: String | Default Value:
The resource block's name
The host to add to the known hosts file.
key
- Ruby Type: String
An optional key for the host. If not provided this will be automatically determined.
key_type
- Ruby Type: String | Default Value:
rsa
The type of key to store.
mode
- Ruby Type: String | Default Value:
0644
The file mode for the ssh_known_hosts file.
owner
- Ruby Type: String, Integer | Default Value:
root
The file owner for the ssh_known_hosts file.
port
- Ruby Type: Integer | Default Value:
22
The server port that the ssh-keyscan command will use to gather the public key.
timeout
- Ruby Type: Integer | Default Value:
30
The timeout in seconds for ssh-keyscan.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the ssh_known_hosts_entry resource in recipes:
Add a single entry for github.com with the key auto detected
ssh_known_hosts_entry 'github.com'
Add a single entry with your own provided key
ssh_known_hosts_entry 'github.com' do
key 'node.example.com ssh-rsa ...'
end
subversion resource
subversion resource pageUse the subversion resource to manage source control resources that exist in a Subversion repository.
Warning
Syntax
The full syntax for all of the properties that are available to the subversion resource is:
subversion 'name' do
destination String # default value: 'name' unless specified
environment Hash
group String, Integer
repository String
revision String # default value: "HEAD"
svn_arguments String, false # default value: "--no-auth-cache"
svn_binary String
svn_info_args String, false # default value: "--no-auth-cache"
svn_password String
svn_username String
timeout Integer
user String, Integer
action Symbol # defaults to :sync if not specified
end
where:
subversion
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.destination
,environment
,group
,repository
,revision
,svn_arguments
,svn_binary
,svn_info_args
,svn_password
,svn_username
,timeout
, anduser
are the properties available to this resource.
Actions
The subversion resource has the following actions:
:checkout
- Clone or check out the source. When a checkout is available, this provider does nothing.
:export
- Export the source, excluding or removing any version control artifacts.
:force_export
- Export the source, excluding or removing any version control artifacts and force an export of the source that is overwriting the existing copy (if it exists).
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:sync
- Update the source to the specified version, or get a new clone or checkout. This action causes a hard reset of the index and working tree, discarding any uncommitted changes. (default)
Properties
The subversion resource has the following properties:
destination
- Ruby Type: String | Default Value:
The resource block's name
The location path to which the source is to be cloned, checked out, or exported. Default value: the name of the resource block.
environment
- Ruby Type: Hash
A Hash of environment variables in the form of ({‘ENV_VARIABLE’ => ‘VALUE’}).
group
- Ruby Type: String, Integer
The system group that will own the checked-out code.
repository
- Ruby Type: String
The URI of the code repository.
revision
- Ruby Type: String | Default Value:
HEAD
A branch, tag, or commit to be synchronized with git. This can be symbolic, like
HEAD
or it can be a source control management-specific revision identifier.
svn_arguments
- Ruby Type: String, false | Default Value:
--no-auth-cache
The extra arguments that are passed to the Subversion command.
svn_binary
- Ruby Type: String
The location of the svn binary.
svn_info_args
- Ruby Type: String, false | Default Value:
--no-auth-cache
Use when the
svn info
command is used by Chef Infra Client and arguments need to be passed. Thesvn_arguments
command does not work when thesvn info
command is used.
svn_password
- Ruby Type: String
The password for a user that has access to the Subversion repository.
svn_username
- Ruby Type: String
The user name for a user that has access to the Subversion repository.
timeout
- Ruby Type: Integer
The amount of time (in seconds) to wait before timing out.
user
- Ruby Type: String, Integer | Default Value:
`HOME` environment variable of the user running chef-client
The system user that will own the checked-out code.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the subversion resource in recipes:
Get the latest version of an application
subversion 'CouchDB Edge' do
repository 'http://svn.apache.org/repos/asf/couchdb/trunk'
revision 'HEAD'
destination '/opt/my_sources/couch'
action :sync
end
sudo resource
sudo resource pageUse the sudo resource to add or remove individual sudo entries using sudoers.d files. Sudo version 1.7.2 or newer is required to use the sudo resource, as it relies on the #includedir
directive introduced in version 1.7.2. This resource does not enforce installation of the required sudo version. Chef-supported releases of Ubuntu, SuSE, Debian, and RHEL (6+) all support this feature.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the sudo resource is:
sudo 'name' do
command_aliases Array # default value: []
commands Array # default value: ["ALL"]
config_prefix String # default value: "Prefix values based on the node's platform"
defaults Array # default value: []
env_keep_add Array # default value: []
env_keep_subtract Array # default value: []
filename String # default value: 'name' unless specified
groups String, Array # default value: []
host String # default value: "ALL"
noexec true, false # default value: false
nopasswd true, false # default value: false
runas String # default value: "ALL"
setenv true, false # default value: false
template String
users String, Array # default value: []
variables Hash
visudo_binary String # default value: "/usr/sbin/visudo"
action Symbol # defaults to :create if not specified
end
where:
sudo
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.command_aliases
,commands
,config_prefix
,defaults
,env_keep_add
,env_keep_subtract
,filename
,groups
,host
,noexec
,nopasswd
,runas
,setenv
,template
,users
,variables
, andvisudo_binary
are the properties available to this resource.
Actions
The sudo resource has the following actions:
:create
- Create a single sudoers configuration file in the
sudoers.d
directory. (default) :delete
- Remove a sudoers configuration file from the
sudoers.d
directory. :nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The sudo resource has the following properties:
command_aliases
- Ruby Type: Array | Default Value:
[]
Command aliases that can be used as allowed commands later in the configuration.
commands
- Ruby Type: Array | Default Value:
["ALL"]
An array of full paths to commands this sudoer can execute.
config_prefix
- Ruby Type: String | Default Value:
Prefix values based on the node's platform
The directory that contains the sudoers configuration file.
defaults
- Ruby Type: Array | Default Value:
[]
An array of defaults for the user/group.
env_keep_add
- Ruby Type: Array | Default Value:
[]
An array of strings to add to
env_keep
.
env_keep_subtract
- Ruby Type: Array | Default Value:
[]
An array of strings to remove from
env_keep
.
filename
- Ruby Type: String | Default Value:
The resource block's name
The name of the sudoers.d file if it differs from the name of the resource block
groups
- Ruby Type: String, Array | Default Value:
[]
Group(s) to provide sudo privileges to. This property accepts either an array or a comma separated list. Leading % on group names is optional.
host
- Ruby Type: String | Default Value:
ALL
The host to set in the sudo configuration.
noexec
- Ruby Type: true, false | Default Value:
false
Prevent commands from shelling out.
nopasswd
- Ruby Type: true, false | Default Value:
false
Allow sudo to be run without specifying a password.
runas
- Ruby Type: String | Default Value:
ALL
User that the command(s) can be run as.
setenv
- Ruby Type: true, false | Default Value:
false
Determines whether or not to permit preservation of the environment with
sudo -E
.
template
- Ruby Type: String
The name of the erb template in your cookbook, if you wish to supply your own template.
users
- Ruby Type: String, Array | Default Value:
[]
User(s) to provide sudo privileges to. This property accepts either an array or a comma separated list.
variables
- Ruby Type: Hash
The variables to pass to the custom template. This property is ignored if not using a custom template.
visudo_binary
- Ruby Type: String | Default Value:
/usr/sbin/visudo
The path to visudo for configuration verification.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the sudo resource in recipes:
Grant a user sudo privileges for any command
sudo 'admin' do
user 'admin'
end
Grant a user and groups sudo privileges for any command
sudo 'admins' do
users 'bob'
groups 'sysadmins, superusers'
end
Grant passwordless sudo privileges for specific commands
sudo 'passwordless-access' do
commands ['/bin/systemctl restart httpd', '/bin/systemctl restart mysql']
nopasswd true
end
swap_file resource
swap_file resource pageUse the swap_file resource to create or delete swap files on Linux systems, and optionally to manage the swappiness configuration for a host.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the swap_file resource is:
swap_file 'name' do
path String # default value: 'name' unless specified
persist true, false # default value: false
size Integer
swappiness Integer
timeout Integer # default value: 600
action Symbol # defaults to :create if not specified
end
where:
swap_file
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.path
,persist
,size
,swappiness
, andtimeout
are the properties available to this resource.
Actions
The swap_file resource has the following actions:
:create
- Create a swapfile. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove a swapfile and disable swap.
Properties
The swap_file resource has the following properties:
path
- Ruby Type: String | Default Value:
The resource block's name
The path where the swap file will be created on the system if it differs from the resource block’s name.
persist
- Ruby Type: true, false | Default Value:
false
Persist the swapon.
size
- Ruby Type: Integer
The size (in MBs) of the swap file.
swappiness
- Ruby Type: Integer
The swappiness value to set on the system.
timeout
- Ruby Type: Integer | Default Value:
600
Timeout for
dd
/fallocate
commands.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the swap_file resource in recipes:
Create a swap file
swap_file '/dev/sda1' do
size 1024
end
Remove a swap file
swap_file '/dev/sda1' do
action :remove
end
sysctl resource
sysctl resource pageUse the sysctl resource to set or remove kernel parameters using the sysctl
command line tool and configuration files in the system’s sysctl.d
directory. Configuration files managed by this resource are named 99-chef-KEYNAME.conf
.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the sysctl resource is:
sysctl 'name' do
comment Array, String # default value: []
conf_dir String # default value: "/etc/sysctl.d"
ignore_error true, false # default value: false
key String # default value: 'name' unless specified
value Array, String, Integer, Float
action Symbol # defaults to :apply if not specified
end
where:
sysctl
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.comment
,conf_dir
,ignore_error
,key
, andvalue
are the properties available to this resource.
Actions
The sysctl resource has the following actions:
:apply
- Set the kernel parameter and update the
sysctl
settings. (default) :nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove the kernel parameter and update the
sysctl
settings.
Properties
The sysctl resource has the following properties:
comment
- Ruby Type: Array, String | Default Value:
[]
Comments, placed above the resource setting in the generated file. For multi-line comments, use an array of strings, one per line.
New in Chef Infra Client 15.8
conf_dir
- Ruby Type: String | Default Value:
/etc/sysctl.d
The configuration directory to write the config to.
ignore_error
- Ruby Type: true, false | Default Value:
false
Ignore any errors when setting the value on the command line.
key
- Ruby Type: String | Default Value:
The resource block's name
The kernel parameter key in dotted format if it differs from the resource block’s name.
value
- Ruby Type: Array, String, Integer, Float |
REQUIRED
The value to set.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the sysctl resource in recipes:
Set vm.swappiness:
sysctl 'vm.swappiness' do
value 19
end
Remove kernel.msgmax:
Note: This only removes the sysctl.d config for kernel.msgmax. The value will be set back to the kernel default value.
sysctl 'kernel.msgmax' do
action :remove
end
Adding Comments to sysctl configuration files:
sysctl 'vm.swappiness' do
value 19
comment "define how aggressively the kernel will swap memory pages."
end
This produces /etc/sysctl.d/99-chef-vm.swappiness.conf as follows:
# define how aggressively the kernel will swap memory pages.
vm.swappiness = 1
Converting sysctl settings from shell scripts:
Example of existing settings:
fs.aio-max-nr = 1048576 net.ipv4.ip_local_port_range = 9000 65500 kernel.sem = 250 32000 100 128
Converted to sysctl resources:
sysctl 'fs.aio-max-nr' do
value '1048576'
end
sysctl 'net.ipv4.ip_local_port_range' do
value '9000 65500'
end
sysctl 'kernel.sem' do
value '250 32000 100 128'
end
systemd_unit resource
systemd_unit resource pageUse the systemd_unit resource to create, manage, and run systemd units.
New in Chef Infra Client 12.11.
Syntax
The full syntax for all of the properties that are available to the systemd_unit resource is:
systemd_unit 'name' do
content String, Hash
triggers_reload true, false # default value: true
unit_name String # default value: 'name' unless specified
user String
verify true, false # default value: true
action Symbol # defaults to :nothing if not specified
end
where:
systemd_unit
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.content
,triggers_reload
,unit_name
,user
, andverify
are the properties available to this resource.
Actions
The systemd_unit resource has the following actions:
:create
- Create a systemd unit file, if it does not already exist.
:delete
- Delete a systemd unit file, if it exists.
:disable
- Ensure the unit will not be started after the next system boot.
:enable
- Ensure the unit will be started after the next system boot.
:mask
- Ensure the unit will not start, even to satisfy dependencies.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run. (default)
:preset
- Restore the preset ‘
enable
/disable
’ configuration for a systemd unit. New in Chef Infra Client 14.0. :reenable
- Reenable a unit file. New in Chef Infra Client 14.0.
:reload
- Reload the configuration file for a systemd unit.
:reload_or_restart
- For systemd units that are services, this action reloads the configuration of the service without restarting, if possible; otherwise, it will restart the service so the new configuration is applied.
:reload_or_try_restart
- For systemd units that are services, this action reloads the configuration of the service without restarting, if possible; otherwise, it will try to restart the service so the new configuration is applied.
:restart
- Restart a systemd unit.
:revert
- Revert to a vendor’s version of a systemd unit file. New in Chef Infra Client 14.0.
:start
- Start a systemd unit.
:stop
- Stop a running systemd unit.
:try_restart
- Try to restart a systemd unit if the unit is running.
:unmask
- Stop the unit from being masked and cause it to start as specified.
Properties
The systemd_unit resource has the following properties:
content
- Ruby Type: String, Hash
A string or hash that contains a systemd unit file definition that describes the properties of systemd-managed entities, such as services, sockets, devices, and so on. In Chef Infra Client 14.4 or later, repeatable options can be implemented with an array.
triggers_reload
- Ruby Type: true, false | Default Value:
true
Specifies whether to trigger a daemon reload when creating or deleting a unit.
unit_name
- Ruby Type: String | Default Value:
The resource block's name
The name of the unit file if it differs from the resource block’s name.
New in Chef Client 13.7
user
- Ruby Type: String
The user account that the systemd unit process is run under. The path to the unit for that user would be something like ‘/etc/systemd/user/sshd.service’. If no user account is specified, the systemd unit will run under a ‘system’ account, with the path to the unit being something like ‘/etc/systemd/system/sshd.service’.
verify
- Ruby Type: true, false | Default Value:
true
Specifies if the unit will be verified before installation. Systemd can be overly strict when verifying units, so in certain cases it is preferable not to verify the unit.
Unit file verification
The unit file is verified using a systemd-analyze verify
call before
being written to disk.
Be aware that the referenced commands and files need to already exist before verification.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the systemd_unit resource in recipes:
Create systemd service unit file from a Hash
systemd_unit 'etcd.service' do
content({ Unit: {
Description: 'Etcd',
Documentation: ['https://coreos.com/etcd', 'man:etcd(1)'],
After: 'network.target',
},
Service: {
Type: 'notify',
ExecStart: '/usr/local/etcd',
Restart: 'always',
},
Install: {
WantedBy: 'multi-user.target',
} })
action [:create, :enable]
end
Create systemd service unit file from a String
systemd_unit 'sysstat-collect.timer' do
content <<~EOU
[Unit]
Description=Run system activity accounting tool every 10 minutes
[Timer]
OnCalendar=*:00/10
[Install]
WantedBy=sysstat.service
EOU
action [:create, :enable]
end
template resource
template resource pageA cookbook template is an Embedded Ruby (ERB) template that is used to dynamically generate static text files. Templates may contain Ruby expressions and statements, and are a great way to manage configuration files. Use the template resource to add cookbook templates to recipes; place the corresponding Embedded Ruby (ERB) template file in a cookbook’s /templates
directory.
Use the template resource to manage the contents of a file using an Embedded Ruby (ERB) template by transferring files from a sub-directory of COOKBOOK_NAME/templates/
to a specified path located on a host that is running Chef Infra Client. This resource includes actions and properties from the file resource. Template files managed by the template resource follow the same file specificity rules as the remote_file and file resources.
Syntax
A template resource block typically declares the location in which a file is to be created, the source template that will be used to create the file, and the permissions needed on that file. For example:
template '/etc/motd' do
source 'motd.erb'
owner 'root'
group 'root'
mode '0755'
end
where:
'/etc/motd'
specifies the location in which the file is created'motd.erb'
specifies the name of a template that exists in in the/templates
folder of a cookbookowner
,group
, andmode
define the permissions
The full syntax for all of the properties that are available to the template resource is:
template 'name' do
atomic_update true, false
backup false, Integer
cookbook String
force_unlink true, false
group String, Integer
helper(:method) Method { String } # see Helpers below
helpers(module) Module # see Helpers below
inherits true, false
local true, false
manage_symlink_source true, false
mode String, Integer
owner String, Integer
path String # defaults to 'name' if not specified
rights Hash
sensitive true, false
source String, Array
variables Hash
verify String, Block
action Symbol # defaults to :create if not specified
end
where:
template
is the resourcename
is the name of the resource block, typically the path to the location in which a file is created and also the name of the file to be managed. For example:/var/www/html/index.html
, where/var/www/html/
is the fully qualified path to the location andindex.html
is the name of the filesource
is the template file that will be used to create the file on the node, for example:index.html.erb
; the template file is located in the/templates
directory of a cookbookaction
identifies the steps Chef Infra Client will take to bring the node into the desired stateatomic_update
,backup
,cookbook
,force_unlink
,group
,helper
,helpers
,inherits
,local
,manage_symlink_source
,mode
,owner
,path
,rights
,source
,variables
, andverify
are properties of this resource, with the Ruby type shown. See “Properties” section below for more information about all of the properties that may be used with this resource.
Actions
The template resource has the following actions:
:create
- (default) Create a file. If a file already exists (but does not match), update that file to match.
:create_if_missing
- Create a file only if the file does not exist. When the file exists, nothing happens.
:delete
- Delete a file.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:touch
- Touch a file. This updates the access (atime) and file modification (mtime) times for a file. (This action may be used with this resource, but is typically only used with the file resource.)
Properties
The template resource has the following properties:
atomic_update
- Ruby Type: true, false
Perform atomic file updates on a per-resource basis. Set to
true
for atomic file updates. Set tofalse
for non-atomic file updates. This setting overridesfile_atomic_update
, which is a global setting found in the client.rb file.
backup
- Ruby Type: Integer, false | Default Value:
5
The number of backups to be kept in
/var/chef/backup
(for UNIX- and Linux-based platforms) orC:/chef/backup
(for the Microsoft Windows platform). Set tofalse
to prevent backups from being kept.
cookbook
- Ruby Type: String
The cookbook in which a file is located (if it is not located in the current cookbook). The default value is the current cookbook.
force_unlink
- Ruby Type: true, false | Default Value:
false
How Chef Infra 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 Chef Infra Client to delete the non-file target and replace it with the specified file. Set tofalse
for Chef Infra Client to raise an error.
group
- Ruby Type: Integer, String
A string or ID that identifies the group owner by group name or SID, including fully qualified group names such as
domain\group
orgroup@domain
. If this value is not specified, existing groups remain unchanged and new group assignments use the defaultPOSIX
group (if available).
helper
- Ruby Type: Method | Default Value:
{}
Define a helper method inline. For example:
helper(:hello_world) { "hello world" }
orhelper(:app) { node["app"] }
orhelper(:app_conf) { |setting| node["app"][setting] }
.
helpers
- Ruby Type: Module | Default Value:
[]
Define a helper module inline or in a library. For example, an inline module:
helpers do
, which is then followed by a block of Ruby code. And for a library module:helpers(MyHelperModule)
.
inherits
- Ruby Type: true, false | Default Value:
true
Microsoft Windows only. Whether a file inherits rights from its parent directory.
local
- Ruby Type: true, false | Default Value:
false
Load a template from a local path. By default, Chef Infra Client loads templates from a cookbook’s
/templates
directory. When this property is set totrue
, use thesource
property to specify the path to a template on the local node.
manage_symlink_source
- Ruby Type: true, false | Default Value:
true
(with warning) Change the behavior of the file resource if it is pointed at a symlink. When this value is set to
true
, Chef Infra 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 tofalse
, Chef will follow the symlink and will manage the permissions and content of the symlink’s target file. The default behavior istrue
but emits a warning that the default value will be changed tofalse
in a future version; setting this explicitly totrue
orfalse
suppresses this warning.
mode
- Ruby Type: Integer, String
A quoted 3-5 character string that defines the octal mode. For example:
'755'
,'0755'
, or00755
. Ifmode
is not specified and if the file already exists, the existing mode on the file is used. Ifmode
is not specified, the file does not exist, and the:create
action is specified, Chef Infra Client assumes a mask value of'0777'
and then applies the umask for the system on which the file is to be created to themask
value. For example, if the umask on a system is'022'
, Chef Infra Client uses the default value of'0755'
. The behavior is different depending on the platform. UNIX- and Linux-based systems: A quoted 3-5 character string that defines the octal mode that is passed to chmod. For example:'755'
,'0755'
, or00755
. If the value is specified as a quoted string, it works exactly as if thechmod
command was passed. If the value is specified as an integer, prepend a zero (0
) to the value to ensure that it is interpreted as an octal number. For example, to assign read, write, and execute rights for all users, use'0777'
or'777'
; for the same rights, plus the sticky bit, use01777
or'1777'
.Microsoft Windows: A quoted 3-5 character string that defines the octal mode that is translated into rights for Microsoft Windows security. For example:
'755'
,'0755'
, or00755
. Values up to'0777'
are allowed (no sticky bits) and mean the same in Microsoft Windows as they do in UNIX, where4
equalsGENERIC_READ
,2
equalsGENERIC_WRITE
, and1
equalsGENERIC_EXECUTE
. This property cannot be used to set:full_control
. This property has no effect if not specified, but when it andrights
are both specified, the effects are cumulative.
owner
- Ruby Type: Integer, String
A string or ID that identifies the group owner by user name or SID, including fully qualified user names such as
domain\user
oruser@domain
. If this value is not specified, existing owners remain unchanged and new owner assignments use the current user (when necessary).
path
- Ruby Type: String | Default Value:
The resource block's name
The full path to the file, including the file name and its extension. Microsoft Windows: A path that begins with a forward slash (
/
) will point to the root of the current working directory of Chef Infra Client process. This path can vary from system to system. Therefore, using a path that begins with a forward slash (/
) is not recommended.
rights
- Ruby Type: Integer, String
Microsoft Windows only. The permissions for users and groups in a Microsoft Windows environment. For example:
rights <permissions>, <principal>, <options>
where<permissions>
specifies the rights granted to the principal,<principal>
is the group or user name, and<options>
is a Hash with one (or more) advanced rights options.
source
- Ruby Type: String, Array
The location of a template file. By default, Chef Infra Client looks for a template file in the
/templates
directory of a cookbook. When thelocal
property is set totrue
, use to specify the path to a template on the local node. This property may also be used to distribute specific files to specific platforms. See “File Specificity” below for more information. Default value: thename
of the resource block. See “Syntax” section above for more information.
variables
- Ruby Type: Hash
A Hash of variables that are passed into a Ruby template file.
The
variables
property of the template resource can be used to reference a partial template file by using a Hash. For example:template '/file/name.txt' do variables partials: { 'partial_name_1.txt.erb' => 'message', 'partial_name_2.txt.erb' => 'message', 'partial_name_3.txt.erb' => 'message', } end
where each of the partial template files can then be combined using normal Ruby template patterns within a template file, such as:
<% @partials.each do |partial, message| %> Here is <%= partial %> <%= render partial, :variables => {:message => message} %> <% end %>
verify
- Ruby Type: String, Block
A block or a string that returns
true
orfalse
. A string, whentrue
is executed as a system command.A block is arbitrary Ruby defined within the resource block by using the
verify
property. When a block istrue
, Chef Infra Client will continue to update the file as appropriate.For example, this should return
true
:template '/tmp/baz' do verify { 1 == 1 } end
This should return
true
:template '/etc/nginx.conf' do verify 'nginx -t -c %{path}' end
This should return
true
:template '/tmp/bar' do verify { 1 == 1} end
And this should return
true
:template '/tmp/foo' do verify do |path| true end end
Whereas, this should return
false
:template '/tmp/turtle' do verify '/usr/bin/false' end
If a string or a block return
false
, the Chef Infra Client run will stop and an error is returned.
Atomic File Updates
Atomic updates are used with file-based resources to help ensure that file updates can be made when updating a binary or if disk space runs out.
Atomic updates are enabled by default. They can be managed globally
using the file_atomic_update
setting in the client.rb
file. They can
be managed for each resource using the atomic_update
property
that is available with the cookbook_file, file,
remote_file, and template resources.
Note
On certain platforms, and after a file has been moved into place, Chef
Infra Client may modify file permissions to support features specific to
those platforms. On platforms with SELinux enabled, Chef Infra Client
will fix up the security contexts after a file has been moved into the
correct location by running the restorecon
command. On the Microsoft
Windows platform, Chef Infra Client will create files so that ACL
inheritance works as expected.
Windows File Security
To support Windows security, the template, file, remote_file, cookbook_file, directory, and remote_directory resources support the use of inheritance and access control lists (ACLs) within recipes. Access Control Lists (ACLs)The rights
property can be used in a recipe to manage access control
lists (ACLs), which allow permissions to be given to multiple users and
groups. Use the rights
property can be used as many times as
necessary; Chef Infra Client will apply them to the file or directory as
required. The syntax for the rights
property is as follows:
rights permission, principal, option_type => value
where
permission
Use to specify which rights are granted to the
principal
. The possible values are::read
,:write
,read_execute
,:modify
,:full_control
, or an integer.Integers used for permissions must match the following list FileSystemRights Enum fields.
These permissions are cumulative. If
:write
is specified, then it includes:read
. If:full_control
is specified, then it includes both:write
and:read
.(For those who know the Windows API:
:read
corresponds toGENERIC_READ
;:write
corresponds toGENERIC_WRITE
;:read_execute
corresponds toGENERIC_READ
andGENERIC_EXECUTE
;:modify
corresponds toGENERIC_WRITE
,GENERIC_READ
,GENERIC_EXECUTE
, andDELETE
;:full_control
corresponds toGENERIC_ALL
, which allows a user to change the owner and other metadata about a file.)principal
Use to specify a group or user. The principal can be specified by either name or SID. When using name, this is identical to what is entered in the login box for Windows, such as
user_name
,domain\user_name
, oruser_name@fully_qualified_domain_name
. When using a SID, you may use either the standard string representation of a SID (S-R-I-S-S) or one of the SDDL string constants. Chef Infra Client does not need to know if a principal is a user or a group.option_type
A hash that contains advanced rights options. For example, the rights to a directory that only applies to the first level of children might look something like:
rights :write, 'domain\group_name', :one_level_deep => true
.Possible option types:
:applies_to_children
Specify how permissions are applied to children. Possible values:
true
to inherit both child directories and files;false
to not inherit any child directories or files;:containers_only
to inherit only child directories (and not files);:objects_only
to recursively inherit files (and not child directories).:applies_to_self
Indicates whether a permission is applied to the parent directory. Possible values:
true
to apply to the parent directory or file and its children;false
to not apply only to child directories and files.:one_level_deep
Indicates the depth to which permissions will be applied. Possible values:
true
to apply only to the first level of children;false
to apply to all children.
For example:
resource 'x.txt' do
rights :read, 'S-1-1-0'
rights :write, 'domain\group'
rights :full_control, 'group_name_or_user_name'
rights :full_control, 'user_name', applies_to_children: true
end
or:
rights :read, %w(Administrators Everyone)
rights :full_control, 'Users', applies_to_children: true
rights :write, 'Sally', applies_to_children: :containers_only, applies_to_self: false, one_level_deep: true
Some other important things to know when using the rights
attribute:
- Only inherited rights remain. All existing explicit rights on the object are removed and replaced.
- If rights are not specified, nothing will be changed. Chef Infra Client does not clear out the rights on a file or directory if rights are not specified.
- Changing inherited rights can be expensive. Windows will propagate rights to all children recursively due to inheritance. This is a normal aspect of Windows, so consider the frequency with which this type of action is necessary and take steps to control this type of action if performance is the primary consideration.
Use the deny_rights
property to deny specific rights to specific
users. The ordering is independent of using the rights
property. For
example, it doesn’t matter if rights are granted to everyone is placed
before or after deny_rights :read, ['Julian', 'Lewis']
, both Julian
and Lewis will be unable to read the document. For example:
resource 'x.txt' do
rights :read, 'Everyone'
rights :write, 'domain\group'
rights :full_control, 'group_name_or_user_name'
rights :full_control, 'user_name', applies_to_children: true
deny_rights :read, %w(Julian Lewis)
end
or:
deny_rights :full_control, ['Sally']
By default, a file or directory inherits rights from its parent
directory. Most of the time this is the preferred behavior, but
sometimes it may be necessary to take steps to more specifically control
rights. The inherits
property can be used to specifically tell Chef
Infra Client to apply (or not apply) inherited rights from its parent
directory.
For example, the following example specifies the rights for a directory:
directory 'C:\mordor' do
rights :read, 'MORDOR\Minions'
rights :full_control, 'MORDOR\Sauron'
end
and then the following example specifies how to use inheritance to deny access to the child directory:
directory 'C:\mordor\mount_doom' do
rights :full_control, 'MORDOR\Sauron'
inherits false # Sauron is the only person who should have any sort of access
end
If the deny_rights
permission were to be used instead, something could
slip through unless all users and groups were denied.
Another example also shows how to specify rights for a directory:
directory 'C:\mordor' do
rights :read, 'MORDOR\Minions'
rights :full_control, 'MORDOR\Sauron'
rights :write, 'SHIRE\Frodo' # Who put that there I didn't put that there
end
but then not use the inherits
property to deny those rights on a child
directory:
directory 'C:\mordor\mount_doom' do
deny_rights :read, 'MORDOR\Minions' # Oops, not specific enough
end
Because the inherits
property is not specified, Chef Infra Client will
default it to true
, which will ensure that security settings for
existing files remain unchanged.
Using Templates
To use a template, two things must happen:
- A template resource must be added to a recipe
- An Embedded Ruby (ERB) template must be added to a cookbook
For example, the following template file and template resource settings
can be used to manage a configuration file named /etc/sudoers
. Within
a cookbook that uses sudo, the following resource could be added to
/recipes/default.rb
:
template '/etc/sudoers' do
source 'sudoers.erb'
mode '0440'
owner 'root'
group 'root'
variables(sudoers_groups: node['authorization']['sudo']['groups'],
sudoers_users: node['authorization']['sudo']['users'])
end
And then create a template called sudoers.erb
and save it to
templates/default/sudoers.erb
:
#
# /etc/sudoers
#
# Generated by Chef for <%= node['fqdn'] %>
#
Defaults !lecture,tty_tickets,!fqdn
# User privilege specification
root ALL=(ALL) ALL
<% @sudoers_users.each do |user| -%>
<%= user %> ALL=(ALL) <%= "NOPASSWD:" if @passwordless %>ALL
<% end -%>
# Members of the sysadmin group may gain root privileges
%sysadmin ALL=(ALL) <%= "NOPASSWD:" if @passwordless %>ALL
<% @sudoers_groups.each do |group| -%>
# Members of the group '<%= group %>' may gain root privileges
<%= group %> ALL=(ALL) <%= "NOPASSWD:" if @passwordless %>ALL
<% end -%>
And then set the default attributes in attributes/default.rb
:
default['authorization']['sudo']['groups'] = %w(sysadmin wheel admin)
default['authorization']['sudo']['users'] = %w(jerry greg)
File Specificity
A cookbook is frequently designed to work across many platforms and is often required to distribute a specific template to a specific platform. A cookbook can be designed to support the distribution of templates across platforms, while ensuring that the correct template ends up on each system.The pattern for template specificity depends on two things: the lookup path and the source. The first pattern that matches is used:
/host-$fqdn/$source
/$platform-$platform_version/$source
/$platform/$source
/default/$source
/$source
Note
To specify a particular Windows version, use the operating system
version
number.
For example, a template in templates/windows-6.3
will be deployed on
systems installed with Windows 8.1.
Use an array with the source
property to define an explicit lookup
path. For example:
template '/test' do
source ["#{node.chef_environment}.erb", 'default.erb']
end
The following example emulates the entire file specificity pattern by defining it as an explicit path:
template '/test' do
source %W(
host-#{node['fqdn']}/test.erb
#{node['platform']}-#{node['platform_version']}/test.erb
#{node['platform']}/test.erb
default/test.erb
)
end
A cookbook may have a /templates
directory structure like this:
/templates/
windows-10
windows-6.3
windows
default
and a resource that looks something like the following:
template 'C:\path\to\file\text_file.txt' do
source 'text_file.txt'
mode '0755'
owner 'root'
group 'root'
end
This resource would be matched in the same order as the /templates
directory structure. For a node named host-node-desktop
that is
running Windows 8.1, the second item would be the matching item and the
location:
/templates
windows-10/text_file.txt
windows-6.3/text_file.txt
windows/text_file.txt
default/text_file.txt
Helpers
A helper is a method or a module that can be used to extend a template. There are three approaches:
- An inline helper method
- An inline helper module
- A cookbook library module
Use the helper
attribute in a recipe to define an inline helper
method. Use the helpers
attribute to define an inline helper module or
a cookbook library module.
Inline Methods
A template helper method is always defined inline on a resource basis. A simple example:
template '/path' do
helper(:hello_world) { 'hello world' }
end
Another way to define an inline helper method is to reference a node object so that repeated calls to one (or more) cookbook attributes can be done efficiently:
template '/path' do
helper(:app) { node['app'] }
end
An inline helper method can also take arguments:
template '/path' do
helper(:app_conf) { |setting| node['app'][setting] }
end
Once declared, a template can then use the helper methods to build a file. For example:
Say hello: <%= hello_world %>
or:
node['app']['listen_port'] is: <%= app['listen_port'] %>
or:
node['app']['log_location'] is: <%= app_conf('log_location') %>
Inline Modules
A template helper module can be defined inline on a resource basis. This approach can be useful when a template requires more complex information. For example:
template '/path' do
helpers do
def hello_world
'hello world'
end
def app
node['app']
end
def app_conf(setting)
node['app']['setting']
end
end
end
where the hello_world
, app
, and app_conf(setting)
methods comprise
the module that extends a template.
Library Modules
A template helper module can be defined in a library. This is useful when extensions need to be reused across recipes or to make it easier to manage code that would otherwise be defined inline for each recipe basis.
template '/path/to/template.erb' do
helpers(MyHelperModule)
end
Host Notation
The naming of folders within cookbook directories must literally match the host notation used for template specificity matching. For example, if a host is namedfoo.example.com
, then the folder must be named
host-foo.example.com
.Partial Templates
A template can be built in a way that allows it to contain references to one (or more) smaller template files. (These smaller template files are also referred to as partials.) A partial can be referenced from a template file in one of the following ways:
- By using the
render
method in the template file - By using the template resource and the
variables
property.
render Method
Use the render
method in a template to reference a partial template
file:
<%= render 'partial_name.txt.erb', :option => {} %>
where partial_name
is the name of the partial template file and
:option
is one (or more) of the following:
Option | Description |
---|---|
:cookbook | By default, a partial template file is assumed to be located in the cookbook that contains the top-level template. Use this option to specify the path to a different cookbook |
:local | Indicates that the name of the partial template file should be interpreted as a path to a file in the local file system or looked up in a cookbook using the normal rules for template files. Set to true to interpret as a path to a file in the local file system and to false to use the normal rules for template files |
:source | By default, a partial template file is identified by its file name. Use this option to specify a different name or a local path to use (instead of the name of the partial template file) |
:variables | A hash of variable_name => value that will be made available to the partial template file. When this option is used, any variables that are defined in the top-level template that are required by the partial template file must have them defined explicitly using this option |
For example:
<%= render 'simple.txt.erb', :variables => {:user => Etc.getlogin }, :local => true %>
Transfer Frequency
The Chef Infra Client caches a template when it is first requested. On each subsequent request for that template, the Chef Infra Client compares that request to the template located on the Chef Infra Server. If the templates are the same, no transfer occurs.Variables
An Embedded Ruby (ERB) template allows Ruby code to be embedded inside a
text file within specially formatted tags. Ruby code can be embedded
using expressions and statements. An expression is delimited by <%=
and %>
. For example:
<%= "my name is #{$ruby}" %>
A statement is delimited by a modifier, such as if
, elsif
, and
else
. For example:
if false
# this will not happen
elsif nil
# this will not either
end
Using a Ruby expression is the most common approach for defining
template variables because this is how all variables that are sent to a
template are referenced. Whenever a template needs to use an each
,
if
, or end
, use a Ruby statement.
When a template is rendered, Ruby expressions and statements are
evaluated by Chef Infra Client. The variables listed in the template
resource’s variables
parameter and in the node object are evaluated.
Chef Infra Client then passes these variables to the template, where
they will be accessible as instance variables within the template. The
node object can be accessed just as if it were part of a recipe, using
the same syntax.
For example, a simple template resource like this:
node['fqdn'] = 'latte'
template '/tmp/foo' do
source 'foo.erb'
variables(x_men: 'are keen')
end
And a simple Embedded Ruby (ERB) template like this:
The node <%= node[:fqdn] %> thinks the x-men <%= @x_men %>
Would render something like:
The node latte thinks the x-men are keen
Even though this is a simple example, the full capabilities of Ruby can be used to tackle even the most complex and demanding template requirements.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the template resource in recipes:
Configure a file from a template
template '/tmp/config.conf' do
source 'config.conf.erb'
end
Configure a file from a local template
template '/tmp/config.conf' do
local true
source '/tmp/config.conf.erb'
end
Configure a file using a variable map
template '/tmp/config.conf' do
source 'config.conf.erb'
variables(
:config_var => node['configs']['config_var']
)
end
Use the not_if condition
The following example shows how to use the not_if
condition to create
a file based on a template and using the presence of an attribute value
on the node to specify the condition:
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
not_if { node['some_value'] }
end
The following example shows how to use the not_if
condition to create
a file based on a template and then Ruby code to specify the condition:
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
not_if do
File.exist?('/etc/passwd')
end
end
The following example shows how to use the not_if
condition to create
a file based on a template and using a Ruby block (with curly braces) to
specify the condition:
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
not_if { File.exist?('/etc/passwd') }
end
The following example shows how to use the not_if
condition to create
a file based on a template and using a string to specify the condition:
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
not_if 'test -f /etc/passwd'
end
Use the only_if condition
The following example shows how to use the only_if
condition to create
a file based on a template and using the presence of an attribute on the
node to specify the condition:
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
only_if { node['some_value'] }
end
The following example shows how to use the only_if
condition to create
a file based on a template, and then use Ruby to specify a condition:
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
only_if { ! ::File.exist?('/etc/passwd') }
end
The following example shows how to use the only_if
condition to create
a file based on a template and using a string to specify the condition:
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
only_if 'test -f /etc/passwd'
end
Use a whitespace array (%w)
The following example shows how to use a Ruby whitespace array to define a list of configuration tools, and then use that list of tools within the template resource to ensure that all of these configuration tools are using the same RSA key:
%w{openssl.cnf pkitool vars Rakefile}.each do |f|
template "/etc/openvpn/easy-rsa/#{f}" do
source "#{f}.erb"
owner 'root'
group 'root'
mode '0755'
end
end
Use a relative path
template "#{ENV['HOME']}/chef-getting-started.txt" do
source 'chef-getting-started.txt.erb'
mode '0755'
end
Delay notifications
template '/etc/nagios3/configures-nagios.conf' do
# other parameters
notifies :run, 'execute[test-nagios-config]', :delayed
end
Notify immediately
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 an action immediately, use :immediately
:
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:
execute 'test-nagios-config' do
command 'nagios3 --verify-config'
action :nothing
end
Notify multiple resources
template '/etc/chef/server.rb' do
source 'server.rb.erb'
owner 'root'
group 'root'
mode '0755'
notifies :restart, 'service[chef-solr]', :delayed
notifies :restart, 'service[chef-solr-indexer]', :delayed
notifies :restart, 'service[chef-server]', :delayed
end
Reload a service
template '/tmp/somefile' do
mode '0755'
source 'somefile.erb'
notifies :reload, 'service[apache]', :immediately
end
Restart a service when a template is modified
template '/etc/www/configures-apache.conf' do
notifies :restart, 'service[apache]', :immediately
end
Send notifications to multiple resources
To send notifications to multiple resources, just use multiple attributes. Multiple attributes will get sent to the notified resources in the order specified.
template '/etc/netatalk/netatalk.conf' do
notifies :restart, 'service[afpd]', :immediately
notifies :restart, 'service[cnid]', :immediately
end
service 'afpd'
service 'cnid'
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:
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.
Set an IP address using variables and a template
The following example shows how the template resource can be used in a recipe to combine settings stored in an attributes file, variables within a recipe, and a template to set the IP addresses that are used by the Nginx service. The attributes file contains the following:
default['nginx']['dir'] = '/etc/nginx'
The recipe then does the following to:
- Declare two variables at the beginning of the recipe, one for the remote IP address and the other for the authorized IP address
- Use the service resource to restart and reload the Nginx service
- Load a template named
authorized_ip.erb
from the/templates
directory that is used to set the IP address values based on the variables specified in the recipe
node.default['nginx']['remote_ip_var'] = 'remote_addr'
node.default['nginx']['authorized_ips'] = ['127.0.0.1/32']
service 'nginx' do
supports :status => true, :restart => true, :reload => true
end
template 'authorized_ip' do
path "#{node['nginx']['dir']}/authorized_ip"
source 'modules/authorized_ip.erb'
owner 'root'
group 'root'
mode '0755'
variables(
:remote_ip_var => node['nginx']['remote_ip_var'],
:authorized_ips => node['nginx']['authorized_ips']
)
notifies :reload, 'service[nginx]', :immediately
end
where the variables
property tells the template to use the variables
set at the beginning of the recipe and the source
property is used to
call a template file located in the cookbook’s /templates
directory.
The template file looks similar to:
geo $<%= @remote_ip_var %> $authorized_ip {
default no;
<% @authorized_ips.each do |ip| %>
<%= "#{ip} yes;" %>
<% end %>
}
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:
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.
Apply proxy settings consistently across a Chef organization
The following example shows how a template can be used to apply consistent proxy settings for all nodes of the same type:
template "#{node['matching_node']['dir']}/sites-available/site_proxy.conf" do
source 'site_proxy.matching_node.conf.erb'
owner 'root'
group 'root'
mode '0755'
variables(
:ssl_certificate => "#{node['matching_node']['dir']}/shared/certificates/site_proxy.crt",
:ssl_key => "#{node['matching_node']['dir']}/shared/certificates/site_proxy.key",
:listen_port => node['site']['matching_node_proxy']['listen_port'],
:server_name => node['site']['matching_node_proxy']['server_name'],
:fqdn => node['fqdn'],
:server_options => node[:site]['matching_node']['server']['options'],
:proxy_options => node[:site]['matching_node']['proxy']['options']
)
end
where matching_node
represents a type of node (like Nginx) and
site_proxy
represents the type of proxy being used for that type of
node (like Nexus).
Get template settings from a local file
The template resource can be used to render a template based on settings contained in a local file on disk or to get the settings from a template in a cookbook. Most of the time, the settings are retrieved from a template in a cookbook. The following example shows how the template resource can be used to retrieve these settings from a local file.
The following example is based on a few assumptions:
- The environment is a Ruby on Rails application that needs render a
file named
database.yml
- Information about the application—the user, their password, the server—is stored in a data bag on the Chef server
- The application is already deployed to the system and that only
requirement in this example is to render the
database.yml
file
The application source tree looks something like:
myapp/
-> config/
-> database.yml.erb
Note
There should not be a file named database.yml
(without the .erb
), as the database.yml
file is what will be rendered using the template resource.
The deployment of the app will end up in /srv
, so the full path to
this template would be something like
/srv/myapp/current/config/database.yml.erb
.
The content of the template itself may look like this:
<%= @rails_env %>:
adapter: <%= @adapter %>
host: <%= @host %>
database: <%= @database %>
username: <%= @username %>
password: <%= @password %>
encoding: 'utf8'
reconnect: true
The recipe will be similar to the following:
results = search(:node, "role:myapp_database_master AND chef_environment:#{node.chef_environment}")
db_master = results[0]
template '/srv/myapp/shared/database.yml' do
source '/srv/myapp/current/config/database.yml.erb'
local true
variables(
:rails_env => node.chef_environment,
:adapter => db_master['myapp']['db_adapter'],
:host => db_master['fqdn'],
:database => "myapp_#{node.chef_environment}",
:username => "myapp",
:password => "SUPERSECRET",
)
end
where:
- the
search
method in the Chef Infra Language is used to find the first node that is the database master (of which there should only be one) - the
:adapter
variable property may also require an attribute to have been set on a role, which then determines the correct adapter
The template will render similar to the following:
production:
adapter: mysql
host: domU-12-31-39-14-F1-C3.compute-1.internal
database: myapp_production
username: myapp
password: SUPERSECRET
encoding: utf8
reconnect: true
This example showed how to use the template resource to render a template based on settings contained in a local file. Some other issues that should be considered when using this type of approach include:
- Should the
database.yml
file be in a.gitignore
file? - How do developers run the application locally?
- Does this work with chef-solo?
Pass values from recipe to template
The following example shows how pass a value to a template using the
variables
property in the template resource. The template file is
similar to:
[tcpout]
defaultGroup = splunk_indexers_<%= node['splunk']['receiver_port'] %>
disabled=false
[tcpout:splunk_indexers_<%= node['splunk']['receiver_port'] %>]
server=<% @splunk_servers.map do |s| -%><%= s['ipaddress'] %>:<%= s['splunk']['receiver_port'] %> <% end.join(', ') -%>
<% @outputs_conf.each_pair do |name, value| -%>
<%= name %> = <%= value %>
<% end -%>
The recipe then uses the variables
attribute to find the values for
splunk_servers
and outputs_conf
, before passing them into the
template:
template "#{splunk_dir}/etc/system/local/outputs.conf" do
source 'outputs.conf.erb'
mode '0755'
variables :splunk_servers => splunk_servers, :outputs_conf => node['splunk']['outputs_conf']
notifies :restart, 'service[splunk]'
end
This example can be found in the client.rb
recipe and the
outputs.conf.erb
template files that are located in the chef-splunk
cookbook that is
maintained by Chef.
timezone resource
timezone resource pageUse the timezone resource to change the system timezone on Windows, Linux, and macOS hosts. Timezones are specified in tz database format, with a complete list of available TZ values for Linux and macOS here: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. On Windows systems run tzutil /l
for a complete list of valid timezones.
New in Chef Infra Client 14.6.
Syntax
The full syntax for all of the properties that are available to the timezone resource is:
timezone 'name' do
timezone String # default value: 'name' unless specified
action Symbol # defaults to :set if not specified
end
where:
timezone
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.timezone
is the property available to this resource.
Actions
The timezone resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:set
- Set the system timezone. (default)
Properties
The timezone resource has the following properties:
timezone
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the timezone value if it differs from the resource block’s name.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the timezone resource in recipes:
Set the timezone to UTC
timezone 'UTC'
Set the timezone to America/Los_Angeles with a friendly resource name on Linux/macOS
timezone "Set the host's timezone to America/Los_Angeles" do
timezone 'America/Los_Angeles'
end
Set the timezone to PST with a friendly resource name on Windows
timezone "Set the host's timezone to PST" do
timezone 'Pacific Standard time'
end
user resource
user resource pageUse the user resource to add users, update existing users, remove users, and to lock/unlock user passwords.
Note
System attributes are collected by Ohai at the start of every Chef Infra Client run. By design, the actions available to the user resource are processed after the start of a Chef Infra Client run. This means that system attributes added or modified by the user resource during a Chef Infra Client run must be reloaded before they can be available to Chef Infra Client. These system attributes can be reloaded in two ways: by picking up the values at the start of the (next) Chef Infra Client run or by using the ohai resource to reload the system attributes during the current Chef Infra Client run.
Syntax
A user resource block manages users on a node:
user 'a user' do
comment 'A random user'
uid 1234
gid 'groupname'
home '/home/random'
shell '/bin/bash'
password '$1$JJsvHslasdfjVEroftprNn4JHtDi'
end
The full syntax for all of the properties that are available to the user resource is:
user 'name' do
comment String
force true, false # see description
gid String, Integer
home String
iterations Integer
manage_home true, false
non_unique true, false
password String
salt String
shell String
system true, false
uid String, Integer
username String # defaults to 'name' if not specified
action Symbol # defaults to :create if not specified
end
where:
user
is the resourcename
is the name of the resource blockaction
identifies the steps Chef Infra Client will take to bring the node into the desired statecomment
,force
,gid
,home
,iterations
,manage_home
,non_unique
,password
,salt
,shell
,system
,uid
, andusername
are properties of this resource, with the Ruby type shown. See “Properties” section below for more information about all of the properties that may be used with this resource.
Actions
The user resource has the following actions:
:create
- (default) Create a user with given properties. If a user already exists (but does not match), update that user to match.
:lock
- Lock a user’s password.
:manage
- Manage an existing user. This action does nothing if the user does not exist.
:modify
- Modify an existing user. This action raises an exception if the user does not exist.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove a user.
:unlock
- Unlock a user’s password.
Properties
The user resource has the following properties:
comment
- Ruby Type: String
One (or more) comments about the user.
expire_date
- Ruby Type: String
(Linux) The date on which the user account will be disabled. The date is specified in YYYY-MM-DD format.
New in Chef Infra Client 18.0
force
- Ruby Type: true, false
Force the removal of a user. May be used only with the
:remove
action.Warning
Using this property may leave the system in an inconsistent state. For example, a user account will be removed even if the user is logged in. A user’s home directory will be removed, even if that directory is shared by multiple users.
gid
- Ruby Type: String, Integer
The identifier for the group. This property was previously named
group
and both continue to function.
home
- Ruby Type: String
The location of the home directory.
inactive
- Ruby Type: String, Integer
(Linux) The number of days after a password expires until the account is permanently disabled. A value of
0
disables the account as soon as the password has expired, and a value of-1
disables the feature.New in Chef Infra Client 18.0
iterations
- Ruby Type: Integer
macOS platform only. The number of iterations for a password with a SALTED-SHA512-PBKDF2 shadow hash.
manage_home
- Ruby Type: true, false
Manage a user’s home directory.
When used with the
:create
action, a user’s home directory is created based onHOME_DIR
. If the home directory is missing, it is created unlessCREATE_HOME
in/etc/login.defs
is set tono
. When created, a skeleton set of files and subdirectories are included within the home directory.When used with the
:modify
action, a user’s home directory is moved toHOME_DIR
. If the home directory is missing, it is created unlessCREATE_HOME
in/etc/login.defs
is set tono
. The contents of the user’s home directory are moved to the new location.
non_unique
- Ruby Type: true, false
Create a duplicate (non-unique) user account.
password
- Ruby Type: String
The password shadow hash
salt
- Ruby Type: String
A SALTED-SHA512-PBKDF2 hash.
shell
- Ruby Type: String
The login shell.
system
- Ruby Type: true, false
Create a system user. This property may be used with
useradd
as the provider to create a system user which passes the-r
flag touseradd
.
uid
- Ruby Type: String, Integer
The numeric user identifier.
username
- Ruby Type: String
The name of the user. Default value: the
name
of the resource block. See “Syntax” section above for more information.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the user resource in recipes:
Create a system user
user 'systemguy' do
comment 'system guy'
system true
shell '/bin/false'
end
Create a system user with a variable
The following example shows how to create a system user. In this
instance, the home
value is calculated and stored in a variable called
user_home
which sets the user’s home
attribute.
user_home = "/home/#{node['cookbook_name']['user']}"
user node['cookbook_name']['user'] do
gid node['cookbook_name']['group']
shell '/bin/bash'
home user_home
system true
action :create
end
Use SALTED-SHA512-PBKDF2 passwords
macOS 10.8 (and higher) calculates the password shadow hash using SALTED-SHA512-PBKDF2. The length of the shadow hash value is 128 bytes, the salt value is 32 bytes, and an integer specifies the number of iterations. The following code will calculate password shadow hashes for macOS 10.8 (and higher):
password = 'my_awesome_password'
salt = OpenSSL::Random.random_bytes(32)
iterations = 25000 # Any value above 20k should be fine.
shadow_hash = OpenSSL::PKCS5::pbkdf2_hmac(
password,
salt,
iterations,
128,
OpenSSL::Digest::SHA512.new
).unpack('H*').first
salt_value = salt.unpack('H*').first
Use the calculated password shadow hash with the user resource:
user 'my_awesome_user' do
password 'cbd1a....fc843' # Length: 256
salt 'bd1a....fc83' # Length: 64
iterations 25000
end
user_ulimit resource
user_ulimit resource pageUse the user_ulimit resource to create individual ulimit files that are installed into the /etc/security/limits.d/
directory.
New in Chef Infra Client 16.0.
Syntax
The full syntax for all of the properties that are available to the user_ulimit resource is:
user_ulimit 'name' do
as_hard_limit String, Integer
as_limit String, Integer
as_soft_limit String, Integer
core_hard_limit String, Integer
core_limit String, Integer
core_soft_limit String, Integer
cpu_hard_limit String, Integer
cpu_limit String, Integer
cpu_soft_limit String, Integer
filehandle_hard_limit String, Integer
filehandle_limit String, Integer
filehandle_soft_limit String, Integer
filename String
locks_limit String, Integer
maxlogins_hard_limit String, Integer
maxlogins_limit String, Integer
maxlogins_soft_limit String, Integer
memory_limit String, Integer
msgqueue_hard_limit String, Integer
msgqueue_limit String, Integer
msgqueue_soft_limit String, Integer
process_hard_limit String, Integer
process_limit String, Integer
process_soft_limit String, Integer
rss_hard_limit String, Integer
rss_limit String, Integer
rss_soft_limit String, Integer
rtprio_hard_limit String, Integer
rtprio_limit String, Integer
rtprio_soft_limit String, Integer
sigpending_hard_limit String, Integer
sigpending_limit String, Integer
sigpending_soft_limit String, Integer
stack_hard_limit String, Integer
stack_limit String, Integer
stack_soft_limit String, Integer
username String # default value: 'name' unless specified
virt_limit String, Integer
action Symbol # defaults to :create if not specified
end
where:
user_ulimit
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.as_hard_limit
,as_limit
,as_soft_limit
,core_hard_limit
,core_limit
,core_soft_limit
,cpu_hard_limit
,cpu_limit
,cpu_soft_limit
,filehandle_hard_limit
,filehandle_limit
,filehandle_soft_limit
,filename
,locks_limit
,maxlogins_hard_limit
,maxlogins_limit
,maxlogins_soft_limit
,memory_limit
,msgqueue_hard_limit
,msgqueue_limit
,msgqueue_soft_limit
,process_hard_limit
,process_limit
,process_soft_limit
,rss_hard_limit
,rss_limit
,rss_soft_limit
,rtprio_hard_limit
,rtprio_limit
,rtprio_soft_limit
,sigpending_hard_limit
,sigpending_limit
,sigpending_soft_limit
,stack_hard_limit
,stack_limit
,stack_soft_limit
,username
, andvirt_limit
are the properties available to this resource.
Actions
The user_ulimit resource has the following actions:
:create
- Create a ulimit configuration file. (default)
:delete
- Delete an existing ulimit configuration file.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The user_ulimit resource has the following properties:
as_hard_limit
- Ruby Type: String, Integer
as_limit
- Ruby Type: String, Integer
as_soft_limit
- Ruby Type: String, Integer
core_hard_limit
- Ruby Type: String, Integer
core_limit
- Ruby Type: String, Integer
core_soft_limit
- Ruby Type: String, Integer
cpu_hard_limit
- Ruby Type: String, Integer
cpu_limit
- Ruby Type: String, Integer
cpu_soft_limit
- Ruby Type: String, Integer
filehandle_hard_limit
- Ruby Type: String, Integer
filehandle_limit
- Ruby Type: String, Integer
filehandle_soft_limit
- Ruby Type: String, Integer
filename
- Ruby Type: String | Default Value:
lazy default
locks_limit
- Ruby Type: String, Integer
maxlogins_hard_limit
- Ruby Type: String, Integer
maxlogins_limit
- Ruby Type: String, Integer
maxlogins_soft_limit
- Ruby Type: String, Integer
memory_limit
- Ruby Type: String, Integer
msgqueue_hard_limit
- Ruby Type: String, Integer
msgqueue_limit
- Ruby Type: String, Integer
msgqueue_soft_limit
- Ruby Type: String, Integer
process_hard_limit
- Ruby Type: String, Integer
process_limit
- Ruby Type: String, Integer
process_soft_limit
- Ruby Type: String, Integer
rss_hard_limit
- Ruby Type: String, Integer
rss_limit
- Ruby Type: String, Integer
rss_soft_limit
- Ruby Type: String, Integer
rtprio_hard_limit
- Ruby Type: String, Integer
rtprio_limit
- Ruby Type: String, Integer
rtprio_soft_limit
- Ruby Type: String, Integer
sigpending_hard_limit
- Ruby Type: String, Integer
sigpending_limit
- Ruby Type: String, Integer
sigpending_soft_limit
- Ruby Type: String, Integer
stack_hard_limit
- Ruby Type: String, Integer
stack_limit
- Ruby Type: String, Integer
stack_soft_limit
- Ruby Type: String, Integer
username
- Ruby Type: String | Default Value:
The resource block's name
virt_limit
- Ruby Type: String, Integer
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the user_ulimit resource in recipes:
Set filehandle limit for the tomcat user:
user_ulimit 'tomcat' do
filehandle_limit 8192
end
Specify a username that differs from the name given to the resource block:
user_ulimit 'Bump filehandle limits for tomcat user' do
username 'tomcat'
filehandle_limit 8192
end
Set filehandle limit for the tomcat user with a non-default filename:
user_ulimit 'tomcat' do
filehandle_limit 8192
filename 'tomcat_filehandle_limits.conf'
end
windows_ad_join resource
windows_ad_join resource pageUse the windows_ad_join resource to join a Windows Active Directory domain.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the windows_ad_join resource is:
windows_ad_join 'name' do
domain_name String # default value: 'name' unless specified
domain_password String
domain_user String
new_hostname String
ou_path String
reboot Symbol # default value: :immediate
reboot_delay Integer # default value: 0
workgroup_name String
action Symbol # defaults to :join if not specified
end
where:
windows_ad_join
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.domain_name
,domain_password
,domain_user
,new_hostname
,ou_path
,reboot
,reboot_delay
, andworkgroup_name
are the properties available to this resource.
Actions
The windows_ad_join resource has the following actions:
:join
- Join the Active Directory domain. (default)
:leave
- Leave an Active Directory domain and re-join a workgroup.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The windows_ad_join resource has the following properties:
domain_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the FQDN of the Active Directory domain to join if it differs from the resource block’s name.
domain_password
- Ruby Type: String |
REQUIRED
The password for the domain user. Note that this resource is set to hide sensitive information by default.
domain_user
- Ruby Type: String |
REQUIRED
The domain user that will be used to join the domain.
new_hostname
- Ruby Type: String
Specifies a new hostname for the computer in the new domain.
New in Chef Client 14.5
ou_path
- Ruby Type: String
The path to the Organizational Unit where the host will be placed.
reboot
- Ruby Type: Symbol | Default Value:
:immediate
Allowed Values::delayed, :immediate, :never, :reboot_now, :request_reboot
Controls the system reboot behavior post domain joining. Reboot immediately, after the Chef Infra Client run completes, or never. Note that a reboot is necessary for changes to take effect.
reboot_delay
- Ruby Type: Integer | Default Value:
0
The amount of time (in minutes) to delay a reboot request.
New in Chef Infra Client 16.5
workgroup_name
- Ruby Type: String
Specifies the name of a workgroup to which the computer is added to when it is removed from the domain. The default value is WORKGROUP. This property is only applicable to the :leave action.
New in Chef Infra Client 15.4
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_ad_join resource in recipes:
Join a domain
windows_ad_join 'ad.example.org' do
domain_user 'nick'
domain_password 'p@ssw0rd1'
end
Join a domain, as win-workstation
windows_ad_join 'ad.example.org' do
domain_user 'nick'
domain_password 'p@ssw0rd1'
new_hostname 'win-workstation'
end
Leave the current domain and re-join the local
workgroup
windows_ad_join 'Leave domain' do
action :leave
workgroup 'local'
end
windows_audit_policy resource
windows_audit_policy resource pageUse the windows_audit_policy resource to configure system level and per-user Windows advanced audit policy settings.
New in Chef Infra Client 16.2.
Syntax
The full syntax for all of the properties that are available to the windows_audit_policy resource is:
windows_audit_policy 'name' do
audit_base_directories true, false
audit_base_objects true, false
crash_on_audit_fail true, false
exclude_user String
failure true, false
full_privilege_auditing true, false
include_user String
subcategory String, Array
success true, false
action Symbol # defaults to :set if not specified
end
where:
windows_audit_policy
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.audit_base_directories
,audit_base_objects
,crash_on_audit_fail
,exclude_user
,failure
,full_privilege_auditing
,include_user
,subcategory
, andsuccess
are the properties available to this resource.
Actions
The windows_audit_policy resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:set
- Configure an audit policy. (default)
Properties
The windows_audit_policy resource has the following properties:
audit_base_directories
- Ruby Type: true, false
Setting this audit policy option to true will force the system to assign a System Access Control List to named objects to enable auditing of container objects such as directories.
audit_base_objects
- Ruby Type: true, false
Setting this audit policy option to true will force the system to assign a System Access Control List to named objects to enable auditing of base objects such as mutexes.
crash_on_audit_fail
- Ruby Type: true, false
Setting this audit policy option to true will cause the system to crash if the auditing system is unable to log events.
exclude_user
- Ruby Type: String
The audit policy specified by the category or subcategory is applied per-user if specified. When a user is specified, exclude user. Include and exclude cannot be used at the same time.
failure
- Ruby Type: true, false
Specify failure auditing. By setting this property to true the resource will enable failure for the category or sub category. Success is the default and is applied if neither success nor failure are specified.
full_privilege_auditing
- Ruby Type: true, false
Setting this audit policy option to true will force the audit of all privilege changes except SeAuditPrivilege. Setting this property may cause the logs to fill up more quickly.
include_user
- Ruby Type: String
The audit policy specified by the category or subcategory is applied per-user if specified. When a user is specified, include user. Include and exclude cannot be used at the same time.
subcategory
- Ruby Type: String, Array
The audit policy subcategory, specified by GUID or name. Applied system-wide if no user is specified.
success
- Ruby Type: true, false
Specify success auditing. By setting this property to true the resource will enable success for the category or sub category. Success is the default and is applied if neither success nor failure are specified.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_audit_policy resource in recipes:
Set Logon and Logoff policy to “Success and Failure”:
windows_audit_policy "Set Audit Policy for 'Logon and Logoff' actions to 'Success and Failure'" do
subcategory %w(Logon Logoff)
success true
failure true
action :set
end
Set Credential Validation policy to “Success”:
windows_audit_policy "Set Audit Policy for 'Credential Validation' actions to 'Success'" do
subcategory 'Credential Validation'
success true
failure false
action :set
end
Enable CrashOnAuditFail option:
windows_audit_policy 'Enable CrashOnAuditFail option' do
crash_on_audit_fail true
action :set
end
windows_auto_run resource
windows_auto_run resource pageUse the windows_auto_run resource to set applications to run at login.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the windows_auto_run resource is:
windows_auto_run 'name' do
args String
path String
program_name String # default value: 'name' unless specified
root Symbol # default value: :machine
action Symbol # defaults to :create if not specified
end
where:
windows_auto_run
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.args
,path
,program_name
, androot
are the properties available to this resource.
Actions
The windows_auto_run resource has the following actions:
:create
- Create an item to be run at login. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove an item that was previously configured to run at login.
Properties
The windows_auto_run resource has the following properties:
args
- Ruby Type: String
Any arguments to be used with the program.
path
- Ruby Type: String
The path to the program that will run at login.
program_name
- Ruby Type: String | Default Value:
The resource block's name
The name of the program to run at login if it differs from the resource block’s name.
root
- Ruby Type: Symbol | Default Value:
:machine
Allowed Values::machine, :user
The registry root key to put the entry under.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_auto_run resource in recipes:
Run BGInfo at login
windows_auto_run 'BGINFO' do
program 'C:/Sysinternals/bginfo.exe'
args ''C:/Sysinternals/Config.bgi' /NOLICPROMPT /TIMER:0'
action :create
end
windows_certificate resource
windows_certificate resource pageUse the windows_certificate resource to install a certificate into the Windows certificate store from a file. The resource grants read-only access to the private key for designated accounts. Due to current limitations in WinRM, installing certificates remotely may not work if the operation requires a user profile. Operations on the local machine store should still work.
New in Chef Infra Client 14.7.
Syntax
The full syntax for all of the properties that are available to the windows_certificate resource is:
windows_certificate 'name' do
exportable true, false # default value: false
output_path String
pfx_password String
private_key_acl Array
source String # default value: 'name' unless specified
store_name String # default value: "MY"
user_store true, false # default value: false
action Symbol # defaults to :create if not specified
end
where:
windows_certificate
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.exportable
,output_path
,pfx_password
,private_key_acl
,source
,store_name
, anduser_store
are the properties available to this resource.
Actions
The windows_certificate resource has the following actions:
:acl_add
- Adds read-only entries to a certificate’s private key ACL.
:create
- Creates or updates a certificate. (default)
:delete
- Deletes a certificate.
:fetch
- Fetches a certificate.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:verify
- Verifies a certificate and logs the result.
Properties
The windows_certificate resource has the following properties:
exportable
- Ruby Type: true, false | Default Value:
false
Ensure that imported pfx certificate is exportable. Please provide ’true’ if you want the certificate to be exportable.
New in Chef Infra Client 16.8
output_path
- Ruby Type: String
A path on the node where a certificate object (PFX, PEM, CER, KEY, etc) can be exported to.
New in Chef Infra Client 17.0
pfx_password
- Ruby Type: String
The password to access the object with if it is a PFX file.
private_key_acl
- Ruby Type: Array
An array of ‘domain\account’ entries to be granted read-only access to the certificate’s private key. Not idempotent.
source
- Ruby Type: String | Default Value:
The resource block's name
The source file (for
create
andacl_add
), thumbprint (fordelete
,export
, andacl_add
), or subject (fordelete
orexport
) if it differs from the resource block’s name.
store_name
- Ruby Type: String | Default Value:
MY
Allowed Values:"AUTHROOT", "CA", "CLIENTAUTHISSUER", "DISALLOWED", "MY", "REMOTE DESKTOP", "ROOT", "SMARTCARDROOT", "TRUST", "TRUSTEDDEVICES", "TRUSTEDPEOPLE", "TRUSTEDPUBLISHER", "TrustedPublisher", "WEBHOSTING"
The certificate store to manipulate.
user_store
- Ruby Type: true, false | Default Value:
false
Use the
CurrentUser
store instead of the defaultLocalMachine
store.Note
Prior to chef-client. 16.10 this property was ignored.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_certificate resource in recipes:
Add PFX cert to local machine personal store and grant accounts read-only access to private key
windows_certificate 'c:/test/mycert.pfx' do
pfx_password 'password'
private_key_acl ["acme\fred", "pc\jane"]
end
Add cert to trusted intermediate store
windows_certificate 'c:/test/mycert.cer' do
store_name 'CA'
end
Remove all certificates matching the subject
windows_certificate 'me.acme.com' do
action :delete
end
windows_defender resource
windows_defender resource pageUse the windows_defender resource to enable or disable the Microsoft Windows Defender service.
New in Chef Infra Client 17.3.
Syntax
The full syntax for all of the properties that are available to the windows_defender resource is:
windows_defender 'name' do
intrusion_protection_system true, false # default value: true
lock_ui true, false # default value: false
realtime_protection true, false # default value: true
scan_archives true, false # default value: true
scan_email true, false # default value: false
scan_mapped_drives true, false # default value: true
scan_network_files true, false # default value: false
scan_removable_drives true, false # default value: false
scan_scripts true, false # default value: false
action Symbol # defaults to :enable if not specified
end
where:
windows_defender
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.intrusion_protection_system
,lock_ui
,realtime_protection
,scan_archives
,scan_email
,scan_mapped_drives
,scan_network_files
,scan_removable_drives
, andscan_scripts
are the properties available to this resource.
Actions
The windows_defender resource has the following actions:
:disable
- Disable Windows Defender.
:enable
- Enable and configure Windows Defender. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The windows_defender resource has the following properties:
intrusion_protection_system
- Ruby Type: true, false | Default Value:
true
Enable network protection against exploitation of known vulnerabilities.
lock_ui
- Ruby Type: true, false | Default Value:
false
Lock the UI to prevent users from changing Windows Defender settings.
realtime_protection
- Ruby Type: true, false | Default Value:
true
Enable realtime scanning of downloaded files and attachments.
scan_archives
- Ruby Type: true, false | Default Value:
true
Scan file archives such as .zip or .gz archives.
scan_email
- Ruby Type: true, false | Default Value:
false
Scan e-mails for malware.
scan_mapped_drives
- Ruby Type: true, false | Default Value:
true
Scan files on mapped network drives.
scan_network_files
- Ruby Type: true, false | Default Value:
false
Scan files on a network.
scan_removable_drives
- Ruby Type: true, false | Default Value:
false
Scan content of removable drives.
scan_scripts
- Ruby Type: true, false | Default Value:
false
Scan scripts in malware scans.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_defender resource in recipes:
Configure Windows Defender AV settings:
windows_defender 'Configure Defender' do
realtime_protection true
intrusion_protection_system true
lock_ui true
scan_archives true
scan_scripts true
scan_email true
scan_removable_drives true
scan_network_files false
scan_mapped_drives false
action :enable
end
Disable Windows Defender AV:
windows_defender 'Disable Defender' do
action :disable
end
windows_defender_exclusion resource
windows_defender_exclusion resource pageUse the windows_defender_exclusion resource to exclude paths, processes, or file types from Windows Defender realtime protection scanning.
New in Chef Infra Client 17.3.
Syntax
The full syntax for all of the properties that are available to the windows_defender_exclusion resource is:
windows_defender_exclusion 'name' do
extensions String, Array # default value: []
paths String, Array # default value: []
process_paths String, Array # default value: []
action Symbol # defaults to :add if not specified
end
where:
windows_defender_exclusion
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.extensions
,paths
, andprocess_paths
are the properties available to this resource.
Actions
The windows_defender_exclusion resource has the following actions:
:add
- Add an exclusion to Windows Defender. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove an exclusion to Windows Defender.
Properties
The windows_defender_exclusion resource has the following properties:
extensions
- Ruby Type: String, Array | Default Value:
[]
File extensions to exclude from scanning.
paths
- Ruby Type: String, Array | Default Value:
[]
File or directory paths to exclude from scanning.
process_paths
- Ruby Type: String, Array | Default Value:
[]
Paths to executables to exclude from scanning.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_defender_exclusion resource in recipes:
Add excluded items to Windows Defender scans:
windows_defender_exclusion 'Add to things to be excluded from scanning' do
paths 'c:\foo\bar, d:\bar\baz'
extensions 'png, foo, ppt, doc'
process_paths 'c:\windows\system32'
action :add
end
Remove excluded items from Windows Defender scans:
windows_defender_exclusion 'Remove things from the list to be excluded' do
process_paths 'c:\windows\system32'
action :remove
end
windows_dfs_folder resource
windows_dfs_folder resource pageUse the windows_dfs_folder resource to creates a folder within DFS as many levels deep as required.
New in Chef Infra Client 15.0.
Syntax
The full syntax for all of the properties that are available to the windows_dfs_folder resource is:
windows_dfs_folder 'name' do
description String
folder_path String # default value: 'name' unless specified
namespace_name String
target_path String
action Symbol # defaults to :create if not specified
end
where:
windows_dfs_folder
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.description
,folder_path
,namespace_name
, andtarget_path
are the properties available to this resource.
Actions
The windows_dfs_folder resource has the following actions:
:create
- Creates the folder in dfs namespace. (default)
:delete
- Deletes the folder in the dfs namespace.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The windows_dfs_folder resource has the following properties:
description
- Ruby Type: String
Description for the share.
folder_path
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the path of the dfs folder if it differs from the resource block’s name.
namespace_name
- Ruby Type: String |
REQUIRED
The namespace this should be created within.
target_path
- Ruby Type: String
The target that this path will connect you to.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
This resource does not have any examples.
windows_dfs_namespace resource
windows_dfs_namespace resource pageUse the windows_dfs_namespace resource to creates a share and DFS namespace on a Windows server.
New in Chef Infra Client 15.0.
Syntax
The full syntax for all of the properties that are available to the windows_dfs_namespace resource is:
windows_dfs_namespace 'name' do
change_users Array # default value: []
description String
full_users Array # default value: ["BUILTIN\\administrators"]
namespace_name String # default value: 'name' unless specified
read_users Array # default value: []
root String # default value: "C:\\DFSRoots"
action Symbol # defaults to :create if not specified
end
where:
windows_dfs_namespace
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.change_users
,description
,full_users
,namespace_name
,read_users
, androot
are the properties available to this resource.
Actions
The windows_dfs_namespace resource has the following actions:
:create
- Creates the dfs namespace on the server. (default)
:delete
- Deletes a DFS Namespace including the directory on disk.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The windows_dfs_namespace resource has the following properties:
change_users
- Ruby Type: Array | Default Value:
[]
Determines which users should have change access to the share.
description
- Ruby Type: String |
REQUIRED
Description of the share.
full_users
- Ruby Type: Array | Default Value:
["BUILTIN\\administrators"]
Determines which users should have full access to the share.
namespace_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the dfs namespace if it differs from the resource block’s name.
read_users
- Ruby Type: Array | Default Value:
[]
Determines which users should have read access to the share.
root
- Ruby Type: String | Default Value:
C:\DFSRoots
The root from which to create the DFS tree. Defaults to C:\DFSRoots.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
This resource does not have any examples.
windows_dfs_server resource
windows_dfs_server resource pageUse the windows_dfs_server resource to set system-wide DFS settings.
New in Chef Infra Client 15.0.
Syntax
The full syntax for all of the properties that are available to the windows_dfs_server resource is:
windows_dfs_server 'name' do
enable_site_costed_referrals true, false # default value: false
ldap_timeout_secs Integer # default value: 30
prefer_login_dc true, false # default value: false
sync_interval_secs Integer # default value: 3600
use_fqdn true, false # default value: false
action Symbol # defaults to :configure if not specified
end
where:
windows_dfs_server
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.enable_site_costed_referrals
,ldap_timeout_secs
,prefer_login_dc
,sync_interval_secs
, anduse_fqdn
are the properties available to this resource.
Actions
The windows_dfs_server resource has the following actions:
:configure
- Configure DFS settings (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The windows_dfs_server resource has the following properties:
enable_site_costed_referrals
- Ruby Type: true, false | Default Value:
false
ldap_timeout_secs
- Ruby Type: Integer | Default Value:
30
prefer_login_dc
- Ruby Type: true, false | Default Value:
false
sync_interval_secs
- Ruby Type: Integer | Default Value:
3600
use_fqdn
- Ruby Type: true, false | Default Value:
false
Indicates whether a DFS namespace server uses FQDNs in referrals. If this property is set to true, the server uses FQDNs in referrals. If this property is set to false then the server uses NetBIOS names.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
This resource does not have any examples.
windows_dns_record resource
windows_dns_record resource pageThe windows_dns_record resource creates a DNS record for the given domain.
New in Chef Infra Client 15.0.
Syntax
The full syntax for all of the properties that are available to the windows_dns_record resource is:
windows_dns_record 'name' do
dns_server String # default value: "localhost"
record_name String # default value: 'name' unless specified
record_type String # default value: "ARecord"
target String
zone String
action Symbol # defaults to :create if not specified
end
where:
windows_dns_record
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.dns_server
,record_name
,record_type
,target
, andzone
are the properties available to this resource.
Actions
The windows_dns_record resource has the following actions:
:create
- Creates and updates the DNS entry. (default)
:delete
- Deletes a DNS entry.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The windows_dns_record resource has the following properties:
dns_server
- Ruby Type: String | Default Value:
localhost
The name of the DNS server on which to create the record.
New in Chef Infra Client 16.3
record_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the dns record name if it differs from the resource block’s name.
record_type
- Ruby Type: String | Default Value:
ARecord
Allowed Values:"ARecord", "CNAME", "PTR"
The type of record to create, can be either ARecord, CNAME or PTR.
target
- Ruby Type: String |
REQUIRED
The target for the record.
zone
- Ruby Type: String |
REQUIRED
The zone to create the record in.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
This resource does not have any examples.
windows_dns_zone resource
windows_dns_zone resource pageThe windows_dns_zone resource creates an Active Directory Integrated DNS Zone on the local server.
New in Chef Infra Client 15.0.
Syntax
The full syntax for all of the properties that are available to the windows_dns_zone resource is:
windows_dns_zone 'name' do
replication_scope String # default value: "Domain"
server_type String # default value: "Domain"
zone_name String # default value: 'name' unless specified
action Symbol # defaults to :create if not specified
end
where:
windows_dns_zone
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.replication_scope
,server_type
, andzone_name
are the properties available to this resource.
Actions
The windows_dns_zone resource has the following actions:
:create
- Creates and updates a DNS Zone. (default)
:delete
- Deletes a DNS Zone.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The windows_dns_zone resource has the following properties:
replication_scope
- Ruby Type: String | Default Value:
Domain
The replication scope for the zone, required if server_type set to ‘Domain’.
server_type
- Ruby Type: String | Default Value:
Domain
Allowed Values:"Domain", "Standalone"
The type of DNS server, Domain or Standalone.
zone_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the dns zone name if it differs from the resource block’s name.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
This resource does not have any examples.
windows_env resource
windows_env resource pageUse the windows_env resource to manage environment keys in Microsoft Windows. After an environment key is set, Microsoft Windows must be restarted before the environment key will be available to the Task Scheduler.
This resource was previously called the env resource; its name was updated in Chef Infra Client 14.0 to reflect the fact that only Windows is supported. Existing cookbooks using env
will continue to function, but should be updated to use the new name.
Note
On UNIX-based systems, the best way to manipulate environment keys is with the ENV
variable in Ruby; however, this approach does not have the same permanent effect as using the windows_env resource.
Syntax
The full syntax for all of the properties that are available to the windows_env resource is:
windows_env 'name' do
delim String, false
key_name String # default value: 'name' unless specified
user String # default value: "<System>"
value String
action Symbol # defaults to :create if not specified
end
where:
windows_env
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.delim
,key_name
,user
, andvalue
are the properties available to this resource.
Actions
The windows_env resource has the following actions:
:create
- Create an environment variable. If an environment variable already exists (but does not match), update that environment variable to match. (default)
:delete
- Delete an environment variable.
:modify
- Modify an existing environment variable. This prepends the new value to the existing value, using the delimiter specified by the
delim
property. :nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The windows_env resource has the following properties:
delim
- Ruby Type: String, false
The delimiter that is used to separate multiple values for a single key.
key_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the name of the key that is to be created, deleted, or modified if it differs from the resource block’s name.
user
- Ruby Type: String | Default Value:
<System>
value
- Ruby Type: String |
REQUIRED
The value of the environmental variable to set.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_env resource in recipes:
Set an environment variable:
windows_env 'ComSpec' do
value 'C:\Windows\system32\cmd.exe'
end
windows_feature resource
windows_feature resource pageUse the windows_feature resource to add, remove or entirely delete Windows features and roles. This resource calls the windows_feature_dism or windows_feature_powershell resources depending on the specified installation method, and defaults to DISM, which is available on both Workstation and Server editions of Windows.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the windows_feature resource is:
windows_feature 'name' do
all true, false # default value: false
feature_name Array, String # default value: 'name' unless specified
install_method Symbol # default value: :windows_feature_dism
management_tools true, false # default value: false
source String
timeout Integer # default value: 600
action Symbol # defaults to :install if not specified
end
where:
windows_feature
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.all
,feature_name
,install_method
,management_tools
,source
, andtimeout
are the properties available to this resource.
Actions
The windows_feature resource has the following actions:
:delete
- Remove a Windows role or feature from the image.
:install
- Install a Windows role or feature. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove a Windows role or feature.
Properties
The windows_feature resource has the following properties:
all
- Ruby Type: true, false | Default Value:
false
Install all sub-features.
feature_name
- Ruby Type: Array, String | Default Value:
The resource block's name
The name of the feature(s) or role(s) to install if they differ from the resource block’s name. The same feature may have different names depending on the underlying installation method being used (ie DHCPServer vs DHCP; DNS-Server-Full-Role vs DNS).
install_method
- Ruby Type: Symbol | Default Value:
:windows_feature_dism
Allowed Values::windows_feature_dism, :windows_feature_powershell, :windows_feature_servermanagercmd
The underlying installation method to use for feature installation. Specify
:windows_feature_dism
for DISM or:windows_feature_powershell
for PowerShell.
management_tools
- Ruby Type: true, false | Default Value:
false
Install all applicable management tools for the roles, role services, or features (PowerShell-only).
source
- Ruby Type: String
Specify a local repository for the feature install.
timeout
- Ruby Type: Integer | Default Value:
600
Specifies a timeout (in seconds) for the feature installation.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_feature resource in recipes:
Install the DHCP Server feature:
windows_feature 'DHCPServer' do
action :install
end
Install the .Net 3.5.1 feature using repository files on DVD:
windows_feature "NetFx3" do
action :install
source 'd:\sources\sxs'
end
Remove Telnet Server and Client features:
windows_feature %w(TelnetServer TelnetClient) do
action :remove
end
Add the SMTP Server feature using the PowerShell provider:
windows_feature 'smtp-server' do
action :install
all true
install_method :windows_feature_powershell
end
Install multiple features using one resource with the PowerShell provider:
windows_feature %w(Web-Asp-Net45 Web-Net-Ext45) do
action :install
install_method :windows_feature_powershell
end
Install the Network Policy and Access Service feature, including the management tools:
windows_feature 'NPAS' do
action :install
management_tools true
install_method :windows_feature_powershell
end
windows_feature_dism resource
windows_feature_dism resource pageUse the windows_feature_dism resource to add, remove, or entirely delete Windows features and roles using DISM.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the windows_feature_dism resource is:
windows_feature_dism 'name' do
all true, false # default value: false
feature_name Array, String # default value: 'name' unless specified
source String
timeout Integer # default value: 600
action Symbol # defaults to :install if not specified
end
where:
windows_feature_dism
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.all
,feature_name
,source
, andtimeout
are the properties available to this resource.
Actions
The windows_feature_dism resource has the following actions:
:delete
- Remove a Windows role or feature from the image using DISM.
:install
- Install a Windows role/feature using DISM. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove a Windows role or feature using DISM.
Properties
The windows_feature_dism resource has the following properties:
all
- Ruby Type: true, false | Default Value:
false
Install all sub-features. When set to
true
, this is the equivalent of specifying the/All
switch todism.exe
feature_name
- Ruby Type: Array, String | Default Value:
The resource block's name
The name of the feature(s) or role(s) to install if they differ from the resource name.
source
- Ruby Type: String
Specify a local repository for the feature install.
timeout
- Ruby Type: Integer | Default Value:
600
Specifies a timeout (in seconds) for the feature installation.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_feature_dism resource in recipes:
Installing the TelnetClient service:
windows_feature_dism "TelnetClient"
Installing two features by using an array:
windows_feature_dism %w(TelnetClient TFTP)
windows_feature_powershell resource
windows_feature_powershell resource pageUse the windows_feature_powershell resource to add, remove, or entirely delete Windows features and roles using PowerShell. This resource offers significant speed benefits over the windows_feature_dism resource, but requires installation of the Remote Server Administration Tools on non-server releases of Windows.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the windows_feature_powershell resource is:
windows_feature_powershell 'name' do
all true, false # default value: false
feature_name Array, String # default value: 'name' unless specified
management_tools true, false # default value: false
source String
timeout Integer # default value: 600
action Symbol # defaults to :install if not specified
end
where:
windows_feature_powershell
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.all
,feature_name
,management_tools
,source
, andtimeout
are the properties available to this resource.
Actions
The windows_feature_powershell resource has the following actions:
:delete
- Delete a Windows role or feature from the image using PowerShell.
:install
- Install a Windows role or feature using PowerShell. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove a Windows role or feature using PowerShell.
Properties
The windows_feature_powershell resource has the following properties:
all
- Ruby Type: true, false | Default Value:
false
Install all subfeatures. When set to
true
, this is the equivalent of specifying the-InstallAllSubFeatures
switch withAdd-WindowsFeature
.
feature_name
- Ruby Type: Array, String | Default Value:
The resource block's name
The name of the feature(s) or role(s) to install if they differ from the resource block’s name.
management_tools
- Ruby Type: true, false | Default Value:
false
Install all applicable management tools for the roles, role services, or features.
source
- Ruby Type: String
Specify a local repository for the feature install.
timeout
- Ruby Type: Integer | Default Value:
600
Specifies a timeout (in seconds) for the feature installation.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_feature_powershell resource in recipes:
Add the SMTP Server feature:
windows_feature_powershell "smtp-server" do
action :install
all true
end
Install multiple features using one resource:
windows_feature_powershell ['Web-Asp-Net45', 'Web-Net-Ext45'] do
action :install
end
Install the Network Policy and Access Service feature:
windows_feature_powershell 'NPAS' do
action :install
management_tools true
end
windows_firewall_profile resource
windows_firewall_profile resource pageUse the windows_firewall_profile resource to enable, disable, and configure the Windows firewall.
New in Chef Infra Client 16.3.
Syntax
The full syntax for all of the properties that are available to the windows_firewall_profile resource is:
windows_firewall_profile 'name' do
allow_inbound_rules true, false, String
allow_local_firewall_rules true, false, String
allow_local_ipsec_rules true, false, String
allow_unicast_response true, false, String
allow_user_apps true, false, String
allow_user_ports true, false, String
default_inbound_action String
default_outbound_action String
display_notification true, false, String
profile String # default value: 'name' unless specified
action Symbol # defaults to :enable if not specified
end
where:
windows_firewall_profile
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.allow_inbound_rules
,allow_local_firewall_rules
,allow_local_ipsec_rules
,allow_unicast_response
,allow_user_apps
,allow_user_ports
,default_inbound_action
,default_outbound_action
,display_notification
, andprofile
are the properties available to this resource.
Actions
The windows_firewall_profile resource has the following actions:
:disable
- Disable a Windows Firewall profile.
:enable
- Enable and optionally configure a Windows Firewall profile. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The windows_firewall_profile resource has the following properties:
allow_inbound_rules
- Ruby Type: true, false, StringAllowed Values:
true, false, "NotConfigured"
Allow users to set inbound firewall rules
allow_local_firewall_rules
- Ruby Type: true, false, StringAllowed Values:
true, false, "NotConfigured"
Merges inbound firewall rules into the policy
allow_local_ipsec_rules
- Ruby Type: true, false, StringAllowed Values:
true, false, "NotConfigured"
Allow users to manage local connection security rules
allow_unicast_response
- Ruby Type: true, false, StringAllowed Values:
true, false, "NotConfigured"
Allow unicast responses to multicast and broadcast messages
allow_user_apps
- Ruby Type: true, false, StringAllowed Values:
true, false, "NotConfigured"
Allow user applications to manage firewall
allow_user_ports
- Ruby Type: true, false, StringAllowed Values:
true, false, "NotConfigured"
Allow users to manage firewall port rules
default_inbound_action
- Ruby Type: StringAllowed Values:
"Allow", "Block", "NotConfigured"
Set the default policy for inbound network traffic
default_outbound_action
- Ruby Type: StringAllowed Values:
"Allow", "Block", "NotConfigured"
Set the default policy for outbound network traffic
display_notification
- Ruby Type: true, false, StringAllowed Values:
true, false, "NotConfigured"
Display a notification when firewall blocks certain activity
profile
- Ruby Type: String | Default Value:
The resource block's name
Allowed Values:"Domain", "Private", "Public"
Set the Windows Profile being configured
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_firewall_profile resource in recipes:
Enable and Configure the Private Profile of the Windows Profile:
windows_firewall_profile 'Private' do
default_inbound_action 'Block'
default_outbound_action 'Allow'
allow_inbound_rules true
display_notification false
action :enable
end
Enable and Configure the Public Profile of the Windows Firewall:
windows_firewall_profile 'Public' do
default_inbound_action 'Block'
default_outbound_action 'Allow'
allow_inbound_rules false
display_notification false
action :enable
end
Disable the Domain Profile of the Windows Firewall:
windows_firewall_profile 'Disable the Domain Profile of the Windows Firewall' do
profile 'Domain'
action :disable
end
windows_firewall_rule resource
windows_firewall_rule resource pageUse the windows_firewall_rule resource to create, change or remove Windows firewall rules.
New in Chef Infra Client 14.7.
Syntax
The full syntax for all of the properties that are available to the windows_firewall_rule resource is:
windows_firewall_rule 'name' do
description String
direction Symbol, String # default value: :inbound
displayname String # default value: The rule_name property value.
enabled true, false # default value: true
firewall_action Symbol, String # default value: :allow
group String
icmp_type String, Integer # default value: "Any"
interface_type Symbol, String # default value: :any
local_address String
local_port String, Integer, Array
profile Symbol, String, Array # default value: :any
program String
protocol String # default value: "TCP"
remote_address String, Array
remote_port String, Integer, Array
rule_name String # default value: 'name' unless specified
service String
action Symbol # defaults to :create if not specified
end
where:
windows_firewall_rule
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.description
,direction
,displayname
,enabled
,firewall_action
,group
,icmp_type
,interface_type
,local_address
,local_port
,profile
,program
,protocol
,remote_address
,remote_port
,rule_name
, andservice
are the properties available to this resource.
Actions
The windows_firewall_rule resource has the following actions:
:create
- Create a Windows firewall entry. (default)
:delete
- Delete an existing Windows firewall entry.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The windows_firewall_rule resource has the following properties:
description
- Ruby Type: String
The description to assign to the firewall rule.
direction
- Ruby Type: Symbol, String | Default Value:
:inbound
Allowed Values::inbound, :outbound
The direction of the firewall rule. Direction means either inbound or outbound traffic.
displayname
- Ruby Type: String | Default Value:
The rule_name property value.
The displayname to assign to the firewall rule.
New in Chef Infra Client 16.0
enabled
- Ruby Type: true, false | Default Value:
true
Whether or not to enable the firewall rule.
firewall_action
- Ruby Type: Symbol, String | Default Value:
:allow
Allowed Values::allow, :block, :notconfigured
The action of the firewall rule.
group
- Ruby Type: String
Specifies that only matching firewall rules of the indicated group association are copied.
New in Chef Infra Client 16.0
icmp_type
- Ruby Type: String, Integer | Default Value:
Any
Specifies the ICMP Type parameter for using a protocol starting with ICMP
New in Chef Infra Client 16.0
interface_type
- Ruby Type: Symbol, String | Default Value:
:any
Allowed Values::any, :remoteaccess, :wired, :wireless
The interface type the firewall rule applies to.
local_address
- Ruby Type: String
The local address the firewall rule applies to.
local_port
- Ruby Type: String, Integer, Array
The local port the firewall rule applies to.
profile
- Ruby Type: Symbol, String, Array | Default Value:
:any
The profile the firewall rule applies to.
program
- Ruby Type: String
The program the firewall rule applies to.
protocol
- Ruby Type: String | Default Value:
TCP
The protocol the firewall rule applies to.
remote_address
- Ruby Type: String, Array
The remote address(es) the firewall rule applies to.
remote_port
- Ruby Type: String, Integer, Array
The remote port the firewall rule applies to.
rule_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the name of the firewall rule to assign if it differs from the resource block’s name.
service
- Ruby Type: String
The service the firewall rule applies to.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_firewall_rule resource in recipes:
Allowing port 80 access:
windows_firewall_rule 'IIS' do
local_port '80'
protocol 'TCP'
firewall_action :allow
end
Configuring multiple remote-address ports on a rule:
windows_firewall_rule 'MyRule' do
description 'Testing out remote address arrays'
enabled false
local_port 1434
remote_address %w(10.17.3.101 172.7.7.53)
protocol 'TCP'
action :create
end
Allow protocol ICMPv6 with ICMP Type:
windows_firewall_rule 'CoreNet-Rule' do
rule_name 'CoreNet-ICMP6-LR2-In'
display_name 'Core Networking - Multicast Listener Report v2 (ICMPv6-In)'
local_port 'RPC'
protocol 'ICMPv6'
icmp_type '8'
end
Blocking WinRM over HTTP on a particular IP:
windows_firewall_rule 'Disable WinRM over HTTP' do
local_port '5985'
protocol 'TCP'
firewall_action :block
local_address '192.168.1.1'
end
Deleting an existing rule
windows_firewall_rule 'Remove the SSH rule' do
rule_name 'ssh'
action :delete
end
windows_font resource
windows_font resource pageUse the windows_font resource to install font files on Windows. By default, the font is sourced from the cookbook using the resource, but a URI source can be specified as well.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the windows_font resource is:
windows_font 'name' do
font_name String # default value: 'name' unless specified
source String
action Symbol # defaults to :install if not specified
end
where:
windows_font
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.font_name
andsource
are the properties available to this resource.
Actions
The windows_font resource has the following actions:
:install
- Install a font to the system fonts directory. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The windows_font resource has the following properties:
font_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the name of the font to install if it differs from the resource block’s name.
source
- Ruby Type: String
A local filesystem path or URI that is used to source the font file.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_font resource in recipes:
Install a font from a https source:
windows_font 'Custom.otf' do
source 'https://example.com/Custom.otf'
end
windows_package resource
windows_package resource pageUse the windows_package resource to manage packages on the Microsoft Windows platform. The windows_package resource supports these installer formats:
- Microsoft Installer Package (MSI)
- Nullsoft Scriptable Install System (NSIS)
- Inno Setup (inno)
- Wise
- InstallShield
- Custom installers such as installing a non-.msi file that embeds an .msi-based installer
To enable idempotence of the :install
action or to enable the :remove
action with no source property specified,
package_name
MUST be an exact match of the name used by the package installer. The names of installed packages
Windows knows about can be found in Add/Remove programs, in the output of ohai packages
, or in the
DisplayName
property in one of the following in the Windows registry:
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall
HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Uninstall
HKEY_LOCAL_MACHINE\Software\Wow6432Node\Microsoft\Windows\CurrentVersion\Uninstall
Note
If there are multiple versions of a package installed with the same display name, all of those packages will be removed unless a version is provided in the version property or unless it can be discovered in the installer file specified by the source property.
Note
Syntax
A windows_package resource block manages a package on a node, typically by installing it. The simplest use of the windows_package resource is:
windows_package ''package_name''
which will install the named package using all of the default options
and the default action (:install
).'
The full syntax for all of the properties that are available to the windows_package resource is:
windows_package 'name' do
checksum String
installer_type Symbol
options String
package_name String
remote_file_attributes Hash
returns String, Integer, Array
source String # default value: "The resource block's name"
timeout String, Integer # default value: "600 (seconds)"
version String
action Symbol # defaults to :install if not specified
end
where:
windows_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.checksum
,installer_type
,options
,package_name
,remote_file_attributes
,returns
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The windows_package resource has the following actions:
:install
- Install a package. If a version is specified, install the specified version of the package. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
Properties
The windows_package resource has the following properties:
checksum
- Ruby Type: String
The SHA-256 checksum of the file. Use to prevent a file from being re-downloaded. When the local file matches the checksum, Chef Infra Client does not download it. Use when a URL is specified by the
source
property.
installer_type
- Ruby Type: SymbolAllowed Values:
:custom, :inno, :installshield, :msi, :nsis, :wise
A symbol that specifies the type of package. Possible values:
:custom
(such as installing a non-.msi file that embeds an .msi-based installer),:inno
(Inno Setup),:installshield
(InstallShield),:msi
(Microsoft Installer Package (MSI)),:nsis
(Nullsoft Scriptable Install System (NSIS)),:wise
(Wise).
options
- Ruby Type: String
One (or more) additional options that are passed to the command.
package_name
- Ruby Type: String
An optional property to set the package name if it differs from the resource block’s name.
remote_file_attributes
- Ruby Type: Hash
If the source package to install is at a remote location, this property allows you to define a hash of properties which will be used by the underlying remote_file resource used to fetch the source.
returns
- Ruby Type: String, Integer, Array of integers | Default Value:
0 (success) and 3010 (success where a reboot is necessary)
A comma-delimited list of return codes that indicate the success or failure of the package command that was run.
source
- Ruby Type: String | Default Value:
The resource block's name
The path to a package in the local file system. The location of the package may be at a URL.
If the
source
property is not specified, the package name MUST be exactly the same as the display name found in Add/Remove programs or exactly the same as theDisplayName
property in the appropriate registry key, which may be one of the following:HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Uninstall HKEY_LOCAL_MACHINE\Software\Wow6432Node\Microsoft\Windows\CurrentVersion\Uninstall
Note
If there are multiple versions of a package installed with the same display name, all of those packages will be removed unless a version is provided in the
version
property or unless it can be discovered in the installer file specified by thesource
property.
timeout
- Ruby Type: String, Integer | Default Value:
600 (seconds)
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String
The version of a package to be installed or upgraded.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_package resource in recipes:
Install a package:
windows_package '7zip' do
action :install
source 'C:\7z920.msi'
end
Specify a URL for the source attribute:
windows_package '7zip' do
source 'http://www.7-zip.org/a/7z938-x64.msi'
end
Specify path and checksum:
windows_package '7zip' do
source 'http://www.7-zip.org/a/7z938-x64.msi'
checksum '7c8e873991c82ad9cfc123415254ea6101e9a645e12977dcd518979e50fdedf3'
end
Modify remote_file resource attributes:
The windows_package resource may specify a package at a remote location using the remote_file_attributes property. This uses the remote_file resource to download the contents at the specified URL and passes in a Hash that modifies the properties of the remote_file resource.
windows_package '7zip' do
source 'http://www.7-zip.org/a/7z938-x64.msi'
remote_file_attributes ({
:path => 'C:\7zip.msi',
:checksum => '7c8e873991c82ad9cfc123415254ea6101e9a645e12977dcd518979e50fdedf3'
})
end
Download a nsis (Nullsoft) package resource:
windows_package 'Mercurial 3.6.1 (64-bit)' do
source 'https://www.mercurial-scm.org/release/windows/Mercurial-3.6.1-x64.exe'
checksum 'febd29578cb6736163d232708b834a2ddd119aa40abc536b2c313fc5e1b5831d'
end
Download a custom package:
windows_package 'Microsoft Visual C++ 2005 Redistributable' do
source 'https://download.microsoft.com/download/6/B/B/6BB661D6-A8AE-4819-B79F-236472F6070C/vcredist_x86.exe'
installer_type :custom
options '/Q'
end
windows_pagefile resource
windows_pagefile resource pageUse the windows_pagefile resource to configure pagefile settings on Windows.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the windows_pagefile resource is:
windows_pagefile 'name' do
automatic_managed true, false
initial_size Integer
maximum_size Integer
path String # default value: 'name' unless specified
system_managed true, false
action Symbol # defaults to :set if not specified
end
where:
windows_pagefile
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.automatic_managed
,initial_size
,maximum_size
,path
, andsystem_managed
are the properties available to this resource.
Actions
The windows_pagefile resource has the following actions:
:delete
- Deletes the specified pagefile.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:set
- Configures the default pagefile, creating if it doesn’t exist. (default)
Properties
The windows_pagefile resource has the following properties:
automatic_managed
- Ruby Type: true, false
Enable automatic management of pagefile initial and maximum size. Setting this to true ignores
initial_size
andmaximum_size
properties.
initial_size
- Ruby Type: Integer
Initial size of the pagefile in megabytes.
maximum_size
- Ruby Type: Integer
Maximum size of the pagefile in megabytes.
path
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the pagefile name if it differs from the resource block’s name.
system_managed
- Ruby Type: true, false
Configures whether the system manages the pagefile size.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_pagefile resource in recipes:
Set the system to manage pagefiles:
windows_pagefile 'Enable automatic management of pagefiles' do
automatic_managed true
end
Delete a pagefile:
windows_pagefile 'Delete the pagefile' do
path 'C'
action :delete
end
Switch to system managed pagefiles:
windows_pagefile 'Change the pagefile to System Managed' do
path 'E:'
system_managed true
action :set
end
Create a pagefile with an initial and maximum size:
windows_pagefile 'create the pagefile with these sizes' do
path 'f:'
initial_size 100
maximum_size 200
end
windows_path resource
windows_path resource pageUse the windows_path resource to manage the path environment variable on Microsoft Windows.
New in Chef Infra Client 13.4.
Syntax
The full syntax for all of the properties that are available to the windows_path resource is:
windows_path 'name' do
path String # default value: 'name' unless specified
action Symbol # defaults to :add if not specified
end
where:
windows_path
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.path
is the property available to this resource.
Actions
The windows_path resource has the following actions:
:add
- Add an item to the system path. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove an item from the system path.
Properties
The windows_path resource has the following properties:
path
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the path value if it differs from the resource block’s name.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_path resource in recipes:
Add Sysinternals to the system path:
windows_path 'C:\Sysinternals' do
action :add
end
Remove 7-Zip from the system path:
windows_path 'C:\7-Zip' do
action :remove
end
windows_printer resource
windows_printer resource pageUse the windows_printer resource to setup Windows printers. This resource will automatically install the driver specified in the driver_name
property and will automatically create a printer port using either the ipv4_address
property or the port_name
property.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the windows_printer resource is:
windows_printer 'name' do
comment String
create_port true, false # default value: true
default true, false # default value: false
device_id String # default value: 'name' unless specified
driver_name String
ipv4_address String
location String
port_name String
share_name String
shared true, false # default value: false
action Symbol # defaults to :create if not specified
end
where:
windows_printer
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.comment
,create_port
,default
,device_id
,driver_name
,ipv4_address
,location
,port_name
,share_name
, andshared
are the properties available to this resource.
Actions
The windows_printer resource has the following actions:
:create
- Create a new printer and printer port, if one doesn’t already. (default)
:delete
- Delete an existing printer. Note that this resource does not delete the associated printer port.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The windows_printer resource has the following properties:
comment
- Ruby Type: String
Optional descriptor for the printer queue.
create_port
- Ruby Type: true, false | Default Value:
true
Create a printer port for the printer. Set this to false and specify the
port_name
property if using thewindows_printer_port
resource to create the port instead.New in Chef Infra Client 17.3
default
- Ruby Type: true, false | Default Value:
false
Determines whether or not this should be the system’s default printer.
device_id
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the printer queue name if it differs from the resource block’s name. Example:
HP LJ 5200 in fifth floor copy room
.
driver_name
- Ruby Type: String |
REQUIRED
The exact name of printer driver installed on the system.
ipv4_address
- Ruby Type: String
The IPv4 address of the printer, such as
10.4.64.23
location
- Ruby Type: String
Printer location, such as
Fifth floor copy room
.
port_name
- Ruby Type: String | Default Value:
The resource block name or the ipv4_address prepended with IP_.
The port name.
New in Chef Infra Client 17.3
share_name
- Ruby Type: String
The name used to identify the shared printer.
shared
- Ruby Type: true, false | Default Value:
false
Determines whether or not the printer is shared.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_printer resource in recipes:
Create a printer:
windows_printer 'HP LaserJet 5th Floor' do
driver_name 'HP LaserJet 4100 Series PCL6'
ipv4_address '10.4.64.38'
end
Delete a printer:
Note: this doesn’t delete the associated printer port. See windows_printer_port above for how to delete the port.
windows_printer 'HP LaserJet 5th Floor' do
action :delete
end
Create a printer port and a printer that uses that port (new in 17.3)
windows_printer_port '10.4.64.39' do
port_name 'My awesome printer port'
snmp_enabled true
port_protocol 2
end
windows_printer 'HP LaserJet 5th Floor' do
driver_name 'HP LaserJet 4100 Series PCL6'
port_name 'My awesome printer port'
ipv4_address '10.4.64.38'
create_port false
end
windows_printer_port resource
windows_printer_port resource pageUse the windows_printer_port resource to create and delete TCP/IPv4 printer ports on Windows.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the windows_printer_port resource is:
windows_printer_port 'name' do
ipv4_address String # default value: 'name' unless specified
port_name String
port_number Integer # default value: 9100
port_protocol Integer # default value: 1
snmp_enabled true, false # default value: false
action Symbol # defaults to :create if not specified
end
where:
windows_printer_port
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.ipv4_address
,port_name
,port_number
,port_protocol
, andsnmp_enabled
are the properties available to this resource.
Actions
The windows_printer_port resource has the following actions:
:create
- Create or update the printer port. (default)
:delete
- Delete an existing printer port.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The windows_printer_port resource has the following properties:
ipv4_address
- Ruby Type: String | Default Value:
The resource block's name
An optional property for the IPv4 address of the printer if it differs from the resource block’s name.
port_name
- Ruby Type: String | Default Value:
The resource block name or the ipv4_address prepended with IP_.
The port name.
port_number
- Ruby Type: Integer | Default Value:
9100
The TCP port number.
port_protocol
- Ruby Type: Integer | Default Value:
1
Allowed Values:1, 2
The printer port protocol: 1 (RAW) or 2 (LPR).
snmp_enabled
- Ruby Type: true, false | Default Value:
false
Determines if SNMP is enabled on the port.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_printer_port resource in recipes:
Delete a printer port
windows_printer_port '10.4.64.37' do
action :delete
end
Delete a port with a custom port_name
windows_printer_port '10.4.64.38' do
port_name 'My awesome port'
action :delete
end
Create a port with more options
windows_printer_port '10.4.64.39' do
port_name 'My awesome port'
snmp_enabled true
port_protocol 2
end
windows_security_policy resource
windows_security_policy resource pageUse the windows_security_policy resource to set a security policy on the Microsoft Windows platform.
New in Chef Infra Client 16.0.
Syntax
The full syntax for all of the properties that are available to the windows_security_policy resource is:
windows_security_policy 'name' do
secoption String # default value: 'name' unless specified
secvalue String
action Symbol # defaults to :set if not specified
end
where:
windows_security_policy
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.secoption
andsecvalue
are the properties available to this resource.
Actions
The windows_security_policy resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:set
- Set the Windows security policy (default)
Properties
The windows_security_policy resource has the following properties:
secoption
- Ruby Type: String | Default Value:
The resource block's name
|REQUIRED
Allowed Values:"AuditPolicyChange", "ClearTextPassword", "EnableAdminAccount", "EnableGuestAccount", "ForceLogoffWhenHourExpire", "LSAAnonymousNameLookup", "LockoutBadCount", "LockoutDuration", "LockoutDuration", "MaximumPasswordAge", "MinimumPasswordAge", "MinimumPasswordLength", "NewAdministratorName", "NewGuestName", "PasswordComplexity", "PasswordHistorySize", "RequireLogonToChangePassword", "ResetLockoutCount"
The name of the policy to be set on windows platform to maintain its security.
secvalue
- Ruby Type: String |
REQUIRED
Policy value to be set for policy name.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_security_policy resource in recipes:
Set Administrator Account to Enabled:
windows_security_policy 'EnableAdminAccount' do
secvalue '1'
action :set
end
Rename Administrator Account:
windows_security_policy 'NewAdministratorName' do
secvalue 'AwesomeChefGuy'
action :set
end
Set Guest Account to Disabled:
windows_security_policy 'EnableGuestAccount' do
secvalue '0'
action :set
end
windows_service resource
windows_service resource pageUse the windows_service resource to create, delete, or manage a service on the Microsoft Windows platform.
New in Chef Infra Client 12.0.
Syntax
A windows_service resource block manages the state of a service on a machine that is running Microsoft Windows. For example:
windows_service 'BITS' do
action :configure_startup
startup_type :manual
end
The full syntax for all of the properties that are available to the windows_service resource is:
windows_service 'name' do
binary_path_name String
delayed_start true, false # default value: false
dependencies String, Array
description String
desired_access Integer # default value: 983551
display_name String
error_control Integer # default value: 1
load_order_group String
pattern String
reload_command String, false
restart_command String, false
run_as_password String
run_as_user String # default value: "localsystem"
service_name String # default value: 'name' unless specified
service_type Integer # default value: 16
start_command String, false
startup_type Symbol # default value: :automatic
status_command String, false
stop_command String, false
supports Hash # default value: {"restart"=>nil, "reload"=>nil, "status"=>nil}
timeout Integer # default value: 60
action Symbol # defaults to :nothing if not specified
end
where:
windows_service
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.binary_path_name
,delayed_start
,dependencies
,description
,desired_access
,display_name
,error_control
,load_order_group
,pattern
,reload_command
,restart_command
,run_as_password
,run_as_user
,service_name
,service_type
,start_command
,startup_type
,status_command
,stop_command
,supports
, andtimeout
are the properties available to this resource.
Actions
The windows_service resource has the following actions:
:configure
- Configure a pre-existing service. New in Chef Client 14.0.
:configure_startup
- Configure a service based on the value of the
startup_type
property. :create
- Create the service based on the value of the
binary_path_name
,service_name
and/ordisplay_name
property. New in Chef Client 14.0. :delete
- Delete the service based on the value of the
service_name
property. New in Chef Client 14.0. :disable
- Disable a service. This action is equivalent to a
Disabled
startup type on the Microsoft Windows platform. :enable
- Enable a service at boot. This action is equivalent to an
Automatic
startup type on the Microsoft Windows platform. :nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:reload
- Reload the configuration for this service. This action is not supported on the Windows platform and will raise an error if used.
:restart
- Restart a service.
:start
- Start a service, and keep it running until stopped or disabled.
:stop
- Stop a service.
Properties
The windows_service resource has the following properties:
binary_path_name
- Ruby Type: String
The fully qualified path to the service binary file. The path can also include arguments for an auto-start service. This is required for
:create
and:configure
actionsNew in Chef Client 14.0
delayed_start
- Ruby Type: true, false | Default Value:
false
Set the startup type to delayed start. This only applies if
startup_type
is:automatic
New in Chef Client 14.0
dependencies
- Ruby Type: String, Array
A pointer to a double null-terminated array of null-separated names of services or load ordering groups that the system must start before this service. Specify
nil
or an empty string if the service has no dependencies. Dependency on a group means that this service can run if at least one member of the group is running after an attempt to start all members of the group.New in Chef Client 14.0
description
- Ruby Type: String
Description of the service.
New in Chef Client 14.0
desired_access
- Ruby Type: Integer | Default Value:
983551
New in Chef Client 14.0
display_name
- Ruby Type: String
The display name to be used by user interface programs to identify the service. This string has a maximum length of 256 characters.
New in Chef Client 14.0
error_control
- Ruby Type: Integer | Default Value:
1
New in Chef Client 14.0
load_order_group
- Ruby Type: String
The name of the service’s load ordering group(s).
New in Chef Client 14.0
pattern
- Ruby Type: String | Default Value:
The value provided to 'service_name' or the resource block's name
The pattern to look for in the process table.
reload_command
- Ruby Type: String, false
The command used to tell a service to reload its configuration.
restart_command
- Ruby Type: String, false
The command used to restart a service.
run_as_password
- Ruby Type: String
The password for the user specified by
run_as_user
.
run_as_user
- Ruby Type: String | Default Value:
localsystem
The user under which a Microsoft Windows service runs.
service_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the service name if it differs from the resource block’s name.
service_type
- Ruby Type: Integer | Default Value:
16
New in Chef Client 14.0
start_command
- Ruby Type: String, false
The command used to start a service.
startup_type
- Ruby Type: Symbol | Default Value:
:automatic
Allowed Values::automatic, :disabled, :manual
Use to specify the startup type of the service.
status_command
- Ruby Type: String, false
The command used to check the run status for a service.
stop_command
- Ruby Type: String, false
The command used to stop a service.
supports
- Ruby Type: Hash | Default Value:
{"restart"=>nil, "reload"=>nil, "status"=>nil}
A list of properties that controls how Chef Infra Client is to attempt to manage a service:
:restart
,:reload
,:status
. For:restart
, the init script or other service provider can use a restart command; if:restart
is not specified, Chef Infra Client attempts to stop and then start a service. For:reload
, the init script or other service provider can use a reload command. For:status
, the init script or other service provider can use a status command to determine if the service is running; if:status
is not specified, Chef Infra Client attempts to match theservice_name
against the process table as a regular expression, unless a pattern is specified as a parameter property. Default value:{ restart: false, reload: false, status: false }
for all platforms (except for the Red Hat platform family, which defaults to{ restart: false, reload: false, status: true }
.)
timeout
- Ruby Type: Integer | Default Value:
60
The amount of time (in seconds) to wait before timing out.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_service resource in recipes:
Starting Services
Start a service with a manual
startup type:
windows_service 'BITS' do
action :configure_startup
startup_type :manual
end
Creating Services
Create a service named chef-client:
windows_service 'chef-client' do
action :create
binary_path_name "C:\opscode\chef\bin"
end
Create a service with service_name
and display_name
:
windows_service 'Setup chef-client as a service' do
action :create
display_name 'CHEF-CLIENT'
service_name 'chef-client'
binary_path_name "C:\opscode\chef\bin"
end
Create a service with the manual
startup type:
windows_service 'chef-client' do
action :create
binary_path_name "C:\opscode\chef\bin"
startup_type :manual
end
Create a service with the disabled
startup type:
windows_service 'chef-client' do
action :create
binary_path_name "C:\opscode\chef\bin"
startup_type :disabled
end
Create a service with the automatic
startup type and delayed start enabled:
windows_service 'chef-client' do
action :create
binary_path_name "C:\opscode\chef\bin"
startup_type :automatic
delayed_start true
end
Create a service with a description:
windows_service 'chef-client' do
action :create
binary_path_name "C:\opscode\chef\bin"
startup_type :automatic
description "Chef client as service"
end
Deleting Services
Delete a service named chef-client:
windows_service 'chef-client' do
action :delete
end
Delete a service with the service_name
property:
windows_service 'Delete chef client' do
action :delete
service_name 'chef-client'
end
Configuring Services
Change an existing service from automatic to manual startup:
windows_service 'chef-client' do
action :configure
binary_path_name "C:\opscode\chef\bin"
startup_type :manual
end
windows_share resource
windows_share resource pageUse the windows_share resource to create, modify and remove Windows shares.
New in Chef Infra Client 14.7.
Syntax
The full syntax for all of the properties that are available to the windows_share resource is:
windows_share 'name' do
ca_timeout Integer # default value: 0
change_users Array # default value: []
concurrent_user_limit Integer # default value: 0
continuously_available true, false # default value: false
description String
encrypt_data true, false # default value: false
full_users Array # default value: []
path String
read_users Array # default value: []
scope_name String # default value: "*"
share_name String # default value: 'name' unless specified
temporary true, false # default value: false
action Symbol # defaults to :create if not specified
end
where:
windows_share
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.ca_timeout
,change_users
,concurrent_user_limit
,continuously_available
,description
,encrypt_data
,full_users
,path
,read_users
,scope_name
,share_name
, andtemporary
are the properties available to this resource.
Actions
The windows_share resource has the following actions:
:create
- Create or modify a Windows share. (default)
:delete
- Delete an existing Windows share.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The windows_share resource has the following properties:
ca_timeout
- Ruby Type: Integer | Default Value:
0
The continuous availability time-out for the share.
change_users
- Ruby Type: Array | Default Value:
[]
The users that should have ‘modify’ permission on the share in domain\username format.
concurrent_user_limit
- Ruby Type: Integer | Default Value:
0
The maximum number of concurrently connected users the share can accommodate.
continuously_available
- Ruby Type: true, false | Default Value:
false
Indicates that the share is continuously available.
description
- Ruby Type: String
The description to be applied to the share.
encrypt_data
- Ruby Type: true, false | Default Value:
false
Indicates that the share is encrypted.
full_users
- Ruby Type: Array | Default Value:
[]
The users that should have ‘Full control’ permissions on the share in domain\username format.
path
- Ruby Type: String
The path of the folder to share. Required when creating. If the share already exists on a different path then it is deleted and re-created.
read_users
- Ruby Type: Array | Default Value:
[]
The users that should have ‘read’ permission on the share in domain\username format.
scope_name
- Ruby Type: String | Default Value:
*
The scope name of the share.
share_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the share name if it differs from the resource block’s name.
temporary
- Ruby Type: true, false | Default Value:
false
The lifetime of the new SMB share. A temporary share does not persist beyond the next restart of the computer.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_share resource in recipes:
Create a share:
windows_share 'foo' do
action :create
path 'C:\foo'
full_users ['DOMAIN_A\some_user', 'DOMAIN_B\some_other_user']
read_users ['DOMAIN_C\Domain users']
end
Delete a share:
windows_share 'foo' do
action :delete
end
windows_shortcut resource
windows_shortcut resource pageUse the windows_shortcut resource to create shortcut files on Windows.
New in Chef Infra Client 14.0.
Syntax
The full syntax for all of the properties that are available to the windows_shortcut resource is:
windows_shortcut 'name' do
arguments String
cwd String
description String
iconlocation String
shortcut_name String # default value: 'name' unless specified
target String
action Symbol # defaults to :create if not specified
end
where:
windows_shortcut
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.arguments
,cwd
,description
,iconlocation
,shortcut_name
, andtarget
are the properties available to this resource.
Actions
The windows_shortcut resource has the following actions:
:create
- Create or modify a Windows shortcut. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The windows_shortcut resource has the following properties:
arguments
- Ruby Type: String
Arguments to pass to the target when the shortcut is executed.
cwd
- Ruby Type: String
Working directory to use when the target is executed.
description
- Ruby Type: String
The description of the shortcut
iconlocation
- Ruby Type: String
Icon to use for the shortcut. Accepts the format of
path, index
, where index is the icon file to use. See Microsoft’s documentation for details
shortcut_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the shortcut name if it differs from the resource block’s name.
target
- Ruby Type: String
The destination that the shortcut links to.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_shortcut resource in recipes:
Create a shortcut with a description:
windows_shortcut 'C:\shortcut_dir.lnk' do
target 'C:\original_dir'
description 'Make a shortcut to C:\original_dir'
end
windows_task resource
windows_task resource pageUse the windows_task resource to create, delete or run a Windows scheduled task.
New in Chef Infra Client 13.0.
Syntax
The full syntax for all of the properties that are available to the windows_task resource is:
windows_task 'name' do
backup Integer, false # default value: 5
command String
cwd String
day String, Integer
description String
disallow_start_if_on_batteries true, false # default value: false
execution_time_limit String, Integer # default value: "PT72H (72 hours in ISO8601 duration format)"
force true, false # default value: false
frequency Symbol
frequency_modifier Integer, String # default value: 1
idle_time Integer
interactive_enabled true, false # default value: false
minutes_duration String, Integer
minutes_interval String, Integer
months String
password String
priority Integer # default value: 7
random_delay String, Integer
run_level Symbol # default value: :limited
start_day String # default value: The current date.
start_time String
start_when_available true, false # default value: false
stop_if_going_on_batteries true, false # default value: false
task_name String # default value: 'name' unless specified
user String # default value: The localized SYSTEM user for the node.
action Symbol # defaults to :create if not specified
end
where:
windows_task
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.backup
,command
,cwd
,day
,description
,disallow_start_if_on_batteries
,execution_time_limit
,force
,frequency
,frequency_modifier
,idle_time
,interactive_enabled
,minutes_duration
,minutes_interval
,months
,password
,priority
,random_delay
,run_level
,start_day
,start_time
,start_when_available
,stop_if_going_on_batteries
,task_name
, anduser
are the properties available to this resource.
Actions
The windows_task resource has the following actions:
:create
- Creates a scheduled task, or updates an existing task if any property has changed. (default)
:delete
- Deletes a scheduled task.
:disable
- Disables a scheduled task.
:enable
- Enables a scheduled task.
:end
- Ends a scheduled task.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:run
- Runs a scheduled task.
Properties
The windows_task resource has the following properties:
backup
- Ruby Type: Integer, false | Default Value:
5
Number of backups to keep of the task when modified/deleted. Set to false to disable backups.
New in Chef Infra Client 17.0
command
- Ruby Type: String
The command to be executed by the windows scheduled task.
cwd
- Ruby Type: String
The directory the task will be run from.
day
- Ruby Type: String, Integer
The day(s) on which the task runs.
- Use this property when setting
frequency
to:monthly
or:weekly
. - Valid values with frequency
:weekly
areMON
-SUN
or*
. - Valid values with frequency
:monthly
are1-31
,MON
-SUN
, andLASTDAY
. - Use
MON
-SUN
orLASTDAY
if you are settingfrequency_modifier
as “FIRST, SECOND, THIRD etc.” else use 1-31. - Multiple days should be comma separated. e.g
1, 2, 3
orMON, WED, FRI
.
- Use this property when setting
description
- Ruby Type: String
The task description.
New in Chef Client 14.7
disallow_start_if_on_batteries
- Ruby Type: true, false | Default Value:
false
Disallow start of the task if the system is running on battery power.
New in Chef Client 14.4
execution_time_limit
- Ruby Type: String, Integer | Default Value:
PT72H (72 hours in ISO8601 duration format)
The maximum time the task will run. This field accepts either seconds or an ISO8601 duration value.
force
- Ruby Type: true, false | Default Value:
false
When used with create, will update the task.
frequency
- Ruby Type: SymbolAllowed Values:
:daily, :hourly, :minute, :monthly, :none, :on_idle, :on_logon, :once, :onstart, :weekly
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 thestart_time
property to be set.
frequency_modifier
- Ruby Type: Integer, String | Default Value:
1
- 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')
OR1-12
.- e.g. If user want to run the task on
second week of the month
usefrequency_modifier
value asSECOND
. 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.
- e.g. If user want to run the task on
- For frequency
idle_time
- Ruby Type: Integer
For
:on_idle
frequency, the time (in minutes) without user activity that must pass to trigger the task, from1
-999
.
interactive_enabled
- Ruby Type: true, false | Default Value:
false
Allow task to run interactively or non-interactively. Requires user and password to also be set.
minutes_duration
- Ruby Type: String, Integer
minutes_interval
- Ruby Type: String, Integer
months
- Ruby Type: String
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
.
password
- Ruby Type: String
The user’s password. The user property must be set if using this property.
priority
- Ruby Type: Integer | Default Value:
7
Use to set Priority Levels range from 0 to 10.
random_delay
- Ruby Type: String, Integer
Delays the task up to a given time (in seconds).
run_level
- Ruby Type: Symbol | Default Value:
:limited
Allowed Values::highest, :limited
Run with
:limited
or:highest
privileges.
start_day
- Ruby Type: String | Default Value:
The current date.
Specifies the first date on which the task runs in MM/DD/YYYY format.
start_time
- Ruby Type: String
Specifies the start time to run the task, in HH:mm format.
start_when_available
- Ruby Type: true, false | Default Value:
false
To start the task at any time after its scheduled time has passed.
New in Chef Client 14.15
stop_if_going_on_batteries
- Ruby Type: true, false | Default Value:
false
Scheduled task option when system is switching on battery.
New in Chef Client 14.4
task_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the task name if it differs from the resource block’s name. Example:
Task Name
or/Task Name
user
- Ruby Type: String | Default Value:
The localized SYSTEM user for the node.
The user to run the task as.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_task resource in recipes:
Create a scheduled task to run every 15 minutes as the Administrator user:
windows_task 'chef-client' do
user 'Administrator'
password 'password'
command 'chef-client'
run_level :highest
frequency :minute
frequency_modifier 15
end
Create a scheduled task to run every 2 days:
windows_task 'chef-client' do
command 'chef-client'
run_level :highest
frequency :daily
frequency_modifier 2
end
Create a scheduled task to run on specific days of the week:
windows_task 'chef-client' do
command 'chef-client'
run_level :highest
frequency :weekly
day 'Mon, Thu'
end
Create a scheduled task to run only once:
windows_task 'chef-client' do
command 'chef-client'
run_level :highest
frequency :once
start_time '16:10'
end
Create a scheduled task to run on current day every 3 weeks and delay upto 1 min:
windows_task 'chef-client' do
command 'chef-client'
run_level :highest
frequency :weekly
frequency_modifier 3
random_delay '60'
end
Create a scheduled task to run weekly starting on Dec 28th 2018:
windows_task 'chef-client 8' do
command 'chef-client'
run_level :highest
frequency :weekly
start_day '12/28/2018'
end
Create a scheduled task to run every Monday, Friday every 2 weeks:
windows_task 'chef-client' do
command 'chef-client'
run_level :highest
frequency :weekly
frequency_modifier 2
day 'Mon, Fri'
end
Create a scheduled task to run when computer is idle with idle duration 20 min:
windows_task 'chef-client' do
command 'chef-client'
run_level :highest
frequency :on_idle
idle_time 20
end
Delete a task named “old task”:
windows_task 'old task' do
action :delete
end
Enable a task named “chef-client”:
windows_task 'chef-client' do
action :enable
end
Disable a task named “ProgramDataUpdater” with TaskPath “\Microsoft\Windows\Application Experience\ProgramDataUpdater”
windows_task '\Microsoft\Windows\Application Experience\ProgramDataUpdater' do
action :disable
end
windows_uac resource
windows_uac resource pageThe windows_uac resource configures UAC on Windows hosts by setting registry keys at HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System
New in Chef Infra Client 15.0.
Syntax
The full syntax for all of the properties that are available to the windows_uac resource is:
windows_uac 'name' do
consent_behavior_admins Symbol # default value: :prompt_for_consent_non_windows_binaries
consent_behavior_users Symbol # default value: :prompt_for_creds
detect_installers true, false
enable_uac true, false # default value: true
prompt_on_secure_desktop true, false # default value: true
require_signed_binaries true, false # default value: false
action Symbol # defaults to :configure if not specified
end
where:
windows_uac
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.consent_behavior_admins
,consent_behavior_users
,detect_installers
,enable_uac
,prompt_on_secure_desktop
, andrequire_signed_binaries
are the properties available to this resource.
Actions
The windows_uac resource has the following actions:
:configure
- Configures UAC by setting registry keys at
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System
. (default) :nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The windows_uac resource has the following properties:
consent_behavior_admins
- Ruby Type: Symbol | Default Value:
:prompt_for_consent_non_windows_binaries
Allowed Values::no_prompt, :prompt_for_consent, :prompt_for_consent_non_windows_binaries, :prompt_for_creds, :secure_prompt_for_consent, :secure_prompt_for_creds
Behavior of the elevation prompt for administrators in Admin Approval Mode. Sets HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System\EnableLUA\ConsentPromptBehaviorAdmin.
consent_behavior_users
- Ruby Type: Symbol | Default Value:
:prompt_for_creds
Allowed Values::auto_deny, :prompt_for_creds, :secure_prompt_for_creds
Behavior of the elevation prompt for standard users. Sets HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System\EnableLUA\ConsentPromptBehaviorUser.
detect_installers
- Ruby Type: true, false
Detect application installations and prompt for elevation. Sets HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System\EnableLUA\EnableInstallerDetection.
enable_uac
- Ruby Type: true, false | Default Value:
true
Enable or disable UAC Admin Approval Mode. If this is changed a system restart is required. Sets HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System\EnableLUA.
prompt_on_secure_desktop
- Ruby Type: true, false | Default Value:
true
Switch to the secure desktop when prompting for elevation. Sets HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System\EnableLUA\PromptOnSecureDesktop.
require_signed_binaries
- Ruby Type: true, false | Default Value:
false
Only elevate executables that are signed and validated. Sets HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System\EnableLUA\ValidateAdminCodeSignatures.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_uac resource in recipes:
Disable UAC prompts for the admin:
windows_uac 'Disable UAC prompts for the admin' do
enable_uac true
prompt_on_secure_desktop false
consent_behavior_admins :no_prompt
end
Disable UAC entirely:
windows_uac 'Disable UAC entirely' do
enable_uac false
end
windows_update_settings resource
windows_update_settings resource pageUse the windows_update_settings resource to manage the various Windows Update patching options.
New in Chef Infra Client 17.3.
Syntax
The full syntax for all of the properties that are available to the windows_update_settings resource is:
windows_update_settings 'name' do
automatic_update_option Integer, Symbol # default value: :download_and_schedule
automatically_install_minor_updates true, false # default value: false
block_windows_update_website true, false # default value: false
custom_detection_frequency Integer # default value: 22
disable_automatic_updates true, false # default value: false
disable_os_upgrades true, false # default value: false
elevate_non_admins true, false # default value: true
enable_detection_frequency true, false # default value: false
no_reboot_with_users_logged_on true, false # default value: true
scheduled_install_day String # default value: "Everyday"
scheduled_install_hour Integer
target_wsus_group_name String
update_other_ms_products true, false # default value: true
wsus_server_url String
action Symbol # defaults to :set if not specified
end
where:
windows_update_settings
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.automatic_update_option
,automatically_install_minor_updates
,block_windows_update_website
,custom_detection_frequency
,disable_automatic_updates
,disable_os_upgrades
,elevate_non_admins
,enable_detection_frequency
,no_reboot_with_users_logged_on
,scheduled_install_day
,scheduled_install_hour
,target_wsus_group_name
,update_other_ms_products
, andwsus_server_url
are the properties available to this resource.
Actions
The windows_update_settings resource has the following actions:
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:set
- Set Windows Update settings. (default)
Properties
The windows_update_settings resource has the following properties:
automatic_update_option
- Ruby Type: Integer, Symbol | Default Value:
:download_and_schedule
Allowed Values::download_and_notify, :download_and_schedule, :local_admin_decides, :notify
Control what to do when updates are found. This allows you to notify, automatically download and notify to install, automatically download and schedule the install, or let the local admin decide what action to take.
automatically_install_minor_updates
- Ruby Type: true, false | Default Value:
false
Automatically install minor updates.
block_windows_update_website
- Ruby Type: true, false | Default Value:
false
Block accessing the Windows Update website.
custom_detection_frequency
- Ruby Type: Integer | Default Value:
22
If you decided to override the OS default detection frequency, specify your choice here. Valid choices are 0 - 22
disable_automatic_updates
- Ruby Type: true, false | Default Value:
false
Disable Windows Update.
disable_os_upgrades
- Ruby Type: true, false | Default Value:
false
Disable OS upgrades.
elevate_non_admins
- Ruby Type: true, false | Default Value:
true
Allow normal user accounts to temporarily be elevated to install patches.
enable_detection_frequency
- Ruby Type: true, false | Default Value:
false
Used to override the OS default of how often to check for updates
no_reboot_with_users_logged_on
- Ruby Type: true, false | Default Value:
true
Prevents the OS from rebooting while someone is on the console.
scheduled_install_day
- Ruby Type: String | Default Value:
Everyday
Allowed Values:"Everyday", "Friday", "Monday", "Saturday", "Sunday", "Thursday", "Tuesday", "Wednesday"
A day of the week to tell Windows when to install updates.
scheduled_install_hour
- Ruby Type: Integer
If you chose a scheduled day to install, then choose an hour on that day for you installation
target_wsus_group_name
- Ruby Type: String
Add the node to a WSUS Target Group.
update_other_ms_products
- Ruby Type: true, false | Default Value:
true
Allows for other Microsoft products to get updates too
wsus_server_url
- Ruby Type: String
The URL of your WSUS server if you use one.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_update_settings resource in recipes:
Set Windows Update settings:
windows_update_settings 'Settings to Configure Windows Nodes to automatically receive updates' do
disable_os_upgrades true
elevate_non_admins true
block_windows_update_website true
automatically_install_minor_updates true
scheduled_install_day 'Friday'
scheduled_install_hour 18
update_other_ms_products true
action :enable
end
windows_user_privilege resource
windows_user_privilege resource pageUse the windows_user_privilege resource to set privileges for a principal, user, or group. See Microsoft’s user rights assignment documentation for more information.
New in Chef Infra Client 16.0.
Syntax
The full syntax for all of the properties that are available to the windows_user_privilege resource is:
windows_user_privilege 'name' do
principal String # default value: 'name' unless specified
privilege Array, String
users Array, String
action Symbol # defaults to :add if not specified
end
where:
windows_user_privilege
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.principal
,privilege
, andusers
are the properties available to this resource.
Actions
The windows_user_privilege resource has the following actions:
:add
- Add a privilege to a principal. (default)
:clear
- Clear all user privileges
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:remove
- Remove a privilege from a principal.
:set
- Set the privileges that are listed in the
privilege
property for only the users listed in theusers
property. All other users not listed with given privilege will be have the privilege removed.
Properties
The windows_user_privilege resource has the following properties:
principal
- Ruby Type: String | Default Value:
The resource block's name
An optional property to add the privilege for the specified principal. Use only with add and remove action. The principal can either be a user, group, or special identity.'
privilege
- Ruby Type: Array, String |
REQUIRED
One or more privileges to set for principal or users/groups. For more information, see Microsoft’s privileges documentation.
users
- Ruby Type: Array, String
An optional property to set the privilege for the specified users. Use only with
:set
action.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_user_privilege resource in recipes:
Set the SeNetworkLogonRight privilege for the Builtin Administrators and Authenticated Users groups:
The :set
action will add this privilege for these two groups and remove this privilege from all other groups or users.
windows_user_privilege 'Network Logon Rights' do
privilege 'SeNetworkLogonRight'
users ['BUILTIN\Administrators', 'NT AUTHORITY\Authenticated Users']
action :set
end
Set the SeCreatePagefilePrivilege privilege for the Builtin Guests and Administrator groups:
The :set
action will add this privilege for these two groups and remove this privilege from all other groups or users.
windows_user_privilege 'Create Pagefile' do
privilege 'SeCreatePagefilePrivilege'
users ['BUILTIN\Guests', 'BUILTIN\Administrators']
action :set
end
Add the SeDenyRemoteInteractiveLogonRight privilege to the ‘Remote interactive logon’ principal:
windows_user_privilege 'Remote interactive logon' do
privilege 'SeDenyRemoteInteractiveLogonRight'
action :add
end
Add the SeCreatePageFilePrivilege privilege to the Builtin Guests group:
windows_user_privilege 'Guests add Create Pagefile' do
principal 'BUILTIN\Guests'
privilege 'SeCreatePagefilePrivilege'
action :add
end
Remove the SeCreatePageFilePrivilege privilege from the Builtin Guests group:
windows_user_privilege 'Create Pagefile' do
privilege 'SeCreatePagefilePrivilege'
users ['BUILTIN\Guests']
action :remove
end
Clear the SeDenyNetworkLogonRight privilege from all users:
windows_user_privilege 'Allow any user the Network Logon right' do
privilege 'SeDenyNetworkLogonRight'
action :clear
end
windows_workgroup resource
windows_workgroup resource pageUse the windows_workgroup resource to join or change the workgroup of a Windows host.
New in Chef Infra Client 14.5.
Syntax
The full syntax for all of the properties that are available to the windows_workgroup resource is:
windows_workgroup 'name' do
password String
reboot Symbol # default value: :immediate
user String
workgroup_name String # default value: 'name' unless specified
action Symbol # defaults to :join if not specified
end
where:
windows_workgroup
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.password
,reboot
,user
, andworkgroup_name
are the properties available to this resource.
Actions
The windows_workgroup resource has the following actions:
:join
- Update the workgroup. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The windows_workgroup resource has the following properties:
password
- Ruby Type: String
The password for the local administrator user. Required if using the
user
property.
reboot
- Ruby Type: Symbol | Default Value:
:immediate
Allowed Values::never, :reboot_now, :request_reboot
Controls the system reboot behavior post workgroup joining. Reboot immediately, after the Chef Infra Client run completes, or never. Note that a reboot is necessary for changes to take effect.
user
- Ruby Type: String
The local administrator user to use to change the workgroup. Required if using the
password
property.
workgroup_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the workgroup name if it differs from the resource block’s name.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the windows_workgroup resource in recipes:
Join a workgroup:
windows_workgroup 'myworkgroup'
Join a workgroup using a specific user:
windows_workgroup 'myworkgroup' do
user 'Administrator'
password 'passw0rd'
end
yum_package resource
yum_package resource pageUse the yum_package resource to install, upgrade, and remove packages with Yum for the Red Hat and CentOS platforms. The yum_package resource is able to resolve provides
data for packages much like Yum can do when it is run from the command line. This allows a variety of options for installing packages, like minimum versions, virtual provides, and library names.
Note
Support for using file names to install packages (as in yum_package '/bin/sh'
) is not available because the volume of data required to parse for this is excessive.
Note
Syntax
The full syntax for all of the properties that are available to the yum_package resource is:
yum_package 'name' do
allow_downgrade true, false # default value: true
arch String, Array
flush_cache Hash # default value: {"before"=>false, "after"=>false}
options String, Array
package_name String, Array
source String
timeout String, Integer
version String, Array
yum_binary String
action Symbol # defaults to :install if not specified
end
where:
yum_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.allow_downgrade
,arch
,flush_cache
,options
,package_name
,source
,timeout
,version
, andyum_binary
are the properties available to this resource.
Actions
The yum_package resource has the following actions:
:install
- Install a package. If a version is specified, install the specified version of the package. (default)
:lock
- Locks the yum package to a specific version.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:purge
- Purge a package. This action typically removes the configuration files as well as the package.
:remove
- Remove a package.
:unlock
- Unlocks the yum package so that it can be upgraded to a newer version.
:upgrade
- Install a package and/or ensure that a package is the latest version. This action will ignore the
version
attribute.
Properties
The yum_package resource has the following properties:
allow_downgrade
- Ruby Type: true, false | Default Value:
true
Allow downgrading a package to satisfy requested version requirements.
arch
- Ruby Type: String, Array
The architecture of the package to be installed or upgraded. This value can also be passed as part of the package name.
flush_cache
- Ruby Type: Hash | Default Value:
{"before"=>false, "after"=>false}
Flush the in-memory cache before or after a Yum operation that installs, upgrades, or removes a package. Accepts a Hash in the form:
{ :before =\> true/false, :after =\> true/false }
or an Array in the form[ :before, :after ]
.Yum automatically synchronizes remote metadata to a local cache. Chef Infra Client creates a copy of the local cache, and then stores it in-memory during a Chef Infra Client run. The in-memory cache allows packages to be installed during a Chef Infra Client run without the need to continue synchronizing the remote metadata to the local cache while the Chef Infra Client run is in-progress.
As an array:
yum_package 'some-package' do #... flush_cache [ :before ] #... end
and as a Hash:
yum_package 'some-package' do #... flush_cache( { :after => true } ) #... end
Note
The
flush_cache
property does not flush the local Yum cache! Use Yum tools—yum clean headers
,yum clean packages
,yum clean all
—to clean the local Yum cache.
options
- Ruby Type: String, Array
One (or more) additional command options that are passed to the command.
package_name
- Ruby Type: String, Array
One of the following: the name of a package, the name of a package and its architecture, the name of a dependency. Default value: the
name
of the resource block. See “Syntax” section above for more information.
source
- Ruby Type: String
The optional path to a package on the local file system.
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String, Array
The version of a package to be installed or upgraded. This property is ignored when using the
:upgrade
action.
yum_binary
- Ruby Type: String
The path to the yum binary.
Multiple Packages
A resource may specify multiple packages and/or versions for platforms that use Apt, Chocolatey, DNF, Homebrew, Pacman, or Zypper package managers. Specifying multiple packages and/or versions allows a single transaction to:
- Download the specified packages and versions using a single HTTP transaction
- Update or install multiple packages with a single resource during a Chef Infra Client run
For example, installing multiple packages:
package %w(package1 package2)
Installing multiple packages with versions:
package %w(package1 package2) do
version [ '1.3.4-2', '4.3.6-1']
end
Upgrading multiple packages:
package %w(package1 package2) do
action :upgrade
end
Removing multiple packages:
package %w(package1 package2) do
action :remove
end
Purging multiple packages:
package %w(package1 package2) do
action :purge
end
Notifications, using an implicit name:
package %w(package1 package2) do
action :nothing
end
log 'call a notification' do
notifies :install, 'package[package1, package2]', :immediately
end
Note
Notifications and subscriptions do not need to be updated when packages
and versions are added or removed from the package_name
or version
properties.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Multiple Packages
A resource may specify multiple packages and/or versions for platforms that use Apt, Chocolatey, DNF, Homebrew, Pacman, or Zypper package managers. Specifying multiple packages and/or versions allows a single transaction to:
- Download the specified packages and versions using a single HTTP transaction
- Update or install multiple packages with a single resource during a Chef Infra Client run
For example, installing multiple packages:
package %w(package1 package2)
Installing multiple packages with versions:
package %w(package1 package2) do
version [ '1.3.4-2', '4.3.6-1']
end
Upgrading multiple packages:
package %w(package1 package2) do
action :upgrade
end
Removing multiple packages:
package %w(package1 package2) do
action :remove
end
Purging multiple packages:
package %w(package1 package2) do
action :purge
end
Notifications, using an implicit name:
package %w(package1 package2) do
action :nothing
end
log 'call a notification' do
notifies :install, 'package[package1, package2]', :immediately
end
Note
Notifications and subscriptions do not need to be updated when packages
and versions are added or removed from the package_name
or version
properties.
Examples
The following examples demonstrate various approaches for using the yum_package resource in recipes:
Install an exact version:
yum_package 'netpbm = 10.35.58-8.el8'
Install a minimum version:
yum_package 'netpbm >= 10.35.58-8.el8'
Install a minimum version using the default action:
yum_package 'netpbm'
Install a version without worrying about the exact release:
yum_package 'netpbm-10.35*'
To install a package:
yum_package 'netpbm' do
action :install
end
To install a partial minimum version:
yum_package 'netpbm >= 10'
To install a specific architecture:
yum_package 'netpbm' do
arch 'i386'
end
or:
yum_package 'netpbm.x86_64'
To install a specific version-release
yum_package 'netpbm' do
version '10.35.58-8.el8'
end
Handle cookbook_file and yum_package resources in the same recipe:
When a cookbook_file resource and a yum_package resource are
both called from within the same recipe, use the flush_cache
attribute
to dump the in-memory Yum cache, and then use the repository immediately
to ensure that the correct package is installed:
cookbook_file '/etc/yum.repos.d/custom.repo' do
source 'custom'
mode '0755'
end
yum_package 'pkg-that-is-only-in-custom-repo' do
action :install
flush_cache [ :before ]
end
yum_repository resource
yum_repository resource pageUse the yum_repository resource to manage a Yum repository configuration file located at /etc/yum.repos.d/repositoryid.repo
on the local machine. This configuration file specifies which repositories to reference, how to handle cached data, etc.
New in Chef Infra Client 12.14.
Syntax
The full syntax for all of the properties that are available to the yum_repository resource is:
yum_repository 'name' do
baseurl String, Array
clean_metadata true, false # default value: true
cost String
description String # default value: "Yum Repository"
enabled true, false # default value: true
enablegroups true, false
exclude String
failovermethod String
fastestmirror_enabled true, false
gpgcheck true, false # default value: true
gpgkey String, Array
http_caching String
include_config String
includepkgs String
keepalive true, false
make_cache true, false # default value: true
makecache_fast true, false # default value: false
max_retries String, Integer
metadata_expire String
metalink String
mirror_expire String
mirrorlist String
mirrorlist_expire String
mode String, Integer # default value: "0644"
options Hash
password String
priority String
proxy String
proxy_password String
proxy_username String
repo_gpgcheck true, false
report_instanceid true, false
reposdir String # default value: "/etc/yum.repos.d/"
repositoryid String # default value: 'name' unless specified
skip_if_unavailable true, false
source String
sslcacert String
sslclientcert String
sslclientkey String
sslverify true, false
throttle String, Integer
timeout String
username String
action Symbol # defaults to :create if not specified
end
where:
yum_repository
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.baseurl
,clean_metadata
,cost
,description
,enabled
,enablegroups
,exclude
,failovermethod
,fastestmirror_enabled
,gpgcheck
,gpgkey
,http_caching
,include_config
,includepkgs
,keepalive
,make_cache
,makecache_fast
,max_retries
,metadata_expire
,metalink
,mirror_expire
,mirrorlist
,mirrorlist_expire
,mode
,options
,password
,priority
,proxy
,proxy_password
,proxy_username
,repo_gpgcheck
,report_instanceid
,reposdir
,repositoryid
,skip_if_unavailable
,source
,sslcacert
,sslclientcert
,sslclientkey
,sslverify
,throttle
,timeout
, andusername
are the properties available to this resource.
Actions
The yum_repository resource has the following actions:
:create
- Create a repository based on the properties. (default)
:delete
- Remove a repository.
:makecache
- Force the creation of the repository cache. This is also done automatically when a repository is updated.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The yum_repository resource has the following properties:
baseurl
- Ruby Type: String, Array
URL to the directory where the Yum repository’s
repodata
directory lives. Can be anhttp://
,https://
or aftp://
URLs. You can specify multiple URLs in onebaseurl
statement.
clean_metadata
- Ruby Type: true, false | Default Value:
true
Specifies whether you want to purge all of the packages downloaded from a Yum repository and held in a cache directory.
cost
- Ruby Type: String
Relative cost of accessing this repository. Useful for weighing one repo’s packages as greater/less than any other.
description
- Ruby Type: String | Default Value:
Yum Repository
Descriptive name for the repository channel and maps to the ’name’ parameter in a repository .conf.
enabled
- Ruby Type: true, false | Default Value:
true
Specifies whether or not Yum should use this repository.
enablegroups
- Ruby Type: true, false
Specifies whether Yum will allow the use of package groups for this repository.
exclude
- Ruby Type: String
List of packages to exclude from updates or installs. This should be a space separated list. Shell globs using wildcards (eg. * and ?) are allowed.
failovermethod
- Ruby Type: StringAllowed Values:
"priority", "roundrobin"
Method to determine how to switch to a new server if the current one fails, which can either be
roundrobin
orpriority
.roundrobin
randomly selects a URL out of the list of URLs to start with and proceeds through each of them as it encounters a failure contacting the host.priority
starts from the firstbaseurl
listed and reads through them sequentially.
fastestmirror_enabled
- Ruby Type: true, false
Specifies whether to use the fastest mirror from a repository configuration when more than one mirror is listed in that configuration.
gpgcheck
- Ruby Type: true, false | Default Value:
true
Specifies whether or not Yum should perform a GPG signature check on the packages received from a repository.
gpgkey
- Ruby Type: String, Array
URL pointing to the ASCII-armored GPG key file for the repository. This is used if Yum needs a public key to verify a package and the required key hasn’t been imported into the RPM database. If this option is set, Yum will automatically import the key from the specified URL. Multiple URLs may be specified in the same manner as the baseurl option. If a GPG key is required to install a package from a repository, all keys specified for that repository will be installed. Multiple URLs may be specified in the same manner as the baseurl option. If a GPG key is required to install a package from a repository, all keys specified for that repository will be installed.
http_caching
- Ruby Type: StringAllowed Values:
"all", "none", "packages"
Determines how upstream HTTP caches are instructed to handle any HTTP downloads that Yum does. This option can take the following values:
all
means all HTTP downloads should be cachedpackages
means only RPM package downloads should be cached, but not repository metadata downloadsnone
means no HTTP downloads should be cached.
The default value of
all
is recommended unless you are experiencing caching related issues.
include_config
- Ruby Type: String
An external configuration file using the format
url://to/some/location
.
includepkgs
- Ruby Type: String
Inverse of exclude property. This is a list of packages you want to use from a repository. If this option lists only one package then that is all Yum will ever see from the repository.
keepalive
- Ruby Type: true, false
Determines whether or not HTTP/1.1
keep-alive
should be used with this repository.
make_cache
- Ruby Type: true, false | Default Value:
true
Determines whether package files downloaded by Yum stay in cache directories. By using cached data, you can carry out certain operations without a network connection.
makecache_fast
- Ruby Type: true, false | Default Value:
false
If
make_cache
istrue
, this usesyum makecache fast
, which downloads only the minimum amount of data required. Useful over slower connections and when disk space is at a premium.New in Chef Infra Client 18.1
max_retries
- Ruby Type: String, Integer
Number of times any attempt to retrieve a file should retry before returning an error. Setting this to
0
makes Yum try forever.
metadata_expire
- Ruby Type: String
Time (in seconds) after which the metadata will expire. If the current metadata downloaded is less than the value specified, then Yum will not update the metadata against the repository. If you find that Yum is not downloading information on updates as often as you would like lower the value of this option. You can also change from the default of using seconds to using days, hours or minutes by appending a
d
,h
orm
respectively. The default is six hours to compliment yum-updates running once per hour. It is also possible to use the wordnever
, meaning that the metadata will never expire.Note
When using a metalink file, the metalink must always be newer than the metadata for the repository due to the validation, so this timeout also applies to the metalink file.
metalink
- Ruby Type: String
Specifies a URL to a metalink file for the repomd.xml, a list of mirrors for the entire repository are generated by converting the mirrors for the repomd.xml file to a baseurl.
mirror_expire
- Ruby Type: String
Time (in seconds) after which the mirrorlist locally cached will expire. If the current mirrorlist is less than this many seconds old then Yum will not download another copy of the mirrorlist, it has the same extra format as metadata_expire. If you find that Yum is not downloading the mirrorlists as often as you would like lower the value of this option. You can also change from the default of using seconds to using days, hours or minutes by appending a
d
,h
orm
respectively.
mirrorlist
- Ruby Type: String
URL to a file containing a list of baseurls. This can be used instead of or with the baseurl option. Substitution variables, described below, can be used with this option.
mirrorlist_expire
- Ruby Type: String
Specifies the time (in seconds) after which the mirrorlist locally cached will expire. If the current mirrorlist is less than the value specified, then Yum will not download another copy of the mirrorlist. You can also change from the default of using seconds to using days, hours or minutes by appending a
d
,h
orm
respectively.
mode
- Ruby Type: String, Integer | Default Value:
0644
Permissions mode of .repo file on disk. This is useful for scenarios where secrets are in the repo file. If this value is set to
600
, normal users will not be able to use Yum search, Yum info, etc.
options
- Ruby Type: Hash
Specifies the repository options.
password
- Ruby Type: String
Password to use with the username for basic authentication.
priority
- Ruby Type: String
Assigns a priority to a repository where the priority value is between
1
and99
inclusive. Priorities are used to enforce ordered protection of repositories. Packages from repositories with a lower priority (higher numerical value) will never be used to upgrade packages that were installed from a repository with a higher priority (lower numerical value). The repositories with the lowest numerical priority number have the highest priority.
proxy
- Ruby Type: String
URL to the proxy server that Yum should use.
proxy_password
- Ruby Type: String
Password for this proxy.
proxy_username
- Ruby Type: String
Username to use for proxy.
repo_gpgcheck
- Ruby Type: true, false
Determines whether or not Yum should perform a GPG signature check on the repodata from this repository.
report_instanceid
- Ruby Type: true, false
Determines whether to report the instance ID when using Amazon Linux AMIs and repositories.
reposdir
- Ruby Type: String | Default Value:
/etc/yum.repos.d/
The directory where the Yum repository files should be stored
New in Chef Infra Client 16.9
repositoryid
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the repository name if it differs from the resource block’s name.
skip_if_unavailable
- Ruby Type: true, false
Allow yum to continue if this repository cannot be contacted for any reason.
source
- Ruby Type: String
Use a custom template source instead of the default one.
sslcacert
- Ruby Type: String
Path to the directory containing the databases of the certificate authorities Yum should use to verify SSL certificates.
sslclientcert
- Ruby Type: String
Path to the SSL client certificate Yum should use to connect to repos/remote sites.
sslclientkey
- Ruby Type: String
Path to the SSL client key Yum should use to connect to repos/remote sites.
sslverify
- Ruby Type: true, false
Determines whether Yum will verify SSL certificates/hosts.
throttle
- Ruby Type: String, Integer
Enable bandwidth throttling for downloads.
timeout
- Ruby Type: String
Number of seconds to wait for a connection before timing out. Defaults to 30 seconds. This may be too short of a time for extremely overloaded sites.
username
- Ruby Type: String
Username to use for basic authentication to a repository.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the yum_repository resource in recipes:
Add an internal company repository:
yum_repository 'OurCo' do
description 'OurCo yum repository'
mirrorlist 'http://artifacts.ourco.org/mirrorlist?repo=ourco-8&arch=$basearch'
gpgkey 'http://artifacts.ourco.org/pub/yum/RPM-GPG-KEY-OURCO-8'
action :create
end
Delete a repository:
yum_repository 'CentOS-Media' do
action :delete
end
zypper_package resource
zypper_package resource pageUse the zypper_package resource to install, upgrade, and remove packages with Zypper for the SUSE Enterprise and openSUSE platforms.
Note
Syntax
The full syntax for all of the properties that are available to the zypper_package resource is:
zypper_package 'name' do
allow_downgrade true, false # default value: true
global_options String, Array
gpg_check true, false # default value: "true"
options String, Array
package_name String, Array
source String
timeout String, Integer
version String, Array
action Symbol # defaults to :install if not specified
end
where:
zypper_package
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.allow_downgrade
,global_options
,gpg_check
,options
,package_name
,source
,timeout
, andversion
are the properties available to this resource.
Actions
The zypper_package resource has the following actions:
:install
- Install a package. If a version is specified, install the specified version of the package. (default)
:lock
- Locks the zypper package to a specific version.
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:purge
- Purge a package. This action typically removes the configuration files as well as the package.
:remove
- Remove a package.
:unlock
- Unlocks the zypper package so that it can be upgraded to a newer version.
:upgrade
- Install a package and/or ensure that a package is the latest version.
Properties
The zypper_package resource has the following properties:
allow_downgrade
- Ruby Type: true, false | Default Value:
true
Allow downgrading a package to satisfy requested version requirements.
New in Chef Client 13.6
global_options
- Ruby Type: String, Array
One (or more) additional command options that are passed to the command. For example, common zypper directives, such as
--no-recommends
. See the zypper man page for the full list.New in Chef Client 14.6
gpg_check
- Ruby Type: true, false | Default Value:
true
Verify the package’s GPG signature. Can also be controlled site-wide using the
zypper_check_gpg
config option.
options
- Ruby Type: String, Array
One (or more) additional command options that are passed to the command.
package_name
- Ruby Type: String, Array
An optional property to set the package name if it differs from the resource block’s name.
source
- Ruby Type: String
The optional path to a package on the local file system.
timeout
- Ruby Type: String, Integer
The amount of time (in seconds) to wait before timing out.
version
- Ruby Type: String, Array
The version of a package to be installed or upgraded.
Multiple Packages
A resource may specify multiple packages and/or versions for platforms that use Apt, Chocolatey, DNF, Homebrew, Pacman, or Zypper package managers. Specifying multiple packages and/or versions allows a single transaction to:
- Download the specified packages and versions using a single HTTP transaction
- Update or install multiple packages with a single resource during a Chef Infra Client run
For example, installing multiple packages:
package %w(package1 package2)
Installing multiple packages with versions:
package %w(package1 package2) do
version [ '1.3.4-2', '4.3.6-1']
end
Upgrading multiple packages:
package %w(package1 package2) do
action :upgrade
end
Removing multiple packages:
package %w(package1 package2) do
action :remove
end
Purging multiple packages:
package %w(package1 package2) do
action :purge
end
Notifications, using an implicit name:
package %w(package1 package2) do
action :nothing
end
log 'call a notification' do
notifies :install, 'package[package1, package2]', :immediately
end
Note
Notifications and subscriptions do not need to be updated when packages
and versions are added or removed from the package_name
or version
properties.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Multiple Packages
A resource may specify multiple packages and/or versions for platforms that use Apt, Chocolatey, DNF, Homebrew, Pacman, or Zypper package managers. Specifying multiple packages and/or versions allows a single transaction to:
- Download the specified packages and versions using a single HTTP transaction
- Update or install multiple packages with a single resource during a Chef Infra Client run
For example, installing multiple packages:
package %w(package1 package2)
Installing multiple packages with versions:
package %w(package1 package2) do
version [ '1.3.4-2', '4.3.6-1']
end
Upgrading multiple packages:
package %w(package1 package2) do
action :upgrade
end
Removing multiple packages:
package %w(package1 package2) do
action :remove
end
Purging multiple packages:
package %w(package1 package2) do
action :purge
end
Notifications, using an implicit name:
package %w(package1 package2) do
action :nothing
end
log 'call a notification' do
notifies :install, 'package[package1, package2]', :immediately
end
Note
Notifications and subscriptions do not need to be updated when packages
and versions are added or removed from the package_name
or version
properties.
Examples
The following examples demonstrate various approaches for using the zypper_package resource in recipes:
Install a package using package manager:
zypper_package 'name of package' do
action :install
end
Install a package using local file:
zypper_package 'jwhois' do
action :install
source '/path/to/jwhois.rpm'
end
Install without using recommend packages as a dependency:
package 'apache2' do
options '--no-recommends'
end
zypper_repository resource
zypper_repository resource pageUse the zypper_repository resource to create Zypper package repositories on SUSE Enterprise Linux and openSUSE systems. This resource maintains full compatibility with the zypper_repository resource in the existing zypper cookbook.
New in Chef Infra Client 13.3.
Syntax
The full syntax for all of the properties that are available to the zypper_repository resource is:
zypper_repository 'name' do
autorefresh true, false # default value: true
baseurl String
cookbook String # default value: "The cookbook containing the resource"
description String
enabled true, false # default value: true
gpgautoimportkeys true, false # default value: true
gpgcheck true, false # default value: true
gpgkey String, Array # default value: []
keeppackages true, false # default value: false
mirrorlist String
mode String, Integer # default value: "0644"
path String
priority Integer # default value: 99
refresh_cache true, false # default value: true
repo_name String # default value: 'name' unless specified
source String
type String # default value: "NONE"
action Symbol # defaults to :create if not specified
end
where:
zypper_repository
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.autorefresh
,baseurl
,cookbook
,description
,enabled
,gpgautoimportkeys
,gpgcheck
,gpgkey
,keeppackages
,mirrorlist
,mode
,path
,priority
,refresh_cache
,repo_name
,source
, andtype
are the properties available to this resource.
Actions
The zypper_repository resource has the following actions:
:create
- Add a new Zypper repository. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
:refresh
- Refresh Zypper repository.
:remove
- Remove a Zypper repository.
Properties
The zypper_repository resource has the following properties:
autorefresh
- Ruby Type: true, false | Default Value:
true
Determines whether or not the repository should be refreshed automatically.
baseurl
- Ruby Type: String
The base URL for the Zypper repository, such as
http://download.opensuse.org
.
cookbook
- Ruby Type: String | Default Value:
The cookbook containing the resource
The cookbook to source the repository template file from. Only necessary if you’re using a custom template for the repository file.
description
- Ruby Type: String
The description of the repository that will be shown by the
zypper repos
command.
enabled
- Ruby Type: true, false | Default Value:
true
Determines whether or not the repository should be enabled.
gpgautoimportkeys
- Ruby Type: true, false | Default Value:
true
Automatically import the specified key when setting up the repository.
gpgcheck
- Ruby Type: true, false | Default Value:
true
Determines whether or not to perform a GPG signature check on the repository.
gpgkey
- Ruby Type: String, Array | Default Value:
[]
The location of the repository key(s) to be imported.
keeppackages
- Ruby Type: true, false | Default Value:
false
Determines whether or not packages should be saved.
mirrorlist
- Ruby Type: String
The URL of the mirror list that will be used.
mode
- Ruby Type: String, Integer | Default Value:
0644
The file mode of the repository file.
path
- Ruby Type: String
The relative path from the repository’s base URL.
priority
- Ruby Type: Integer | Default Value:
99
Determines the priority of the Zypper repository.
refresh_cache
- Ruby Type: true, false | Default Value:
true
Determines whether or not the package cache should be refreshed.
repo_name
- Ruby Type: String | Default Value:
The resource block's name
An optional property to set the repository name if it differs from the resource block’s name.
source
- Ruby Type: String
The name of the template for the repository file. Only necessary if you’re using a custom template for the repository file.
type
- Ruby Type: String | Default Value:
NONE
Specifies the repository type.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the zypper_repository resource in recipes:
Add the Apache repo on openSUSE Leap 15:
zypper_repository 'apache' do
baseurl 'http://download.opensuse.org/repositories/Apache'
path '/openSUSE_Leap_15.2'
type 'rpm-md'
priority '100'
end
Remove the repo named ‘apache’:
zypper_repository 'apache' do
action :delete
end
Refresh the repo named ‘apache’:
zypper_repository 'apache' do
action :refresh
end