Ресурс registry_key

Редактировать эту страницу в репозитории Chef

Все страницы ресурсов Infra

Используйте ресурс registry_key для создания и удаления ключей реестра в Microsoft Windows.

Синтаксис

Блок ресурса registry_key создает и удаляет ключи реестра в Microsoft Windows:

registry_key 'HKEY_LOCAL_MACHINE\\...\\System' do
  values [{
    name: 'NewRegistryKeyValue',
    type: :multi_string,
    data: %w(foo bar baz),
  }]
  action :create
end

Используйте несколько записей ключей реестра со значениями ключей, основанными на атрибутах узла:

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 имеет следующий синтаксис:

registry_key 'name' do
  architecture      Symbol # default value: :machine
  key               String # default value: 'name' unless specified
  recursive         true, false # default value: false
  values
  action            Symbol # defaults to :create if not specified
end

где:

• registry_key является ресурсом
• name — имя блока ресурса
• values — массив, содержащий, как минимум, один ключ реестра для создания или удаления. Каждый ключ реестра в массиве сгруппирован в скобки, в которых указаны значения name:, type:, и data: для этого ключа реестра.

• type: представляет доступные значения для ключей реестра в Microsoft Windows. Используйте :binary для REG_BINARY, :string для REG_SZ, :multi_string для REG_MULTI_SZ, :expand_string для REG_EXPAND_SZ, :dword для REG_DWORD, :dword_big_endian для REG_DWORD_BIG_ENDIAN или :qword для REG_QWORD.

  Предупреждение

  :multi_string должен быть массивом, даже если существует только одна строка.
• action определяет действия Chef Infra Client для приведения узла в нужное состояние
• architecture, key, recursive и values — свойства этого ресурса со соответствующим типом Ruby. Подробную информацию о всех свойствах, которые можно использовать с этим ресурсом, см. в разделе «Свойства» ниже.

Разделители путей ключей реестра

Ключ реестра Microsoft Windows может использоваться как строка в коде Ruby, например, когда ключ реестра используется в качестве имени рецепта. В Ruby, когда ключ реестра заключён в двойные кавычки (" "), один и тот же обратный слэш (\), используемый для определения разделителя пути ключа реестра, также используется в Ruby для определения управляющего символа. Поэтому разделители путей ключа реестра должны быть экранированы, когда они заключены в двойные кавычки. Например, следующий ключ реестра:

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

можно заключить в одинарные кавычки с одним обратным слэшем:

'HKCU\SOFTWARE\path\to\key\Themes'

или заключить в двойные кавычки с дополнительным обратным слэшем как управляющим символом:

"HKCU\\SOFTWARE\\path\\to\\key\\Themes"

Методы языка Chef Infra

registry_data_exists?

Используйте метод registry_data_exists? для проверки наличия в ключе реестра Microsoft Windows указанных данных указанного типа в значении.

Синтаксис метода registry_data_exists? следующий:

registry_data_exists?(
  KEY_PATH,
  { name: 'NAME', type: TYPE, data: DATA },
  ARCHITECTURE
)

где:

• KEY_PATH — путь к значению ключа реестра. Путь должен включать в себя реестр, который можно указать либо полным именем, либо трех- или четырехбуквенным сокращением. Например, оба HKLM\SECURITY и HKEY_LOCAL_MACHINE\SECURITY являются допустимыми и эквивалентными. Допустимые реестры: HKEY_LOCAL_MACHINE, HKLM, HKEY_CURRENT_CONFIG, HKCC, HKEY_CLASSES_ROOT, HKCR, HKEY_USERS, HKU, HKEY_CURRENT_USER, и HKCU.
• { name: 'NAME', type: TYPE, data: DATA } — массив, содержащий ожидаемое имя, тип и данные значения ключа реестра
• type: представляет значения, доступные для ключей реестра в Microsoft Windows. Используйте :binary для REG_BINARY, :string для REG_SZ, :multi_string для REG_MULTI_SZ, :expand_string для REG_EXPAND_SZ, :dword для REG_DWORD, :dword_big_endian для REG_DWORD_BIG_ENDIAN или :qword для REG_QWORD.
• ARCHITECTURE — одно из следующих значений: :x86_64, :i386, или :machine. Установите в значение :i386 для чтения или записи 32-битных ключей реестра на 64-битных машинах под управлением Microsoft Windows. Установите в значение :x86_64 для принудительной записи в 64-битную позицию реестра, однако Chef Infra Client возвращает исключение, если :x86_64 используется на 32-битной машине. Установите в значение :machine для разрешения Chef Infra Client использовать соответствующее расположение ключа на основе архитектуры вашего узла. Значение по умолчанию: :machine.

Этот метод вернет true или false.

registry_get_subkeys

Используйте метод registry_get_subkeys для получения списка значений ключей реестра, присутствующих для ключа реестра Microsoft Windows.

