W3cubDocs

/Chef 18

Chef Infra Language: Reading Registry Keys

[edit on GitHub]

Six methods are present in the Chef Infra Language to help verify the registry during a Chef Infra Client run on the Microsoft 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.

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.

registry_data_exists?

Use the registry_data_exists? method to find out if a Microsoft Windows registry key contains the specified data of the specified type under the value.

Note

This method can be used in recipes and from within the 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, 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.
  • { name: 'NAME', type: TYPE, data: DATA } is a hash that contains the expected name, type, and data of the registry key value
  • 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.
  • 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 Microsoft 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 the registry_get_subkeys method to get a list of registry key values that are present for a Microsoft Windows registry key.

Note

This method can be used in recipes and from within the 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, 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.
  • 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 Microsoft 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 the registry_get_values method to get the registry key values (name, type, and data) for a Microsoft Windows registry key.

Note

This method can be used in recipes and from within the 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, 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.
  • 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 Microsoft 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 the registry_has_subkeys? method to find out if a Microsoft Windows registry key has one (or more) values.

Note

This method can be used in recipes and from within the 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, 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.
  • 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 Microsoft 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 the registry_key_exists? method to find out if a Microsoft Windows registry key exists at the specified path.

Note

This method can be used in recipes and from within the 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, 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.
  • 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 Microsoft 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 the registry_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

This method can be used in recipes and from within the 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, 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.
  • { name: 'NAME' } is a hash that contains the name of the registry key value; if either type: or :value are specified in the hash, they are ignored
  • 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.
  • 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 Microsoft 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.

© Chef Software, Inc.
Licensed under the Creative Commons Attribution 3.0 Unported License.
The Chef™ Mark and Chef Logo are either registered trademarks/service marks or trademarks/servicemarks of Chef, in the United States and other countries and are used with Chef Inc's permission.
We are not affiliated with, endorsed or sponsored by Chef Inc.
https://docs.chef.io/infra_language/registry_keys/