All Desktop Resources

macos_admin_control resource

Use the macos_admin_control resource to require Admin level privileges to make system-wide changes

New in Chef Infra Client 1.0.

Syntax

The full syntax for all of the properties that are available to the macos_admin_control resource is:

macos_admin_control 'name' do
  action      Symbol # defaults to :enable if not specified
end

where:

macos_admin_control 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 macos_admin_control resource has the following actions:

:disable
:enable
: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.

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 (the converge 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 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.

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, 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.

Examples

The following examples demonstrate various approaches for using the macos_admin_control resource in recipes:

Set Admin control to require Admin access:

admin_control 'Require Admin rights to perform system-wide changes' do
  action :enable
end

Do not require Admin access for System-Wide changes:

admin_control 'Require Admin rights to perform system-wide changes' do
  action :disable
end

macos_app_management resource

macos_app_management resource page

Use the macos_app_management resource to configure nodes to use Munki to manage apps

New in Chef Infra Client 1.0.

Syntax

The full syntax for all of the properties that are available to the macos_app_management resource is:

macos_app_management 'name' do
  munki_client_download_url      String
  munki_password                 String
  munki_repo_url                 String
  munki_user                     String
  action                         Symbol # defaults to :install if not specified
end

where:

macos_app_management 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.
munki_client_download_url, munki_password, munki_repo_url, and munki_user are the properties available to this resource.

Actions

The macos_app_management resource has the following actions:

:install: Installs the client on the macOS 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 macos_app_management resource has the following properties:

munki_client_download_url

Ruby Type: String

The URL where nodes will download the Munki client from

munki_password

Ruby Type: String

The password associated with the munki_user account

munki_repo_url

Ruby Type: String

The URL of the repository nodes will use to download apps, settings, etc

munki_user

Ruby Type: String

A username used to connect to the munki_repo_url with

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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

Examples

The following examples demonstrate various approaches for using the macos_app_management resource in recipes:

Set up managed app management for clients:

macos_app_management 'Configure Munki on the node' do
  munki_client_download_url 'https://github.com/munki/munki/releases/download/v5.0.0/munkitools-5.0.0.4034.pkg'
  munki_repo_url 'https://something.something.tld'
  munki_user 'munki'
  munki_password 'ILoveMunki'
  action :install
end

macos_automatic_logout resource

macos_automatic_logout resource page

Use the macos_automatic_logout resource to set the system to automatically logout after a set time.

New in Chef Infra Client 1.0.

Syntax

The full syntax for all of the properties that are available to the macos_automatic_logout resource is:

macos_automatic_logout 'name' do
  autologout_time      Integer # default value: 3600
  action               Symbol # defaults to :enable if not specified
end

where:

macos_automatic_logout 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.
autologout_time is the property available to this resource.

Actions

The macos_automatic_logout resource has the following actions:

:disable
:enable
: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 macos_automatic_logout resource has the following properties:

autologout_time

Ruby Type: Integer | Default Value: 3600

The amount of time in seconds to elapse before logging the system out. Defaults to 1 hour

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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

Examples

The following examples demonstrate various approaches for using the macos_automatic_logout resource in recipes:

Setup Automatic Logouts:

automatic_logout 'Automatically logout for inactivity' do
  autologout_time 900
  action :enable
end

Disable Automatic Logouts:

automatic_logout 'Automatically logout for inactivity' do
  action :disable
end

macos_automatic_software_updates resource

macos_automatic_software_updates resource page

Use the macos_automatic_software_updates resource to configure system and application updates on macOS systems.

New in Chef Infra Client 1.0.

Syntax

The full syntax for all of the properties that are available to the macos_automatic_software_updates resource is:

macos_automatic_software_updates 'name' do
  check                  true, false
  download               true, false
  install_app_store      true, false
  install_critical       true, false
  install_os             true, false
  action                 Symbol # defaults to :set if not specified
end

where:

macos_automatic_software_updates 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.
check, download, install_app_store, install_critical, and install_os are the properties available to this resource.

Actions

The macos_automatic_software_updates 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

Properties

The macos_automatic_software_updates resource has the following properties:

check

Ruby Type: true, false

Tell the OS to check for updates

download

Ruby Type: true, false

Tell the OS to download updates

install_app_store

Ruby Type: true, false

Set this to add app updates

install_critical

Ruby Type: true, false

Set this to install critical updates

install_os

Ruby Type: true, false

Set to update the OS

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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

Examples

The following examples demonstrate various approaches for using the macos_automatic_software_updates resource in recipes:

Setup automatic patch management:

macos_automatic_software_updates 'Settings for OS and Patch updates' do
  check true
  download true
  install_os true
  install_app_store true
  install_critical true
  action :set
end

macos_desktop_screensaver resource

macos_desktop_screensaver resource page

Use the macos_desktop_screensaver resource to configure secure screensaver settings on macOS systems.

New in Chef Infra Client 1.0.

Syntax

The full syntax for all of the properties that are available to the macos_desktop_screensaver resource is:

macos_desktop_screensaver 'name' do
  delay_before_password_prompt      Integer
  idle_time                         Integer # default value: 20
  require_password                  true, false
  action                            Symbol # defaults to :set if not specified
end

where:

macos_desktop_screensaver 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_before_password_prompt, idle_time, and require_password are the properties available to this resource.

Actions

The macos_desktop_screensaver resource has the following actions:

:disable: Turns off the screensaver.
: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 properties and enables the screen saver.

Properties

The macos_desktop_screensaver resource has the following properties:

delay_before_password_prompt

Ruby Type: Integer

Time in seconds for screensaver to be active before the system will prompt for password input

New in Chef Client 2.0

idle_time

Ruby Type: Integer | Default Value: 20
Allowed Values: 0, 1, 2, 5, 10, 20, 30, 60

Time in minutes before the the Screensaver comes on. Must be one of these values: 1, 2, 5, 10, 20, 30, 60

require_password

Ruby Type: true, false

Require a password when waking from the screensaver.

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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

Examples

The following examples demonstrate various approaches for using the macos_desktop_screensaver resource in recipes:

Turn on the Screensaver:

desktop_screensaver 'Sets up the screensaver to come on after 30 minutes of idle time and require a password' do
  idle_time 30
  require_password true
  delay_before_password_prompt 5
  action :set
end

macos_disk_encryption resource

macos_disk_encryption resource page

Use the macos_disk_encryption resource to enforce FileVault encryption on macOS systems.

New in Chef Infra Client 1.0.

Syntax

The full syntax for all of the properties that are available to the macos_disk_encryption resource is:

macos_disk_encryption 'name' do
  action      Symbol # defaults to :enable if not specified
end

where:

macos_disk_encryption 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 macos_disk_encryption resource has the following actions:

:enable: Turns on FileVault.
: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.

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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

Examples

This resource does not have any examples.

macos_firewall resource

macos_firewall resource page

Use the macos_firewall resource to enable the firewall on macOS systems.

Syntax

The full syntax for all of the properties that are available to the macos_firewall resource is:

macos_firewall 'name' do
  action      Symbol # defaults to :enable if not specified
end

where:

macos_firewall 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 macos_firewall resource has the following actions:

:disable
:enable
: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.

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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

Examples

The following examples demonstrate various approaches for using the macos_firewall resource in recipes:

Turn on the macOS Firewall:

macos_firewall 'Enable Firewall Protection' do
  action :enable
end

Turn off the macOS Firewall:

macos_firewall 'Disable Firewall Protection' do
  action :disable
end

macos_password_policy resource

macos_password_policy resource page

Use the macos_password_policy resource to set password complexity, password length, etc on macOS systems.

New in Chef Infra Client 1.0.

Syntax

The full syntax for all of the properties that are available to the macos_password_policy resource is:

macos_password_policy 'name' do
  exempt_user                      String
  lockout_time                     Integer
  max_failed_logins                Integer
  maximum_password_age             Integer # default value: 365
  minimum_lowercase_letters        Integer # default value: 0
  minimum_numeric_characters       Integer # default value: 0
  minimum_password_length          Integer # default value: 12
  minimum_special_characters       Integer # default value: 0
  minimum_uppercase_letters        Integer # default value: 0
  remember_how_many_passwords      Integer # default value: 3
  action                           Symbol # defaults to :set if not specified
end

where:

macos_password_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.
exempt_user, lockout_time, max_failed_logins, maximum_password_age, minimum_lowercase_letters, minimum_numeric_characters, minimum_password_length, minimum_special_characters, minimum_uppercase_letters, and remember_how_many_passwords are the properties available to this resource.

Actions

The macos_password_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: This action sets the password policy as defined in its properties.

Properties

The macos_password_policy resource has the following properties:

exempt_user

Ruby Type: String

A user to whom the password policy is not applied

lockout_time

Ruby Type: Integer

The amount of time your account is locked out after you exceed max failed logins

max_failed_logins

Ruby Type: Integer

The maximum number of failed logins before you are locked out

maximum_password_age

Ruby Type: Integer | Default Value: 365

The maximum age in days for a password before it must be changed, defaults to 365

minimum_lowercase_letters

Ruby Type: Integer | Default Value: 0

The minimum number of lower case letters that must be in a password

minimum_numeric_characters

Ruby Type: Integer | Default Value: 0

The minimum number of numbers that must be in a password

minimum_password_length

Ruby Type: Integer | Default Value: 12

The minimum length a password must be

minimum_special_characters

Ruby Type: Integer | Default Value: 0

The minimum number of special characters that must be in a password. Eg. *&^%

minimum_uppercase_letters

Ruby Type: Integer | Default Value: 0

The minimum number of upper case letters that must be in a password

remember_how_many_passwords

Ruby Type: Integer | Default Value: 3

The number of previous passwords to remember to prevent users for keeping stale passwords

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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

Examples

The following examples demonstrate various approaches for using the macos_password_policy resource in recipes:

Set the local password policy:

macos_password_policy 'Setup appropriate password complexity and rules' do
  max_failed_logins 5
  lockout_time 2
  maximum_password_age 365
  minimum_password_length 12
  minimum_numeric_characters 0
  minimum_lowercase_letters 0
  minimum_uppercase_letters 0
  minimum_special_characters 0
  remember_how_many_passwords 3
  exempt_user 'MyAdmin'
  action :set
end

macos_power_management resource

macos_power_management resource page

Use the macos_power_management resource to set the power settings of a kiosk-style device when you need it always-on

New in Chef Infra Client 1.0.

Syntax

The full syntax for all of the properties that are available to the macos_power_management resource is:

macos_power_management 'name' do
  computer_sleep_time      String # default value: "never"
  disk_sleep_time          String # default value: "never"
  display_sleep_time       String # default value: "never"
  action                   Symbol # defaults to :set if not specified
end

where:

macos_power_management 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.
computer_sleep_time, disk_sleep_time, and display_sleep_time are the properties available to this resource.

Actions

The macos_power_management 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: This action sets the policy as defined in its properties.

Properties

The macos_power_management resource has the following properties:

computer_sleep_time

Ruby Type: String | Default Value: never

A time value between 1-60 minutes or “never” to use to set the computer to sleep after. Defaults to never

disk_sleep_time

Ruby Type: String | Default Value: never

A time value between 1-60 minutes or “never” to use to set the hard disk to sleep after. Defaults to never

display_sleep_time

Ruby Type: String | Default Value: never

A time value between 1-60 minutes or “never” to use to set the display to sleep after. Defaults to never

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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

Examples

The following examples demonstrate various approaches for using the macos_power_management resource in recipes:

Configure Power Management settings:

macos_power_management 'Set the Device to a defined power level' do
  computer_sleep_time 'never'
  display_sleep_time 'never'
  disk_sleep_time 'never'
  action :set
end

rescue_account resource

rescue_account resource page

Use the rescue_account resource to provide Administrators with a rescue account.

New in Chef Infra Client 1.0.

Syntax

The full syntax for all of the properties that are available to the rescue_account resource is:

rescue_account 'name' do
  account_name      String
  password          String
  action            Symbol # defaults to :create if not specified
end

where:

rescue_account 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.
account_name and password are the properties available to this resource.

Actions

The rescue_account resource has the following actions:

:create: Creates the user specified in the property field.
:delete: Deletes the named user.
:disable: Turns off the account if it was enabled.
:enable: Turns the account on if previously disabled.
: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 rescue_account resource has the following properties:

account_name

Ruby Type: String | REQUIRED

Name of the user to be created as a rescue account

password

Ruby Type: String | REQUIRED

Corresponding password for that user

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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

Examples

The following examples demonstrate various approaches for using the rescue_account resource in recipes:

Create a managed user account:

rescue_account 'Configure an Admin level account for IT to use' do
  account_name 'MyAdmin'
  password '123Opscode!!'
  action :create
end

Delete a managed user account:

rescue_account 'Delete an Admin level account for IT to use' do
  account_name 'MyAdmin'
  action :delete
end

Enable an existing managed user account:

rescue_account 'Enable an Admin level account for IT to use' do
  account_name 'MyAdmin'
  action :enable
end

Disable an existing managed user account:

rescue_account 'Disable an Admin level account' do
  account_name 'MyAdmin'
  action :disable
end

windows_admin_control resource

windows_admin_control resource page

Use the windows_admin_control resource to enforce Admin level access for system-wide changes.

New in Chef Infra Client 1.0.

Syntax

The full syntax for all of the properties that are available to the windows_admin_control resource is:

windows_admin_control 'name' do
  action      Symbol # defaults to :enable if not specified
end

where:

windows_admin_control 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 windows_admin_control resource has the following actions:

:disable
:enable
: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.

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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

Examples

The following examples demonstrate various approaches for using the windows_admin_control resource in recipes:

Turns on UAC to enforce Admin access for changes:

admin_control 'Require Admin rights to perform system-wide changes' do
  action :enable
end

Turns off UAC:

admin_control 'Do Not Require Admin rights to perform system-wide changes' do
  action :disable
end

windows_app_management resource

windows_app_management resource page

Use the windows_app_management resource to configure nodes to use Gorilla for application management.

New in Chef Infra Client 1.0.

Syntax

The full syntax for all of the properties that are available to the windows_app_management resource is:

windows_app_management 'name' do
  update_check_frequency      String
  action                      Symbol # defaults to :enable if not specified
end

where:

windows_app_management 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.
update_check_frequency is the property available to this resource.

Actions

The windows_app_management resource has the following actions:

:disable: Disables the Windows Scheduled Task.
:enable: Sets the property, installs Gorilla, configures the local install with the yaml file, and sets a Windows Scheduled Task to run at the interval set by how_often_to_check_for_updates.
: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_app_management resource has the following properties:

update_check_frequency

Ruby Type: String
Allowed Values: "daily", "minute", "monthly", "none", "on_idle", "on_logon", "once", "onstart", "weekly"

How often should the Gorilla client check for updates.

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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

Examples

The following examples demonstrate various approaches for using the windows_app_management resource in recipes:

Configure managed application management:

windows_app_management 'Use Gorilla to manage Apps' do
  update_check_frequency 'daily'
  action :enable
end

Disable managed application management:

windows_app_management 'Do Not Use Gorilla to manage Apps' do
  action :disable
end

windows_automatic_logout resource

windows_automatic_logout resource page

Use the windows_automatic_logout resource to set the system to automatically logout after a set time.

New in Chef Infra Client 1.0.

Syntax

The full syntax for all of the properties that are available to the windows_automatic_logout resource is:

windows_automatic_logout 'name' do
  autologout_time      Integer # default value: 3600
  action               Symbol # defaults to :enable if not specified
end

where:

windows_automatic_logout 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.
autologout_time is the property available to this resource.

Actions

The windows_automatic_logout 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

Properties

The windows_automatic_logout resource has the following properties:

autologout_time

Ruby Type: Integer | Default Value: 3600

The amount of time in seconds to elapse before logging the system out. Defaults to 3600s (1 hour)

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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

Examples

The following examples demonstrate various approaches for using the windows_automatic_logout resource in recipes:

Set the node to auto-logout when not being used:

automatic_logout 'Automatically logout for inactivity' do
  autologout_time 900
  action :enable
end

Disable auto-logout:

automatic_logout 'Disable automatic inactivity logout' do
  autologout_time 900
  action :disable
end

windows_choco_installer resource

windows_choco_installer resource page

Use the windows_choco_installer resource to install the Chocolatey package manager on Windows clients.

New in Chef Infra Client 2.0.

Syntax

The full syntax for all of the properties that are available to the windows_choco_installer resource is:

windows_choco_installer 'name' do
  action      Symbol # defaults to :install if not specified
end

where:

windows_choco_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.

Actions

The windows_choco_installer resource has the following actions:

:install: Install the 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.

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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

Examples

The following examples demonstrate various approaches for using the windows_choco_installer resource in recipes:

Configure Chocolatey Package Manager:

windows_choco_installer 'Install Chocolatey Package Manager' do
  action :install
end

windows_defender resource

windows_defender resource page

Use the windows_defender resource to enable or disable the Microsoft Windows Defender service.

New in Chef Infra Client 1.0.

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, and scan_scripts are the properties available to this resource.

Actions

The windows_defender resource has the following actions:

:disable: Disable Windows Defender.
:enable: Enable Windows Defender and configure settings.
: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.

New in Chef Client 1.1

lock_ui

Ruby Type: true, false | Default Value: false

Lock the UI to prevent users from changing Windows Defender settings.

New in Chef Client 1.1

realtime_protection

Ruby Type: true, false | Default Value: true

Enable realtime scanning of downloaded files and attachments.

New in Chef Client 1.1

scan_archives

Ruby Type: true, false | Default Value: true

Scan file archives such as .zip or .gz archives.

New in Chef Client 1.1

scan_email

Ruby Type: true, false | Default Value: false

Scan e-mails for malware.

New in Chef Client 1.1

scan_mapped_drives

Ruby Type: true, false | Default Value: true

Scan files on mapped network drives.

New in Chef Client 1.1

scan_network_files

Ruby Type: true, false | Default Value: false

Scan files on a network.

New in Chef Client 1.1

scan_removable_drives

Ruby Type: true, false | Default Value: false

Scan content of removable drives.

New in Chef Client 1.1

scan_scripts

Ruby Type: true, false | Default Value: false

Scan scripts in malware scans.

New in Chef Client 1.1

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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

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 page

Use the windows_defender_exclusion resource to exclude paths, processes, or file types from Windows Defender realtime protection scanning.

New in Chef Infra Client 1.1.

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, and process_paths are the properties available to this resource.

Actions

The windows_defender_exclusion resource has the following actions:

:add
: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_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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

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_desktop_screensaver resource

windows_desktop_screensaver resource page

Use the windows_desktop_screensaver resource to configure secure screensaver settings on Windows systems.

New in Chef Infra Client 1.0.

Syntax

The full syntax for all of the properties that are available to the windows_desktop_screensaver resource is:

windows_desktop_screensaver 'name' do
  allow_lower_user_idle_time      true, false # default value: false
  idle_time                       Integer # default value: 20
  require_password                true, false # default value: true
  screensaver_name                String
  action                          Symbol # defaults to :enable if not specified
end

where:

windows_desktop_screensaver 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_lower_user_idle_time, idle_time, require_password, and screensaver_name are the properties available to this resource.

Actions

The windows_desktop_screensaver resource has the following actions:

:disable: Disable the desktop screen saver.
:enable: Enable the desktop screen saver.
: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_desktop_screensaver resource has the following properties:

allow_lower_user_idle_time

Ruby Type: true, false | Default Value: false

Allow users to set their screen saver idle time lower than the system requirements.

idle_time

Ruby Type: Integer | Default Value: 20

The amount of idle time in minutes before the screensaver comes on.

require_password

Ruby Type: true, false | Default Value: true

Require a password when waking from the screensaver.

screensaver_name

Ruby Type: String

The name of a specific or custom screensaver to enable.

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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

Examples

The following examples demonstrate various approaches for using the windows_desktop_screensaver resource in recipes:

Secure the desktop with a screensaver and password:

desktop_screensaver 'Sets up a Screensaver to come on and require a password after xx minutes' do
  require_password true
  idle_time 20
  allow_lower_user_idle_time false
  screensaver_name 'mystify.scr'
  action :enable
end

Disable requiring a screensaver with a password:

desktop_screensaver 'Disable the screensaver' do
  action :disable
end

windows_desktop_winrm_settings resource

windows_desktop_winrm_settings resource page

Use the windows_desktop_winrm_settings resource to setup and teardown WinRM settings on a node. Chef Infra Client does not require this for operation.

New in Chef Infra Client 1.0.

Syntax

The full syntax for all of the properties that are available to the windows_desktop_winrm_settings resource is:

windows_desktop_winrm_settings 'name' do
  action      Symbol # defaults to :enable if not specified
end

where:

windows_desktop_winrm_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.

Actions

The windows_desktop_winrm_settings resource has the following actions:

:disable: Turns off WinRM and disables the firewall policy.
:enable: Turns on WinRM and sets a firewall policy.
: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.

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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

Examples

The following examples demonstrate various approaches for using the windows_desktop_winrm_settings resource in recipes:

Turn WinRM On:

windows_desktop_winrm_settings 'Settings to enable WinRM on a node for desktop-config' do
  action :enable
end

Turn WinRM Off:

windows_desktop_winrm_settings 'Settings to disable WinRM on a node for desktop-config' do
  action :disable
end

windows_disk_encryption resource

windows_disk_encryption resource page

Use the windows_disk_encryption resource to enable or disable BitLocker Drive Encryption on Windows systems.

New in Chef Infra Client 1.0.

Syntax

The full syntax for all of the properties that are available to the windows_disk_encryption resource is:

windows_disk_encryption 'name' do
  reboot_after_update      true, false # default value: true
  action                   Symbol # defaults to :enable if not specified
end

where:

windows_disk_encryption 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.
reboot_after_update is the property available to this resource.

Actions

The windows_disk_encryption resource has the following actions:

:disable: Turns off BitLocker.
:enable: Turns on BitLocker.
: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_disk_encryption resource has the following properties:

reboot_after_update

Ruby Type: true, false | Default Value: true

Control the reboot behavior after enabling BitLocker

New in Chef Client 1.1

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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

Examples

The following examples demonstrate various approaches for using the windows_disk_encryption resource in recipes:

Enable BitLocker:

disk_encryption 'Turns on BitLocker Drive Encryption' do
  action :enable
  reboot_after_update true
end

windows_firewall resource

windows_firewall resource page

Use the windows_firewall resource to enable or disable the Windows firewall service and all profiles.

New in Chef Infra Client 1.0.

Syntax

The full syntax for all of the properties that are available to the windows_firewall resource is:

windows_firewall 'name' do
  action      Symbol # defaults to :enable if not specified
end

where:

windows_firewall 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 windows_firewall resource has the following actions:

:disable: Disable the Windows Firewall service
:enable: Enable the Windows Firewall service and all profiles
: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.

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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

Examples

The following examples demonstrate various approaches for using the windows_firewall resource in recipes:

Set the Windows firewall:

windows_firewall 'Enable the node firewall' do
  action :enable
end

windows_ie_esc resource

windows_ie_esc resource page

Use the windows_ie_esc resource to adjust the Internet Explorer extensibility and security settings.

New in Chef Infra Client 2.0.

Syntax

The full syntax for all of the properties that are available to the windows_ie_esc resource is:

windows_ie_esc 'name' do
  scopes      Array
  action      Symbol # defaults to :enable if not specified
end

where:

windows_ie_esc 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.
scopes is the property available to this resource.

Actions

The windows_ie_esc resource has the following actions:

:disable: Disable Internet Explorer extensibility and security settings for scoped users.
:enable: Enable Internet Explorer extensibility and security settings for scoped users (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_ie_esc resource has the following properties:

scopes

Ruby Type: Array | REQUIRED

Windows user scopes targeted by this security config

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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

Examples

The following examples demonstrate various approaches for using the windows_ie_esc resource in recipes:

Turns off Internet Explorer ESC:

windows_ie_esc 'Turn off Internet Explorer ESC for admin' do
  scopes [:admin]
  action :disable
end

Turns on Internet Explorer ESC to reduce risks from exposure to websites:

windows_ie_esc 'Enforce Internet Explorer ESC for all user scopes' do
  scopes [:admin, :user]
  action :enable
end

windows_password_policy resource

windows_password_policy resource page

Use the windows_password_policy resource to setup password complexity, password length, etc.

New in Chef Infra Client 1.0.

Syntax

The full syntax for all of the properties that are available to the windows_password_policy resource is:

windows_password_policy 'name' do
  change_password_at_next_logon              true, false # default value: false
  group_name_for_expired_passwords           String # default value: "Users"
  group_name_for_password_never_expires      String # default value: "Administrators"
  maximum_password_age                       Integer # default value: 365
  minimum_password_length                    Integer # default value: 12
  password_never_expires                     true, false
  require_complex_passwords                  true, false # default value: true
  action                                     Symbol # defaults to :set if not specified
end

where:

windows_password_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.
change_password_at_next_logon, group_name_for_expired_passwords, group_name_for_password_never_expires, maximum_password_age, minimum_password_length, password_never_expires, and require_complex_passwords are the properties available to this resource.

Actions

The windows_password_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: Sets the password policy using the properties.

Properties

The windows_password_policy resource has the following properties:

change_password_at_next_logon

Ruby Type: true, false | Default Value: false

Force all users in a local user group to change passwords at next logon

group_name_for_expired_passwords

Ruby Type: String | Default Value: Users

The group whose passwords were just to change at the next login

group_name_for_password_never_expires

Ruby Type: String | Default Value: Administrators

The group to which the password_never_expires rule applies. Defaults to Admins

maximum_password_age

Ruby Type: Integer | Default Value: 365

The maximum age in days for a password before it must be changed, defaults to 365

minimum_password_length

Ruby Type: Integer | Default Value: 12

Sets the minimum password length, defaults to 12 Characters

password_never_expires

Ruby Type: true, false

True/False to never expire the passwords, set to True by default

require_complex_passwords

Ruby Type: true, false | Default Value: true

A True/False option to require special characters, upper, lower, etc in the password

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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

Examples

The following examples demonstrate various approaches for using the windows_password_policy resource in recipes:

Configure the local password policy:

windows_password_policy 'Settings for password complexity, length and duration' do
  require_complex_passwords true
  minimum_password_length 12
  maximum_password_age 365
  action :set
end

windows_power_management resource

windows_power_management resource page

Use the windows_power_management resource to set the power settings of a kiosk-style device when you need it always-on

New in Chef Infra Client 1.0.

Syntax

The full syntax for all of the properties that are available to the windows_power_management resource is:

windows_power_management 'name' do
  disk_timeout            Integer
  hibernate_timeout       Integer
  monitor_timeout         Integer
  power_level             String # default value: "balanced"
  power_scheme_label      String
  standby_timeout         Integer
  action                  Symbol # defaults to :set if not specified
end

where:

windows_power_management 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.
disk_timeout, hibernate_timeout, monitor_timeout, power_level, power_scheme_label, and standby_timeout are the properties available to this resource.

Actions

The windows_power_management 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 power scheme on a node to ‘balanced’ or ‘ultimate’.

Properties

The windows_power_management resource has the following properties:

disk_timeout

Ruby Type: Integer

The amount of time in minutes to wait before turning off the HD

hibernate_timeout

Ruby Type: Integer

The amount of time in minutes to wait before hibernating the system

monitor_timeout

Ruby Type: Integer

The amount of time in minutes to wait before turning off the display

power_level

Ruby Type: String | Default Value: balanced

There are 2 levels of power - balanced, and ultimate.

power_scheme_label

Ruby Type: String

A label name to prefix your power scheme with. The code duplicates the existing power scheme to keep it distinct

standby_timeout

Ruby Type: Integer

The amount of time in minutes to wait before putting the system into standby

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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

Examples

The following examples demonstrate various approaches for using the windows_power_management resource in recipes:

Setup a Power Management Policy:

windows_power_management 'Set the Device to a defined power level' do
  power_scheme_label 'Unrestricted'
  power_level 'ultimate'
  monitor_timeout 15
  disk_timeout 0
  standby_timeout 0
  hibernate_timeout 0
  action :set
end

windows_update_settings resource

windows_update_settings resource page

Use the windows_update_settings resource to manage the various Windows Update patching options.

New in Chef Infra Client 1.0.

Syntax

The full syntax for all of the properties that are available to the windows_update_settings resource is:

  add_to_target_wsus_group   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   use_custom_update_server   wsus_server_url   wsus_status_server_url   action windows_update_settings 'name' do true, false # default value: false Integer # default value: 4 true, false # default value: false true, false # default value: false Integer # default value: 22 true, false # default value: false true, false # default value: false true, false # default value: true true, false # default value: false true, false # default value: true String # default value: "Everyday" Integer String true, false # default value: true true, false # default value: false String String Symbol # defaults to :enable if not specified font-weight:700>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.
add_to_target_wsus_group, 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, use_custom_update_server, wsus_server_url, and wsus_status_server_url are the properties available to this resource.

Actions

The windows_update_settings resource has the following actions:

:enable: Overrides the default settings with these custom options.
: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_update_settings resource has the following properties:

add_to_target_wsus_group

Ruby Type: true, false | Default Value: false

If you have a WSUS Server and Target Groups, set this True

automatic_update_option

Ruby Type: Integer | Default Value: 4

An Integer value to tell nodes when and how to download updates. Default is 4 - Auto-download and schedule updates to install

automatically_install_minor_updates

Ruby Type: true, false | Default Value: false

Automatically install minor updates. Default is False

block_windows_update_website

Ruby Type: true, false | Default Value: false

Denies access to Windows Update to get updates

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

Prevents automatic updates. Defaults to False to allow automatic updates

disable_os_upgrades

Ruby Type: true, false | Default Value: false

True/False to disable OS upgrades.

elevate_non_admins

Ruby Type: true, false | Default Value: true

This property allows 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. Default is True

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. Defaults to Everyday

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

This is the name of the WSUS Target Group you want the node to be in

update_other_ms_products

Ruby Type: true, false | Default Value: true

Allows for other Microsoft products to get updates too

use_custom_update_server

Ruby Type: true, false | Default Value: false

Used to tell nodes to use a WSUS server, Defaults to False - Use Microsoft for updates

wsus_server_url

Ruby Type: String

The URL of your WSUS server if you use one

wsus_status_server_url

Ruby Type: String

URL for the WSUS Status server. It can be the same as the URL for the WSUS server itself

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

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]'

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]'

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

A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:

:before: Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed: Default. Specifies that a notification should be queued up, and then executed at the 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 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 return true in addition to 0.
A block is executed as Ruby code that must return either true or false. If the block returns true, the guard property is applied. If the block returns false, the guard property is not applied.

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.

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 false
  elevate_non_admins true
  add_to_target_wsus_group false
  block_windows_update_website false
  automatic_update_option 4
  automatically_install_minor_updates false
  enable_detection_frequency false
  custom_detection_frequency 22
  no_reboot_with_users_logged_on true
  disable_automatic_updates false
  scheduled_install_day 'Monday'
  scheduled_install_hour 20
  update_other_ms_products false
  use_custom_update_server false
  action :enable
end