Синтаксис метода registry_get_subkeys следующий:

subkey_array = registry_get_subkeys(KEY_PATH, ARCHITECTURE)

где:

• KEY_PATH — путь к ключу реестра. Путь должен включать в себя реестр, который можно указать либо полным именем, либо трех- или четырехбуквенным сокращением. Например, оба HKLM\SECURITY и HKEY_LOCAL_MACHINE\SECURITY являются допустимыми и эквивалентными. Допустимые реестры: HKEY_LOCAL_MACHINE, HKLM, HKEY_CURRENT_CONFIG, HKCC, HKEY_CLASSES_ROOT, HKCR, HKEY_USERS, HKU, HKEY_CURRENT_USER, и HKCU.
• ARCHITECTURE — одно из следующих значений: :x86_64, :i386, или :machine. Установите в значение :i386 для чтения или записи 32-битных ключей реестра на 64-битных машинах под управлением Microsoft Windows. Установите в значение :x86_64 для принудительной записи в 64-битную позицию реестра, однако Chef Infra Client возвращает исключение, если :x86_64 используется на 32-битной машине. Установите в значение :machine для разрешения Chef Infra Client использовать соответствующее расположение ключа на основе архитектуры вашего узла. Значение по умолчанию: :machine.

Это возвращает массив значений ключей реестра.

registry_get_values

Используйте метод registry_get_values для получения значений ключа реестра (имя, тип и данные) для ключа реестра Microsoft Windows.

Синтаксис метода registry_get_values следующий:

subkey_array = registry_get_values(KEY_PATH, ARCHITECTURE)

где:

• KEY_PATH — путь к ключу реестра. Путь должен включать раздел реестра, который можно указать либо полным именем, либо сокращением из 3 или 4 букв. Например, оба HKLM\SECURITY и HKEY_LOCAL_MACHINE\SECURITY являются допустимыми и эквивалентными. Допустимые разделы реестра: HKEY_LOCAL_MACHINE, HKLM, HKEY_CURRENT_CONFIG, HKCC, HKEY_CLASSES_ROOT, HKCR, HKEY_USERS, HKU, HKEY_CURRENT_USER, и HKCU.
• ARCHITECTURE — одно из следующих значений: :x86_64, :i386, или :machine. Установите значение :i386, чтобы читать или писать 32-битные ключи реестра на 64-битных машинах под управлением Microsoft Windows. Установите значение :x86_64, чтобы принудительно записать в 64-битное местоположение реестра, однако Chef Infra Client возвращает исключение, если :x86_64 используется на 32-битной машине. Установите значение :machine, чтобы позволить Chef Infra Client использовать соответствующее местоположение ключа в зависимости от архитектуры узла. Значение по умолчанию: :machine.

Это возвращает массив значений ключей реестра.

registry_has_subkeys?

Используйте метод registry_has_subkeys?, чтобы узнать, содержит ли ключ реестра Microsoft Windows одно (или несколько) значение(й).

Синтаксис для метода registry_has_subkeys? следующий:

registry_has_subkeys?(KEY_PATH, ARCHITECTURE)

где:

• KEY_PATH — путь к ключу реестра. Путь должен включать раздел реестра, который можно указать либо полным именем, либо сокращением из 3 или 4 букв. Например, оба HKLM\SECURITY и HKEY_LOCAL_MACHINE\SECURITY являются допустимыми и эквивалентными. Допустимые разделы реестра: HKEY_LOCAL_MACHINE, HKLM, HKEY_CURRENT_CONFIG, HKCC, HKEY_CLASSES_ROOT, HKCR, HKEY_USERS, HKU, HKEY_CURRENT_USER, и HKCU.
• ARCHITECTURE — одно из следующих значений: :x86_64, :i386, или :machine. Установите значение :i386, чтобы читать или писать 32-битные ключи реестра на 64-битных машинах под управлением Microsoft Windows. Установите значение :x86_64, чтобы принудительно записать в 64-битное местоположение реестра, однако Chef Infra Client возвращает исключение, если :x86_64 используется на 32-битной машине. Установите значение :machine, чтобы позволить Chef Infra Client использовать соответствующее местоположение ключа в зависимости от архитектуры узла. Значение по умолчанию: :machine.

Этот метод вернёт true или false.

registry_key_exists?

Используйте метод registry_key_exists?, чтобы узнать, существует ли ключ реестра Microsoft Windows по указанному пути.

Синтаксис для метода registry_key_exists? следующий:

registry_key_exists?(KEY_PATH, ARCHITECTURE)

где:

