Chef

Table Of Contents

registry_key

A resource defines the desired state for a single configuration item present on a node that is under management by Chef. A resource collection—one (or more) individual resources—defines the desired state for the entire node. During every chef-client run, the current state of each resource is tested, after which the chef-client will take any steps that are necessary to repair the node and bring it back into the desired state.

Use the registry_key resource to create and delete registry keys in Microsoft Windows.

64-bit versions of Microsoft Windows have a 32-bit compatibility layer in the registry that reflects and redirects certain keys (and their sub-keys) into specific locations. By default, the registry functionality will default to the machine architecture of the system that is being configured. The chef-client can access any reflected or redirected registry key. The chef-client can write to any 64-bit registry location. (This behavior is not affected by the chef-client running as a 32-bit application.) For more information, see: http://msdn.microsoft.com/en-us/library/windows/desktop/aa384235(v=vs.85).aspx.

Syntax

The syntax for using the registry_key resource in a recipe is as follows:

registry_key "name" do
  attribute "value" # see attributes section below
  ...
  values [{
    :name => "name",
    :type => :string,
    :data => "data"
    },
    {
    :name => "name",
    :type => :string,
    :data => "data"
    },
    ...
    ]
  action :action # see actions section below
end

where

  • registry_key tells the chef-client to use the Chef::Provider::Windows::Registry provider during the chef-client run

  • name is the name of the resource block; when the key attribute is not specified as part of a recipe, name is also path to the location in which a registry key is created or from which a registry key is deleted

  • attribute is zero (or more) of the attributes that are available for this resource

  • values is a hash that contains at least one registry key to be created or deleted. Each registry key in the hash is grouped by brackets in which the :name, :type, and :data values for that registry key are specified.

  • :type represents the values available for registry keys in Microsoft Windows. Use :binary for REG_BINARY, :string for REG_SZ, :multi_string for REG_MULTI_SZ, :expand_string for REG_EXPAND_SZ, :dword for REG_DWORD, :dword_big_endian for REG_DWORD_BIG_ENDIAN, or :qword for REG_QWORD.

    Warning

    :multi_string must be an array, even if there is only a single string.

  • :action is the step that the resource will ask the provider to take during the chef-client run

The following is an example of how the registry_key resource can work when used in a recipe. In this example, a Microsoft Windows registry key named “System” will get a new value called “NewRegistryKeyValue” and a multi-string value named “foo bar”:

registry_key "HKEY_LOCAL_MACHINE\\...\\System" do
  values [{
    :name => "NewRegistryKeyValue",
    :type => :multi_string,
    :data => ['foo\0bar\0\0']
  }]
  action :create
end

and the following example shows how multiple registry key entries can be configured using a single resource block with key values based on node attributes:

registry_key 'HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\name_of_registry_key' do
  values [{:name => 'key_name', :type => :string, :data => 'C:\Windows\System32\file_name.bmp'},
          {:name => 'key_name', :type => :string, :data => node['node_name']['attribute']['value']},
          {:name => 'key_name', :type => :string, :data => node['node_name']['attribute']['value']}
         ]
  action :create
end

Registry Key Path Separators

A Microsoft Windows registry key can be used as a string in Ruby code, such as when a registry key is used as the name of a recipe. In Ruby, when a registry key is enclosed in a double-quoted string (" "), the same backslash character (\) that is used to define the registry key path separator is also used in Ruby to define an escape character. Therefore, the registry key path separators must be escaped. For example, the following registry key:

HKCU\SOFTWARE\Policies\Microsoft\Windows\CurrentVersion\Themes

will not work when it is defined like this:

registry_key "HKCU\SOFTWARE\Policies\Microsoft\Windows\CurrentVersion\Themes" do
  ...
  action :some_action
end

but will work when the path separators are escaped properly:

registry_key "HKCU\\SOFTWARE\\Policies\\Microsoft\\Windows\\CurrentVersion\\Themes" do
  ...
  action :some_action
end

Recipe DSL Methods

The following methods can be used to interact with Microsoft Windows registry keys.

Methods Description
registry_data_exists? Find out if a registry key contains data.
registry_get_subkeys Get a list of sub-keys for a registry setting.
registry_get_values Get values (name, type, and data) for a given registry key.
registry_has_subkeys? Find out if a registry key has one (or more) sub-keys.
registry_key_exists? Find out if a registry key exists.
registry_value_exists? Find out if a registry key has values set (name, type, and data).

Note

The recommended order in which registry key-specific methods should be used within a recipe is: key_exists?, value_exists?, data_exists?, get_values, has_subkeys?, and then get_subkeys.

Actions

This resource has the following actions:

Action Description
:create Default. Use to create a registry key. If a registry key already exists (but does not match), use to update that registry key to match.
:create_if_missing Use to create a registry key if it does not exist. Also, use to create a registry key value if it does not exist.
:delete Use to delete the specified values for a registry key.
:delete_key Use to delete the specified registry key and all of its subkeys.

Note

Be careful when using the :delete_key action with the recursive attribute. This will delete the registry key, all of its subkeys and all of the values associated with them. This cannot be undone by the chef-client.

Attributes

This resource has the following attributes:

Attribute Description
architecture

The architecture of the node for which keys will be created or deleted. Possible values: :i386 (for nodes with a 32-bit registry), :x86_64 (for nodes with a 64-bit registry), and :machine (to have the chef-client determine the architecture during the chef-client run). Default value: :machine.

