Ресурс registry_key

Изменить эту страницу в репозитории Chef

Страница справки по ресурсам

Используйте ресурс 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. {{< warning >}} :multi_string должно быть массивом, даже если существует только одна строка. {{< /warning >}}
• 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"

Методы Recipe DSL

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 — путь к значению ключа реестра. Путь должен включать раздел реестра, который может быть указан либо полным именем, либо сокращением из 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: 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.

• 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 во время выполнения 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).