• KEY_PATH — путь к ключу реестра. Путь должен включать раздел реестра, который можно указать либо полным именем, либо сокращением из 3 или 4 букв. Например, оба HKLM\SECURITY и HKEY_LOCAL_MACHINE\SECURITY являются допустимыми и эквивалентными. Допустимые разделы реестра: HKEY_LOCAL_MACHINE, HKLM, HKEY_CURRENT_CONFIG, HKCC, HKEY_CLASSES_ROOT, HKCR, HKEY_USERS, HKU, HKEY_CURRENT_USER, и HKCU.
• ARCHITECTURE — одно из следующих значений: :x86_64, :i386, или :machine. Установите значение :i386, чтобы читать или писать 32-битные ключи реестра на 64-битных машинах под управлением Microsoft Windows. Установите значение :x86_64, чтобы принудительно записать в 64-битное местоположение реестра, однако Chef Infra Client возвращает исключение, если :x86_64 используется на 32-битной машине. Установите значение :machine, чтобы позволить Chef Infra Client использовать соответствующее местоположение ключа в зависимости от архитектуры узла. Значение по умолчанию: :machine.

Этот метод вернёт true или false. (Любые значения ключа реестра, связанные с этим ключом реестра, игнорируются.)

registry_value_exists?

Используйте метод registry_value_exists? для проверки наличия значения ключа реестра. Используйте registry_data_exists? для проверки типа и данных значения ключа реестра.

Синтаксис для метода registry_dvalue_exists? следующий:

registry_value_exists?(
  KEY_PATH,
  { name: 'NAME' },
  ARCHITECTURE
)

где:

• KEY_PATH — путь к ключу реестра. Путь должен включать раздел реестра, который можно указать либо полным именем, либо сокращением из 3 или 4 букв. Например, оба HKLM\SECURITY и HKEY_LOCAL_MACHINE\SECURITY являются допустимыми и эквивалентными. Допустимые разделы реестра: HKEY_LOCAL_MACHINE, HKLM, HKEY_CURRENT_CONFIG, HKCC, HKEY_CLASSES_ROOT, HKCR, HKEY_USERS, HKU, HKEY_CURRENT_USER, и HKCU.
• { name: 'NAME' } — хэш, содержащий имя значения ключа реестра; если в хэше указаны type: или :value, они игнорируются
• type: представляет доступные значения для ключей реестра в Microsoft Windows. Используйте :binary для REG_BINARY, :string для REG_SZ, :multi_string для REG_MULTI_SZ, :expand_string для REG_EXPAND_SZ, :dword для REG_DWORD, :dword_big_endian для REG_DWORD_BIG_ENDIAN или :qword для REG_QWORD.
• ARCHITECTURE — одно из следующих значений: :x86_64, :i386, или :machine. Установите значение :i386, чтобы читать или писать 32-битные ключи реестра на 64-битных машинах под управлением Microsoft Windows. Установите значение :x86_64, чтобы принудительно записать в 64-битное местоположение реестра, однако Chef Infra Client возвращает исключение, если :x86_64 используется на 32-битной машине. Установите значение :machine, чтобы позволить Chef Infra Client использовать соответствующее местоположение ключа в зависимости от архитектуры узла. Значение по умолчанию: :machine.

Этот метод вернёт true или false.

Действия

Ресурс registry_key имеет следующие действия:

:create

По умолчанию. Создаёт ключ реестра. Если ключ реестра уже существует (но не соответствует), обновляет этот ключ реестра для соответствия.

:create_if_missing

Создаёт ключ реестра, если он не существует. Также создаёт значение ключа реестра, если оно не существует.

:delete

Удаляет указанные значения для ключа реестра.

:delete_key

Удаляет указанный ключ реестра и все его подключаемые ключи. Действие :delete_key с атрибутом recursive удалит ключ реестра, все его значения и все имена, типы и данные, связанные с ними. Это действие невозможно отменить в Chef Infra Client.

:nothing

Этот блок ресурса не выполняет никаких действий, пока не получит уведомление от другого ресурса. После получения уведомления этот блок ресурса либо выполняется немедленно, либо помещается в очередь для выполнения в конце выполнения Chef Infra Client.

Свойства

Ресурс registry_key имеет следующие свойства:

architecture

Тип Ruby: Символ | Значение по умолчанию: :machine Допустимые значения: :i386, :machine, :x86_64

Архитектура узла, для которого создаются или удаляются ключи. Возможные значения: :i386 (для узлов с 32-битным реестром), :x86_64 (для узлов с 64-битным реестром) и :machine (для определения архитектуры Chef Infra Client во время выполнения).

Чтобы читать или писать 32-битные ключи реестра на 64-битных машинах под управлением Microsoft Windows, свойство architecture должно быть установлено в значение :i386. Значение :x86_64 можно использовать для принудительного записи в 64-битное местоположение реестра, но это значение менее полезно, чем значение по умолчанию (:machine), поскольку Chef Infra Client возвращает исключение, если :x86_64 используется, и машина оказывается 32-битной (в то время как с :machine, Chef Infra Client может получить доступ к ключу реестра на 32-битной машине).