In order to read or write 32-bit registry keys on 64-bit machines running Microsoft Windows, the architecture attribute must be set to :i386. The :x86_64 value can be used to force writing to a 64-bit registry location, but this value is less useful than the default (:machine) because the chef-client will return an exception if :x86_64 is used and the machine turns out to be a 32-bit machine (whereas with :machine, the chef-client will be able to access the registry key on the 32-bit machine).

Note

The ARCHITECTURE attribute should only specify :x86_64 or :i386 when it is necessary to write 32-bit (:i386) or 64-bit (:x86_64) values on a 64-bit machine. ARCHITECTURE will default to :machine unless a specific value is given.

key

The path to the location in which a registry key will be created or from which a registry key will be deleted. Default value: the name of the resource block (see Syntax section above).

The path must include the registry hive, which can be specified either as its full name or as the 3- or 4-letter abbreviation. For example, both HKLM\SECURITY and HKEY_LOCAL_MACHINE\SECURITY are both valid and equivalent. The following hives are valid: HKEY_LOCAL_MACHINE, HKLM, HKEY_CURRENT_CONFIG, HKCC, HKEY_CLASSES_ROOT, HKCR, HKEY_USERS, HKU, HKEY_CURRENT_USER, and HKCU.

provider Optional. Use to specify a provider by using its long name. For example: provider Chef::Provider::Long::Name.
recursive

When creating a key, this value specifies that the required keys for the specified path will be created. When using the :delete_key action in a recipe, and if the registry key has subkeys, then the value for this attribute should be set to true.

Note

Be careful when using the :delete_key action with the recursive attribute. This will delete the registry key, all of its subkeys and all of the values associated with them. This cannot be undone by the chef-client.

values

An array of hashes, where each Hash contains the values that will be set under a registry key. Each Hash must contain :name, :type, and :data (and must contain no other key values).

:type represents the values available for registry keys in Microsoft Windows. Use :binary for REG_BINARY, :string for REG_SZ, :multi_string for REG_MULTI_SZ, :expand_string for REG_EXPAND_SZ, :dword for REG_DWORD, :dword_big_endian for REG_DWORD_BIG_ENDIAN, or :qword for REG_QWORD.

Warning

:multi_string must be an array, even if there is only a single string.

Providers

The chef-client will attempt to determine the correct provider during the chef-client run, and then choose the best/correct provider based on configuration data collected at the start of the chef-client run. In general, a specific provider does not need to be specified. In situations where a specific provider must be specified, there are two approaches:

  • Using a provider’s short name as the name of the resource, e.g. short_name "foo" do
  • Using the provider attribute to specify the long name as an attribute of a resource, e.g. provider Chef::Provider::Long::Name

Whenever possible, try using the short name first, and then use the long name when necessary.

This resource has the following providers:

Long name Short name Notes
Chef::Provider::Windows::Registry registry_key The default provider for the Microsoft Windows platform.

Examples

The following examples demonstrate various approaches for using resources in recipes. If you want to see examples of how Chef uses resources in recipes, take a closer look at the cookbooks that Chef authors and maintains: https://github.com/opscode-cookbooks.

Create a registry key

registry_key "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Policies\\System" do
  values [{
    :name => "EnableLUA",
    :type => :dword,
    :data => 0
  }]
  action :create
end

Delete a registry key value

registry_key "HKEY_LOCAL_MACHINE\\SOFTWARE\\Policies\\Microsoft\\Windows\\WindowsUpdate\\AU" do
  values [{
    :name => "NoAutoRebootWithLoggedOnUsers",
    :type => :dword
    }]
  action :delete
end

Delete a registry key and its subkeys, recursively

registry_key "HKCU\\SOFTWARE\\Policies\\Microsoft\\Windows\\CurrentVersion\\Themes" do
  recursive true
  action :delete_key
end

Note

Be careful when using the :delete_key action with the recursive attribute. This will delete the registry key, all of its subkeys and all of the values associated with them. This cannot be undone by the chef-client.

Use re-directed keys

In 64-bit versions of Microsoft Windows, HKEY_LOCAL_MACHINE\SOFTWARE\Example is a re-directed key. In the following examples, because HKEY_LOCAL_MACHINE\SOFTWARE\Example is a 32-bit key, the output will be “Found 32-bit key” if they are run on a version of Microsoft Windows that is 64-bit:

registry_key "HKEY_LOCAL_MACHINE\\SOFTWARE\\Example" do
  architecture :i386
  recursive true
  action :create
end

or:

registry_key "HKEY_LOCAL_MACHINE\\SOFTWARE\\Example" do
  architecture :x86_64
  recursive true
  action :delete_key
end

or:

ruby_block "check 32-bit" do
  block do
    puts "Found 32-bit key"
  end
  only_if { registry_key_exists?("HKEY_LOCAL_MACHINE\SOFTWARE\\Example", :i386) }
end

or:

ruby_block "check 64-bit" do
  block do
    puts "Found 64-bit key"
  end
  only_if { registry_key_exists?("HKEY_LOCAL_MACHINE\\SOFTWARE\\Example", :x86_64) }
end

Set proxy settings to be the same as those used by the chef-client

proxy = URI.parse(Chef::Config[:http_proxy])
registry_key 'HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings' do
  values [{:name => 'ProxyEnable', :type => :reg_dword, :data => 1},
          {:name => 'ProxyServer', :data => "#{proxy.host}:#{proxy.port}"},
          {:name => 'ProxyOverride', :type => :reg_string, :data => <local>},
         ]
  action :create
end