registry_key Resource
This page is generated from the Chef Infra Client source code.To suggest a change, edit the registry_key.rb file and submit a pull request to the Chef Infra Client repository.
Use the registry_key resource to create and delete registry keys in Microsoft Windows.
Note
64-bit versions of Microsoft Windows have a 32-bit compatibility layer in the registry that reflects and redirects certain keys (and their values) into specific locations (or logical views) of the registry hive.
Chef Infra Client can access any reflected or redirected registry key. The machine architecture of the system on which Chef Infra Client is running is used as the default (non-redirected) location. Access to the SysWow64 location is redirected must be specified. Typically, this is only necessary to ensure compatibility with 32-bit applications that are running on a 64-bit operating system.
For more information, see Microsoft’s documentation on Registry Reflection.
Syntax
A registry_key resource block creates and deletes registry keys in Microsoft Windows:
registry_key 'HKEY_LOCAL_MACHINE\\...\\System' do
values [{
name: 'NewRegistryKeyValue',
type: :multi_string,
data: %w(foo bar baz),
}]
action :create
end
Use multiple registry key entries with key values that are based on node attributes:
registry_key 'HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\name_of_registry_key' do
values [{name: 'key_name', type: :string, data: 'C:\Windows\System32\file_name.bmp'},
{name: 'key_name', type: :string, data: node['node_name']['attribute']['value']},
{name: 'key_name', type: :string, data: node['node_name']['attribute']['value']}
]
action :create
end
The full syntax for all of the properties that are available to the registry_key resource is:
registry_key 'name' do
architecture Symbol # default value: :machine
key String # default value: 'name' unless specified
recursive true, false # default value: false
values Hash, Array # default value: []
action Symbol # defaults to :create if not specified
end
where:
registry_key
is the resourcename
is the name of the resource blockvalues
is a hash that contains at least one registry key to be created or deleted. Each registry key in the hash is grouped by brackets in which thename:
,type:
, anddata:
values for that registry key are specified.type:
represents the values available for registry keys in Microsoft Windows::binary
for REG_BINARY:string
for REG_SZ:multi_string
for REG_MULTI_SZ:expand_string
for REG_EXPAND_SZ:dword
for REG_DWORD:dword_big_endian
for REG_DWORD_BIG_ENDIAN:qword
for REG_QWORD
Warning
:multi_string
must be an array, even if there is only a single string.action
identifies the steps Chef Infra Client will take to bring the node into the desired statearchitecture
,key
,recursive
andvalues
are properties of this resource, with the Ruby type shown. See “Properties” section below for more information about all of the properties that may be used with this resource.
Registry Key Path Separators
A Windows registry key can be used as a string in Ruby code,
such as when a registry key is used as the name of a recipe. In Ruby,
when a registry key is enclosed in a double-quoted string (" "
), the
same backslash character (\
) that is used to define the registry key
path separator is also used in Ruby to define an escape character.
Therefore, the registry key path separators must be escaped when they
are enclosed in a double-quoted string. For example, the following
registry key:
HKCU\SOFTWARE\Policies\Microsoft\Windows\CurrentVersion\Themes
may be enclosed in a single-quoted string with a single backslash:
'HKCU\SOFTWARE\path\to\key\Themes'
or may be enclosed in a double-quoted string with an extra backslash as an escape character:
"HKCU\\SOFTWARE\\path\\to\\key\\Themes"
Chef Infra Language Methods
Six methods are present in the Chef Infra Language to help verify the registry during a Chef Infra Client run on the Windows platform—registry_data_exists?
, registry_get_subkeys
,
registry_get_values
, registry_has_subkeys?
, registry_key_exists?
,
and registry_value_exists?
—these helpers ensure the
powershell_script resource is idempotent.registry_data_exists?
Use theregistry_data_exists?
method to find out if a Microsoft
Windows registry key contains the specified data of the specified type
under the value.Note
not_if
and
only_if
blocks in resources. This method is not designed to create or
modify a registry key. If a registry key needs to be modified, use the
registry_key resource.The syntax for the registry_data_exists?
method is as follows:
registry_data_exists?(
KEY_PATH,
{ name: 'NAME', type: TYPE, data: DATA },
ARCHITECTURE
)
where:
KEY_PATH
is the path to the registry key value. The path must include the registry hive, which can be specified either as its full name or as the 3- or 4-letter abbreviation. For example, bothHKLM\SECURITY
andHKEY_LOCAL_MACHINE\SECURITY
are both valid and equivalent. The following hives are valid:HKEY_LOCAL_MACHINE
,HKLM
,HKEY_CURRENT_CONFIG
,HKCC
,HKEY_CLASSES_ROOT
,HKCR
,HKEY_USERS
,HKU
,HKEY_CURRENT_USER
, andHKCU
.{ name: 'NAME', type: TYPE, data: DATA }
is a hash that contains the expected name, type, and data of the registry key valuetype:
represents the values available for registry keys in Windows. Use:binary
for REG_BINARY,:string
for REG_SZ,:multi_string
for REG_MULTI_SZ,:expand_string
for REG_EXPAND_SZ,:dword
for REG_DWORD,:dword_big_endian
for REG_DWORD_BIG_ENDIAN, or:qword
for REG_QWORD.ARCHITECTURE
is one of the following values::x86_64
,:i386
, or:machine
. Set to:i386
to read or write 32-bit registry keys on 64-bit machines running Windows. Set to:x86_64
to force write to a 64-bit registry location, however Chef Infra Client returns an exception if:x86_64
is used on a 32-bit machine. Set to:machine
to allow Chef Infra Client to allow Chef Infra Client to use the appropriate key location based on your node’s architecture. Default value::machine
.
This method will return true
or false
.
registry_get_subkeys
Use theregistry_get_subkeys
method to get a list of registry key
values that are present for a Windows registry key.Note
not_if
and
only_if
blocks in resources. This method is not designed to create or
modify a registry key. If a registry key needs to be modified, use the
registry_key resource.The syntax for the registry_get_subkeys
method is as follows:
subkey_array = registry_get_subkeys(KEY_PATH, ARCHITECTURE)
where:
KEY_PATH
is the path to the registry key. The path must include the registry hive, which can be specified either as its full name or as the 3- or 4-letter abbreviation. For example, bothHKLM\SECURITY
andHKEY_LOCAL_MACHINE\SECURITY
are both valid and equivalent. The following hives are valid:HKEY_LOCAL_MACHINE
,HKLM
,HKEY_CURRENT_CONFIG
,HKCC
,HKEY_CLASSES_ROOT
,HKCR
,HKEY_USERS
,HKU
,HKEY_CURRENT_USER
, andHKCU
.ARCHITECTURE
is one of the following values::x86_64
,:i386
, or:machine
. Set to:i386
to read or write 32-bit registry keys on 64-bit machines running Windows. Set to:x86_64
to force write to a 64-bit registry location, however Chef Infra Client returns an exception if:x86_64
is used on a 32-bit machine. Set to:machine
to allow Chef Infra Client to allow Chef Infra Client to use the appropriate key location based on your node’s architecture. Default value::machine
.
This returns an array of registry key values.
registry_get_values
Use theregistry_get_values
method to get the registry key values
(name, type, and data) for a Windows registry key.Note
not_if
and
only_if
blocks in resources. This method is not designed to create or
modify a registry key. If a registry key needs to be modified, use the
registry_key resource.The syntax for the registry_get_values
method is as follows:
subkey_array = registry_get_values(KEY_PATH, ARCHITECTURE)
where:
KEY_PATH
is the path to the registry key. The path must include the registry hive, which can be specified either as its full name or as the 3- or 4-letter abbreviation. For example, bothHKLM\SECURITY
andHKEY_LOCAL_MACHINE\SECURITY
are both valid and equivalent. The following hives are valid:HKEY_LOCAL_MACHINE
,HKLM
,HKEY_CURRENT_CONFIG
,HKCC
,HKEY_CLASSES_ROOT
,HKCR
,HKEY_USERS
,HKU
,HKEY_CURRENT_USER
, andHKCU
.ARCHITECTURE
is one of the following values::x86_64
,:i386
, or:machine
. Set to:i386
to read or write 32-bit registry keys on 64-bit machines running Windows. Set to:x86_64
to force write to a 64-bit registry location, however Chef Infra Client returns an exception if:x86_64
is used on a 32-bit machine. Set to:machine
to allow Chef Infra Client to allow Chef Infra Client to use the appropriate key location based on your node’s architecture. Default value::machine
.
This returns an array of registry key values.
registry_has_subkeys?
Use theregistry_has_subkeys?
method to find out if a Microsoft
Windows registry key has one (or more) values.Note
not_if
and
only_if
blocks in resources. This method is not designed to create or
modify a registry key. If a registry key needs to be modified, use the
registry_key resource.The syntax for the registry_has_subkeys?
method is as follows:
registry_has_subkeys?(KEY_PATH, ARCHITECTURE)
where:
KEY_PATH
is the path to the registry key. The path must include the registry hive, which can be specified either as its full name or as the 3- or 4-letter abbreviation. For example, bothHKLM\SECURITY
andHKEY_LOCAL_MACHINE\SECURITY
are both valid and equivalent. The following hives are valid:HKEY_LOCAL_MACHINE
,HKLM
,HKEY_CURRENT_CONFIG
,HKCC
,HKEY_CLASSES_ROOT
,HKCR
,HKEY_USERS
,HKU
,HKEY_CURRENT_USER
, andHKCU
.ARCHITECTURE
is one of the following values::x86_64
,:i386
, or:machine
. Set to:i386
to read or write 32-bit registry keys on 64-bit machines running Windows. Set to:x86_64
to force write to a 64-bit registry location, however Chef Infra Client returns an exception if:x86_64
is used on a 32-bit machine. Set to:machine
to allow Chef Infra Client to allow Chef Infra Client to use the appropriate key location based on your node’s architecture. Default value::machine
.
This method will return true
or false
.
registry_key_exists?
Use theregistry_key_exists?
method to find out if a Windows
registry key exists at the specified path.Note
not_if
and
only_if
blocks in resources. This method is not designed to create or
modify a registry key. If a registry key needs to be modified, use the
registry_key resource.The syntax for the registry_key_exists?
method is as follows:
registry_key_exists?(KEY_PATH, ARCHITECTURE)
where:
KEY_PATH
is the path to the registry key. The path must include the registry hive, which can be specified either as its full name or as the 3- or 4-letter abbreviation. For example, bothHKLM\SECURITY
andHKEY_LOCAL_MACHINE\SECURITY
are both valid and equivalent. The following hives are valid:HKEY_LOCAL_MACHINE
,HKLM
,HKEY_CURRENT_CONFIG
,HKCC
,HKEY_CLASSES_ROOT
,HKCR
,HKEY_USERS
,HKU
,HKEY_CURRENT_USER
, andHKCU
.ARCHITECTURE
is one of the following values::x86_64
,:i386
, or:machine
. Set to:i386
to read or write 32-bit registry keys on 64-bit machines running Windows. Set to:x86_64
to force write to a 64-bit registry location, however Chef Infra Client returns an exception if:x86_64
is used on a 32-bit machine. Set to:machine
to allow Chef Infra Client to allow Chef Infra Client to use the appropriate key location based on your node’s architecture. Default value::machine
.
This method will return true
or false
. (Any registry key values that
are associated with this registry key are ignored.)
registry_value_exists?
Use theregistry_value_exists?
method to find out if a registry key
value exists. Use registry_data_exists?
to test for the type and data
of a registry key value.Note
not_if
and
only_if
blocks in resources. This method is not designed to create or
modify a registry key. If a registry key needs to be modified, use the
registry_key resource.The syntax for the registry_dvalue_exists?
method is as follows:
registry_value_exists?(
KEY_PATH,
{ name: 'NAME' },
ARCHITECTURE
)
where:
KEY_PATH
is the path to the registry key. The path must include the registry hive, which can be specified either as its full name or as the 3- or 4-letter abbreviation. For example, bothHKLM\SECURITY
andHKEY_LOCAL_MACHINE\SECURITY
are both valid and equivalent. The following hives are valid:HKEY_LOCAL_MACHINE
,HKLM
,HKEY_CURRENT_CONFIG
,HKCC
,HKEY_CLASSES_ROOT
,HKCR
,HKEY_USERS
,HKU
,HKEY_CURRENT_USER
, andHKCU
.{ name: 'NAME' }
is a hash that contains the name of the registry key value; if eithertype:
or:value
are specified in the hash, they are ignoredtype:
represents the values available for registry keys in Windows. Use:binary
for REG_BINARY,:string
for REG_SZ,:multi_string
for REG_MULTI_SZ,:expand_string
for REG_EXPAND_SZ,:dword
for REG_DWORD,:dword_big_endian
for REG_DWORD_BIG_ENDIAN, or:qword
for REG_QWORD.ARCHITECTURE
is one of the following values::x86_64
,:i386
, or:machine
. Set to:i386
to read or write 32-bit registry keys on 64-bit machines running Windows. Set to:x86_64
to force write to a 64-bit registry location, however Chef Infra Client returns an exception if:x86_64
is used on a 32-bit machine. Set to:machine
to allow Chef Infra Client to allow Chef Infra Client to use the appropriate key location based on your node’s architecture. Default value::machine
.
This method will return true
or false
.
Actions
The registry_key resource has the following actions:
:create
- (default) Create a registry key. If a registry key already exists (but does not match), update that registry key to match.
:create_if_missing
- Create a registry key if it does not exist. Also, create a registry key value if it does not exist.
:delete
- Delete the specified values for a registry key.
:delete_key
- Delete the specified registry key and all of its subkeys. The
:delete_key
action with therecursive
attribute will delete the registry key, all of its values and all of the names, types, and data associated with them. This cannot be undone by Chef Infra Client. :nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The registry_key resource has the following properties:
architecture
- Ruby Type: Symbol | Default Value:
:machine
Allowed Values::i386, :machine, :x86_64
The architecture of the node for which keys are to be created or deleted. Possible values:
:i386
(for nodes with a 32-bit registry),:x86_64
(for nodes with a 64-bit registry), and:machine
(to have Chef Infra Client determine the architecture during a Chef Infra Client run).In order to read or write 32-bit registry keys on 64-bit machines running Microsoft Windows, the
architecture
property must be set to:i386
. The:x86_64
value can be used to force writing to a 64-bit registry location, but this value is less useful than the default (:machine
) because Chef Infra Client returns an exception if:x86_64
is used and the machine turns out to be a 32-bit machine (whereas with:machine
, Chef Infra Client is able to access the registry key on the 32-bit machine).
key
- Ruby Type: String | Default Value:
The resource block's name
The path to the location in which a registry key is to be created or from which a registry key is to be deleted. Default value: the
name
of the resource block. See “Syntax” section above for more information. The path must include the registry hive, which can be specified either as its full name or as the 3- or 4-letter abbreviation. For example, bothHKLM\SECURITY
andHKEY_LOCAL_MACHINE\SECURITY
are both valid and equivalent. The following hives are valid:HKEY_LOCAL_MACHINE
,HKLM
,HKEY_CURRENT_CONFIG
,HKCC
,HKEY_CLASSES_ROOT
,HKCR
,HKEY_USERS
,HKU
,HKEY_CURRENT_USER
, andHKCU
.
recursive
- Ruby Type: true, false | Default Value:
false
When creating a key, this value specifies that the required keys for the specified path are to be created. When using the
:delete_key
action in a recipe, and if the registry key has subkeys, then set the value for this property totrue
. The:delete_key
action with therecursive
attribute will delete the registry key, all of its values and all of the names, types, and data associated with them. This cannot be undone by Chef Infra Client.
values
- Ruby Type: Hash, Array | Default Value:
[]
An array of hashes, where each Hash contains the values that are to be set under a registry key. Each Hash must contain
name:
,type:
, anddata:
(and must contain no other key values).type:
represents the values available for registry keys in Microsoft Windows. Use:binary
for REG_BINARY,:string
for REG_SZ,:multi_string
for REG_MULTI_SZ,:expand_string
for REG_EXPAND_SZ,:dword
for REG_DWORD,:dword_big_endian
for REG_DWORD_BIG_ENDIAN, or:qword
for REG_QWORD.Warning
:multi_string
must be an array, even if there is only a single string.
Examples
The following examples demonstrate various approaches for using the registry_key resource in recipes:
Create a registry key:
registry_key 'HKEY_LOCAL_MACHINE\\path-to-key\\Policies\\System' do
values [{
name: 'EnableLUA',
type: :dword,
data: 0
}]
action :create
end
Create a registry key with binary data: “\x01\x02\x03”:
registry_key 'HKEY_CURRENT_USER\ChefTest' do
values [{
:name => "test",
:type => :binary,
:data => [0, 1, 2].map(&:chr).join
}]
action :create
end
Create 32-bit key in redirected wow6432 tree:
In 64-bit versions of Microsoft Windows, HKEY_LOCAL_MACHINE\SOFTWARE\Example is a re-directed key. In the following examples, because HKEY_LOCAL_MACHINE\SOFTWARE\Example is a 32-bit key, the output will be �Found 32-bit key� if they are run on a version of Microsoft Windows that is 64-bit:
registry_key 'HKEY_LOCAL_MACHINE\SOFTWARE\Example' do
architecture :i386
recursive true
action :create
end
Set proxy settings to be the same as those used by #{ChefUtils::Dist::Infra::PRODUCT}:
proxy = URI.parse(Chef::Config[:http_proxy])
registry_key 'HKCU\Software\Microsoft\path\to\key\Internet Settings' do
values [{name: 'ProxyEnable', type: :reg_dword, data: 1},
{name: 'ProxyServer', data: "#{proxy.host}:#{proxy.port}"},
{name: 'ProxyOverride', type: :reg_string, data: <local>},
]
action :create
end
Set the name of a registry key to “(Default)”:
registry_key 'Set (Default) value' do
key 'HKLM\Software\Test\Key\Path'
values [
{name: '', type: :string, data: 'test'},
]
action :create
end
Delete a registry key value:
registry_key 'HKEY_LOCAL_MACHINE\SOFTWARE\path\to\key\AU' do
values [{
name: 'NoAutoRebootWithLoggedOnUsers',
type: :dword,
data: ''
}]
action :delete
end
Note: If data is not specified, Chef Infra Client returns error: “Missing data key in RegistryKey values hash”.
Delete a registry key and its subkeys, recursively:
registry_key 'HKCU\SOFTWARE\Policies\path\to\key\Themes' do
recursive true
action :delete_key
end
Note: Be careful when using the :delete_key
action with the recursive attribute. This will delete the registry key, all of its values
and all of the names, types, and data associated with them. This cannot be undone by #{ChefUtils::Dist::Infra::PRODUCT}
.