key

Тип Ruby: Строка | Значение по умолчанию: The resource block's name

Путь к расположению, в котором должен быть создан ключ реестра или из которого должен быть удален ключ реестра. Значение по умолчанию: name блока ресурса. Более подробная информация приведена в разделе «Синтаксис» выше. Путь должен включать раздел реестра, который можно указать либо полным именем, либо сокращением из 3 или 4 букв. Например, оба HKLM\SECURITY и HKEY_LOCAL_MACHINE\SECURITY являются допустимыми и эквивалентными. Допустимые разделы реестра: HKEY_LOCAL_MACHINE, HKLM, HKEY_CURRENT_CONFIG, HKCC, HKEY_CLASSES_ROOT, HKCR, HKEY_USERS, HKU, HKEY_CURRENT_USER, и HKCU.

recursive

Тип Ruby: true, false | Значение по умолчанию: false

При создании ключа это значение указывает, что необходимые ключи для указанного пути должны быть созданы. При использовании действия :delete_key в рецепте, и если ключ реестра имеет подключа, то установите значение для этого свойства в true. Действие :delete_key с атрибутом recursive удалит ключ реестра, все его значения и все имена, типы и данные, связанные с ними. Это действие невозможно отменить с помощью Chef Infra Client.

values

Тип Ruby: Hash, Array

Массив хэшей, где каждый хэш содержит значения, которые должны быть установлены под ключом реестра. Каждый хэш должен содержать name:, type:, и data: (и не должен содержать других значений ключей).

type: представляет значения, доступные для ключей реестра в Microsoft Windows. Используйте :binary для REG_BINARY, :string для REG_SZ, :multi_string для REG_MULTI_SZ, :expand_string для REG_EXPAND_SZ, :dword для REG_DWORD, :dword_big_endian для REG_DWORD_BIG_ENDIAN или :qword для REG_QWORD.

Предупреждение

:multi_string должен быть массивом, даже если имеется только одна строка.

Примеры

Следующие примеры демонстрируют различные подходы к использованию ресурса registry_key в рецептах:

Создание ключа реестра

Использование строки в двойных кавычках:

registry_key "HKEY_LOCAL_MACHINE\\path-to-key\\Policies\\System" do
  values [{
    name: 'EnableLUA',
    type: :dword,
    data: 0
  }]
  action :create
end

или строки в одинарных кавычках:

registry_key 'HKEY_LOCAL_MACHINE\path-to-key\Policies\System' do
  values [{
    name: 'EnableLUA',
    type: :dword,
    data: 0
  }]
  action :create
end

Удаление значения ключа реестра

Использование строки в двойных кавычках:

registry_key "HKEY_LOCAL_MACHINE\\SOFTWARE\\path\\to\\key\\AU" do
  values [{
    name: 'NoAutoRebootWithLoggedOnUsers',
    type: :dword,
    data: ''
    }]
  action :delete
end

или строки в одинарных кавычках:

registry_key 'HKEY_LOCAL_MACHINE\SOFTWARE\path\to\key\AU' do
  values [{
    name: 'NoAutoRebootWithLoggedOnUsers',
    type: :dword,
    data: ''
    }]
  action :delete
end

Удаление ключа реестра и его подключа, рекурсивно

Использование строки в двойных кавычках:

registry_key "HKCU\\SOFTWARE\\Policies\\path\\to\\key\\Themes" do
  recursive true
  action :delete_key
end

или строки в одинарных кавычках:

registry_key 'HKCU\SOFTWARE\Policies\path\to\key\Themes' do
  recursive true
  action :delete_key
end

Использование перенаправленных ключей

В 64-битных версиях Microsoft Windows, HKEY_LOCAL_MACHINE\SOFTWARE\Example — это перенаправленный ключ. В следующих примерах, поскольку HKEY_LOCAL_MACHINE\SOFTWARE\Example — это 32-битный ключ, вывод будет «Найден 32-битный ключ», если они будут выполнены в 64-битной версии Microsoft Windows:

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

или:

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

или:

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

или:

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

Установка параметров прокси, совпадающих с теми, которые использует Chef Infra Client

Использование строки в двойных кавычках:

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

или строки в одинарных кавычках:

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

Установка имени ключа реестра в «(Default)»

Использование строки в двойных кавычках:

registry_key 'Set (Default) value' do
  key "HKLM\\Software\\Test\\Key\\Path"
  values [
    {name: '', type: :string, data: 'test'},
  ]
  action :create
end

или строки в одинарных кавычках:

registry_key 'Set (Default) value' do
  key 'HKLM\Software\Test\Key\Path'
  values [
    {name: '', type: :string, data: 'test'},
  ]
  action :create
end

где name: '' содержит пустую строку, что установит имя ключа реестра в (Default).