mirror of
https://github.com/ansible-collections/community.general.git
synced 2026-05-06 13:22:48 +00:00
Added win_reg_stat module (#19145)
This commit is contained in:
Jordan Borean
committed by
Matt Davis
Matt Davis
parent
2ac57e0bc3
commit
5cabe420ea
150
lib/ansible/modules/windows/win_reg_stat.ps1
Normal file
150
lib/ansible/modules/windows/win_reg_stat.ps1
Normal file
@@ -0,0 +1,150 @@
|
||||
#!powershell
|
||||
# This file is part of Ansible
|
||||
#
|
||||
# Ansible is free software: you can redistribute it and/or modify
|
||||
# it under the terms of the GNU General Public License as published by
|
||||
# the Free Software Foundation, either version 3 of the License, or
|
||||
# (at your option) any later version.
|
||||
#
|
||||
# Ansible is distributed in the hope that it will be useful,
|
||||
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
# GNU General Public License for more details.
|
||||
#
|
||||
# You should have received a copy of the GNU General Public License
|
||||
# along with Ansible. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
# WANT_JSON
|
||||
# POWERSHELL_COMMON
|
||||
|
||||
$ErrorActionPreference = "Stop"
|
||||
|
||||
$params = Parse-Args $args -supports_check_mode $true
|
||||
$key = Get-AnsibleParam $params "key" -FailIfEmpty $true
|
||||
$property = Get-AnsibleParam $params "property" -FailIfEmpty $false -default $null
|
||||
|
||||
$result = @{
|
||||
win_reg_stat = @{}
|
||||
changed = $false
|
||||
warnings = @()
|
||||
}
|
||||
|
||||
Function Get-NetHiveName($hive) {
|
||||
# Will also check that the hive passed in the path is a known hive
|
||||
switch ($hive.ToUpper()) {
|
||||
"HKCR" {"ClassesRoot"}
|
||||
"HKCC" {"CurrentConfig"}
|
||||
"HKCU" {"CurrentUser"}
|
||||
"HKLM" {"LocalMachine"}
|
||||
"HKU" {"Users"}
|
||||
default {"unsupported"}
|
||||
}
|
||||
}
|
||||
|
||||
Function Get-PropertyType($hive, $path, $property) {
|
||||
$type = (Get-Item REGISTRY::$hive\$path).GetValueKind($property)
|
||||
switch ($type) {
|
||||
"Binary" {"REG_BINARY"}
|
||||
"String" {"REG_SZ"}
|
||||
"DWord" {"REG_DWORD"}
|
||||
"QWord" {"REG_QWORD"}
|
||||
"MultiString" {"REG_MULTI_SZ"}
|
||||
"ExpandString" {"REG_EXPAND_SZ"}
|
||||
"None" {"REG_NONE"}
|
||||
default {"Unknown"}
|
||||
}
|
||||
}
|
||||
|
||||
Function Get-PropertyObject($hive, $net_hive, $path, $property) {
|
||||
$value = (Get-ItemProperty REGISTRY::$hive\$path).$property
|
||||
$type = Get-PropertyType -hive $hive -path $path -property $property
|
||||
If ($type -eq 'REG_EXPAND_SZ') {
|
||||
$raw_value = [Microsoft.Win32.Registry]::$net_hive.OpenSubKey($path).GetValue($property, $false, [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)
|
||||
} ElseIf ($type -eq 'REG_BINARY' -or $type -eq 'REG_NONE') {
|
||||
$raw_value = @()
|
||||
foreach ($byte in $value) {
|
||||
$hex_value = ('{0:x}' -f $byte).PadLeft(2, '0')
|
||||
$raw_value += "0x$hex_value"
|
||||
}
|
||||
} Else {
|
||||
$raw_value = $value
|
||||
}
|
||||
|
||||
$object = New-Object PSObject @{
|
||||
raw_value = $raw_value
|
||||
value = $value
|
||||
type = $type
|
||||
}
|
||||
|
||||
$object
|
||||
}
|
||||
|
||||
Function Test-RegistryProperty($hive, $path, $property) {
|
||||
Try {
|
||||
$type = (Get-Item REGISTRY::$hive\$path).GetValueKind($property)
|
||||
} Catch {
|
||||
$type = $null
|
||||
}
|
||||
|
||||
If ($type -eq $null) {
|
||||
$false
|
||||
} Else {
|
||||
$true
|
||||
}
|
||||
}
|
||||
|
||||
# Will validate the key parameter to make sure it matches known format
|
||||
if ($key -match "^([a-zA-Z_]*):\\(.*)$") {
|
||||
$hive = $matches[1]
|
||||
$path = $matches[2]
|
||||
} else {
|
||||
Fail-Json $result "key does not match format 'HIVE:\KEY_PATH'"
|
||||
}
|
||||
|
||||
# Used when getting the actual REG_EXPAND_SZ value as well as checking the hive is a known value
|
||||
$net_hive = Get-NetHiveName -hive $hive
|
||||
if ($net_hive -eq 'unsupported') {
|
||||
Fail-Json $result "the hive in key is '$hive'; must be 'HKCR', 'HKCC', 'HKCU', 'HKLM' or 'HKU'"
|
||||
}
|
||||
|
||||
if (Test-Path REGISTRY::$hive\$path) {
|
||||
if ($property -eq $null) {
|
||||
$property_info = @{}
|
||||
$properties = Get-ItemProperty REGISTRY::$hive\$path
|
||||
|
||||
foreach ($property in $properties.PSObject.Properties) {
|
||||
# Powershell adds in some metadata we need to filter out
|
||||
$real_property = Test-RegistryProperty -hive $hive -path $path -property $property.Name
|
||||
if ($real_property -eq $true) {
|
||||
$property_object = Get-PropertyObject -hive $hive -net_hive $net_hive -path $path -property $property.Name
|
||||
$property_info.Add($property.Name, $property_object)
|
||||
}
|
||||
}
|
||||
|
||||
$sub_keys = @()
|
||||
$sub_keys_raw = Get-ChildItem REGISTRY::$hive\$path -ErrorAction SilentlyContinue
|
||||
|
||||
foreach ($sub_key in $sub_keys_raw) {
|
||||
$sub_keys += $sub_key.PSChildName
|
||||
}
|
||||
|
||||
$result.win_reg_stat.exists = $true
|
||||
$result.win_reg_stat.sub_keys = $sub_keys
|
||||
$result.win_reg_stat.properties = $property_info
|
||||
} else {
|
||||
$exists = Test-RegistryProperty -hive $hive -path $path -property $property
|
||||
if ($exists -eq $true) {
|
||||
$propertyObject = Get-PropertyObject -hive $hive -net_hive $net_hive -path $path -property $property
|
||||
$result.win_reg_stat.exists = $true
|
||||
$result.win_reg_stat.raw_value = $propertyObject.raw_value
|
||||
$result.win_reg_stat.value = $propertyObject.value
|
||||
$result.win_reg_stat.type = $propertyObject.type
|
||||
} else {
|
||||
$result.win_reg_stat.exists = $false
|
||||
}
|
||||
}
|
||||
} else {
|
||||
$result.win_reg_stat.exists = $false
|
||||
}
|
||||
|
||||
Exit-Json $result
|
||||
120
lib/ansible/modules/windows/win_reg_stat.py
Normal file
120
lib/ansible/modules/windows/win_reg_stat.py
Normal file
@@ -0,0 +1,120 @@
|
||||
#!/usr/bin/python
|
||||
# -*- coding: utf-8 -*-
|
||||
|
||||
# (c) 2016, Ansible, inc
|
||||
#
|
||||
# This file is part of Ansible
|
||||
#
|
||||
# Ansible is free software: you can redistribute it and/or modify
|
||||
# it under the terms of the GNU General Public License as published by
|
||||
# the Free Software Foundation, either version 3 of the License, or
|
||||
# (at your option) any later version.
|
||||
#
|
||||
# Ansible is distributed in the hope that it will be useful,
|
||||
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
# GNU General Public License for more details.
|
||||
#
|
||||
# You should have received a copy of the GNU General Public License
|
||||
# along with Ansible. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
# this is a windows documentation stub. actual code lives in the .ps1
|
||||
# file of the same name
|
||||
|
||||
ANSIBLE_METADATA = {'status': ['preview'],
|
||||
'supported_by': 'community',
|
||||
'version': '1.0'}
|
||||
|
||||
DOCUMENTATION = r'''
|
||||
---
|
||||
module: win_reg_stat
|
||||
version_added: "2.3"
|
||||
short_description: returns information about a Windows registry key or property of a key
|
||||
description:
|
||||
- Like M(win_file), M(win_reg_stat) will return whether the key/property exists.
|
||||
- It also returns the sub keys and properties of the key specified.
|
||||
- If specifying a property name through I(property), it will return the information specific for that property.
|
||||
options:
|
||||
key:
|
||||
description:
|
||||
- The full registry key path including the hive to search for.
|
||||
required: true
|
||||
property:
|
||||
description:
|
||||
- The registry property name to get information for, the return json will not include the sub_keys and properties entries for the I(key) specified.
|
||||
required: false
|
||||
|
||||
author: "Jordan Borean (@jborean93)"
|
||||
'''
|
||||
|
||||
EXAMPLES = r'''
|
||||
# Obtain information about a registry key using short form
|
||||
- win_reg_stat:
|
||||
key: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion
|
||||
register: current_version
|
||||
|
||||
# Obtain information about a registry key property
|
||||
- win_reg_stat:
|
||||
key: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion
|
||||
property: CommonFilesDir
|
||||
register: common_files_dir
|
||||
'''
|
||||
|
||||
RETURN = r'''
|
||||
changed:
|
||||
description: Whether anything was changed.
|
||||
returned: always
|
||||
type: boolean
|
||||
sample: True
|
||||
win_reg_stat:
|
||||
description: Information about the registry key or property specified.
|
||||
returned: success
|
||||
type: dictionary
|
||||
contains:
|
||||
exists:
|
||||
description: States whether the registry key/property exists.
|
||||
returned: success and path/property exists
|
||||
type: boolean
|
||||
sample: True
|
||||
properties:
|
||||
description: A list of all the properties and their values in the key.
|
||||
returned: success, path exists and property not specified
|
||||
type: list
|
||||
sample: [
|
||||
"binary_property" : {
|
||||
"raw_value": ["0x01", "0x16"],
|
||||
"type": "REG_BINARY",
|
||||
"value": [1, 22]
|
||||
},
|
||||
"multi_string_property" : {
|
||||
"raw_value": ["a", "b"],
|
||||
"type": "REG_MULTI_SZ",
|
||||
"value": ["a", "b"]
|
||||
}
|
||||
]
|
||||
sub_keys:
|
||||
description: A list of all the sub keys of the key specified.
|
||||
returned: success, path exists and property not specified
|
||||
type: list
|
||||
sample: [
|
||||
"AppHost",
|
||||
"Casting",
|
||||
"DateTime"
|
||||
]
|
||||
raw_value:
|
||||
description: Returns the raw value of the registry property, REG_EXPAND_SZ has no string expansion, REG_BINARY or REG_NONE is in hex 0x format.
|
||||
REG_NONE, this value is a hex string in the 0x format.
|
||||
returned: success, path/property exists and property specified
|
||||
type: string
|
||||
sample: '%ProgramDir%\\Common Files'
|
||||
type:
|
||||
description: The property type.
|
||||
returned: success, path/property exists and property specified
|
||||
type: string
|
||||
sample: "REG_EXPAND_SZ"
|
||||
value:
|
||||
description: The value of the property.
|
||||
returned: success, path/property exists and property specified
|
||||
type: string
|
||||
sample: 'C:\\Program Files\\Common Files'
|
||||
'''
|
||||
Reference in New Issue
Block a user