win_reg_stat change the module parameters for standardisation (#22732)

This commit is contained in:
Jordan Borean 2017-03-24 08:15:28 +10:00 committed by Matt Davis
parent 89b78cb5e8
commit f1ab879bb6
3 changed files with 175 additions and 189 deletions

View file

@ -19,14 +19,13 @@
$ErrorActionPreference = "Stop"
$params = Parse-Args $args -supports_check_mode $true
$params = Parse-Args -arguments $args -supports_check_mode $true
$key = Get-AnsibleParam -obj $params -name "key" -type "str" -failifempty $true
$property = Get-AnsibleParam -obj $params -name "property" -type "str"
$path = Get-AnsibleParam -obj $params -name "path" -type "str" -failifempty $true -aliases "key"
$name = Get-AnsibleParam -obj $params -name "name" -type "str" -aliases "entry","value"
$result = @{
changed = $false
win_reg_stat = @{}
}
Function Get-NetHiveName($hive) {
@ -94,57 +93,57 @@ Function Test-RegistryProperty($hive, $path, $property) {
}
# Will validate the key parameter to make sure it matches known format
if ($key -match "^([a-zA-Z_]*):\\(.*)$") {
if ($path -match "^([a-zA-Z_]*):\\(.*)$") {
$hive = $matches[1]
$path = $matches[2]
$reg_path = $matches[2]
} else {
Fail-Json $result "key does not match format 'HIVE:\KEY_PATH'"
Fail-Json $result "path 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'"
Fail-Json $result "the hive in path is '$hive'; must be 'HKCR', 'HKCC', 'HKCU', 'HKLM' or 'HKU'"
}
if (Test-Path REGISTRY::$hive\$path) {
if ($property -eq $null) {
if (Test-Path REGISTRY::$hive\$reg_path) {
if ($name -eq $null) {
$property_info = @{}
$properties = Get-ItemProperty REGISTRY::$hive\$path
$properties = Get-ItemProperty REGISTRY::$hive\$reg_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
$real_property = Test-RegistryProperty -hive $hive -path $reg_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_object = Get-PropertyObject -hive $hive -net_hive $net_hive -path $reg_path -property $property.Name
$property_info.Add($property.Name, $property_object)
}
}
$sub_keys = @()
$sub_keys_raw = Get-ChildItem REGISTRY::$hive\$path -ErrorAction SilentlyContinue
$sub_keys_raw = Get-ChildItem REGISTRY::$hive\$reg_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
$result.exists = $true
$result.sub_keys = $sub_keys
$result.properties = $property_info
} else {
$exists = Test-RegistryProperty -hive $hive -path $path -property $property
$exists = Test-RegistryProperty -hive $hive -path $reg_path -property $name
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
$propertyObject = Get-PropertyObject -hive $hive -net_hive $net_hive -path $reg_path -property $name
$result.exists = $true
$result.raw_value = $propertyObject.raw_value
$result.value = $propertyObject.value
$result.type = $propertyObject.type
} else {
$result.win_reg_stat.exists = $false
$result.exists = $false
}
}
} else {
$result.win_reg_stat.exists = $false
$result.exists = $false
}
Exit-Json $result

View file

@ -36,86 +36,81 @@ description:
- 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
path:
description: The full registry key path including the hive to search for.
required: true
aliases: [ key ]
name:
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
aliases: [ entry, value, property ]
author: "Jordan Borean (@jborean93)"
'''
EXAMPLES = r'''
# Obtain information about a registry key using short form
- win_reg_stat:
key: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion
path: 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
path: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion
name: 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'
description: Whether anything was changed.
returned: always
type: boolean
sample: True
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'
'''

View file

@ -1,4 +1,9 @@
---
- name: test
win_file:
path: "{{win_output_dir}}"
state: absent
- name: make sure win output dir exists
win_file:
path: "{{win_output_dir}}"
@ -20,44 +25,43 @@
win_command: powershell.exe $env:windir
register: win_dir_value
- name: expect failure when not passing in key option
- name: expect failure when not passing in path option
win_reg_stat:
property: a
name: a
register: actual
failed_when: "actual.msg != 'Missing required argument: key'"
failed_when: "actual.msg != 'Missing required argument: path'"
- name: expect failure when passing in an invalid hive
win_reg_stat:
key: ABCD:\test
path: ABCD:\test
register: actual
failed_when: actual.msg != "the hive in key is 'ABCD'; must be 'HKCR', 'HKCC', 'HKCU', 'HKLM' or 'HKU'"
failed_when: actual.msg != "the hive in path is 'ABCD'; must be 'HKCR', 'HKCC', 'HKCU', 'HKLM' or 'HKU'"
- name: get known nested reg key structure for testing with short hive form
win_reg_stat:
key: HKCU:\Test\nested
path: HKCU:\Test\nested
register: actual_short
- name: get known nested reg key structure for testing with quoted yaml
win_reg_stat:
key: "HKCU:\\Test\\nested"
path: "HKCU:\\Test\\nested"
register: actual_quoted
- name: set expected value for reg structure
set_fact:
expected:
changed: false
win_reg_stat:
exists: true
properties:
binary: { raw_value: ["0x01", "0x16"], type: 'REG_BINARY', value: [1, 22] }
dword: { raw_value: 1, type: 'REG_DWORD', value: 1 }
expand: { raw_value: '%windir%\dir', type: 'REG_EXPAND_SZ', value: "{{win_dir_value.stdout_lines[0]}}\\dir" }
multi: { raw_value: ['a, b', 'c'], type: 'REG_MULTI_SZ', value: ['a, b', 'c'] }
qword: { raw_value: 1, type: 'REG_QWORD', value: 1 }
string: { raw_value: 'test', type: 'REG_SZ', value: 'test' }
sub_keys:
- nest1
- nest2
exists: true
properties:
binary: { raw_value: ["0x01", "0x16"], type: 'REG_BINARY', value: [1, 22] }
dword: { raw_value: 1, type: 'REG_DWORD', value: 1 }
expand: { raw_value: '%windir%\dir', type: 'REG_EXPAND_SZ', value: "{{win_dir_value.stdout_lines[0]}}\\dir" }
multi: { raw_value: ['a, b', 'c'], type: 'REG_MULTI_SZ', value: ['a, b', 'c'] }
qword: { raw_value: 1, type: 'REG_QWORD', value: 1 }
string: { raw_value: 'test', type: 'REG_SZ', value: 'test' }
sub_keys:
- nest1
- nest2
- name: validate test
assert:
@ -67,21 +71,20 @@
- name: get known reg key with no sub keys but some properties
win_reg_stat:
key: HKCU:\Test\single
path: HKCU:\Test\single
register: actual
- name: set expected value for reg key with no sub keys but some properties
set_fact:
expected:
changed: false
win_reg_stat:
exists: true
properties:
none: { raw_value: [], type: 'REG_NONE', value: [] }
none1: { raw_value: ["0x00"], type: 'REG_NONE', value: [0] }
string1: { raw_value: '', type: 'REG_SZ', value: '' }
string2: { raw_value: 'abc123', type: 'REG_SZ', value: 'abc123' }
sub_keys: []
exists: true
properties:
none: { raw_value: [], type: 'REG_NONE', value: [] }
none1: { raw_value: ["0x00"], type: 'REG_NONE', value: [0] }
string1: { raw_value: '', type: 'REG_SZ', value: '' }
string2: { raw_value: 'abc123', type: 'REG_SZ', value: 'abc123' }
sub_keys: []
- name: validate test
assert:
@ -90,17 +93,16 @@
- name: get known reg key without sub keys and properties
win_reg_stat:
key: HKCU:\Test\nested\nest2
path: HKCU:\Test\nested\nest2
register: actual
- name: set expected value for reg key without sub keys or properties
set_fact:
expected:
changed: false
win_reg_stat:
exists: true
properties: {}
sub_keys: []
exists: true
properties: {}
sub_keys: []
register: expected
- name: validate test
@ -110,15 +112,14 @@
- name: get non-existant reg key
win_reg_stat:
key: HKCU:\Test\Thispathwillneverexist
path: HKCU:\Test\Thispathwillneverexist
register: actual
- name: set expected value for non-existant reg key
set_fact:
expected:
changed: false
win_reg_stat:
exists: false
exists: false
- name: validate test
assert:
@ -127,19 +128,18 @@
- name: get string property
win_reg_stat:
key: HKCU:\Test\nested
property: string
path: HKCU:\Test\nested
name: string
register: actual
- name: set expected string property
set_fact:
expected:
changed: false
win_reg_stat:
exists: true
raw_value: 'test'
type: 'REG_SZ'
value: 'test'
exists: true
raw_value: 'test'
type: 'REG_SZ'
value: 'test'
- name: validate test
assert:
@ -148,19 +148,18 @@
- name: get expand string property
win_reg_stat:
key: HKCU:\Test\nested
property: expand
path: HKCU:\Test\nested
name: expand
register: actual
- name: set expected expand string property
set_fact:
expected:
changed: false
win_reg_stat:
exists: true
raw_value: '%windir%\dir'
type: 'REG_EXPAND_SZ'
value: "{{win_dir_value.stdout_lines[0]}}\\dir"
exists: true
raw_value: '%windir%\dir'
type: 'REG_EXPAND_SZ'
value: "{{win_dir_value.stdout_lines[0]}}\\dir"
- name: validate test
assert:
@ -169,19 +168,18 @@
- name: get multi string property
win_reg_stat:
key: HKCU:\Test\nested
property: multi
path: HKCU:\Test\nested
name: multi
register: actual
- name: set expected multi string property
set_fact:
expected:
changed: false
win_reg_stat:
exists: true
raw_value: ['a, b', 'c']
type: 'REG_MULTI_SZ'
value: ['a, b', 'c']
exists: true
raw_value: ['a, b', 'c']
type: 'REG_MULTI_SZ'
value: ['a, b', 'c']
- name: validate test
assert:
@ -190,19 +188,18 @@
- name: get binary property
win_reg_stat:
key: HKCU:\Test\nested
property: binary
path: HKCU:\Test\nested
name: binary
register: actual
- name: set expected binary property
set_fact:
expected:
changed: false
win_reg_stat:
exists: true
raw_value: ["0x01", "0x16"]
type: 'REG_BINARY'
value: [1, 22]
exists: true
raw_value: ["0x01", "0x16"]
type: 'REG_BINARY'
value: [1, 22]
- name: validate test
assert:
@ -211,19 +208,18 @@
- name: get dword property
win_reg_stat:
key: HKCU:\Test\nested
property: dword
path: HKCU:\Test\nested
name: dword
register: actual
- name: set expected dword property
set_fact:
expected:
changed: false
win_reg_stat:
exists: true
raw_value: 1
type: 'REG_DWORD'
value: 1
exists: true
raw_value: 1
type: 'REG_DWORD'
value: 1
- name: validate test
assert:
@ -232,19 +228,18 @@
- name: get qword property
win_reg_stat:
key: HKCU:\Test\nested
property: qword
path: HKCU:\Test\nested
name: qword
register: actual
- name: set expected qword property
set_fact:
expected:
changed: false
win_reg_stat:
exists: true
raw_value: 1
type: 'REG_QWORD'
value: 1
exists: true
raw_value: 1
type: 'REG_QWORD'
value: 1
- name: validate test
assert:
@ -253,19 +248,18 @@
- name: get none property
win_reg_stat:
key: HKCU:\Test\single
property: none
path: HKCU:\Test\single
name: none
register: actual
- name: set expected none property
set_fact:
expected:
changed: false
win_reg_stat:
exists: true
raw_value: []
type: 'REG_NONE'
value: []
exists: true
raw_value: []
type: 'REG_NONE'
value: []
- name: validate test
assert:
@ -274,19 +268,18 @@
- name: get none with value property
win_reg_stat:
key: HKCU:\Test\single
property: none1
path: HKCU:\Test\single
name: none1
register: actual
- name: set expected none with value property
set_fact:
expected:
changed: false
win_reg_stat:
exists: true
raw_value: ["0x00"]
type: 'REG_NONE'
value: [0]
exists: true
raw_value: ["0x00"]
type: 'REG_NONE'
value: [0]
- name: validate test
assert:
@ -295,16 +288,15 @@
- name: get non-existance property
win_reg_stat:
key: HKCU:\Test\single
property: doesnotexist
path: HKCU:\Test\single
name: doesnotexist
register: actual
- name: set expected non-existance property
set_fact:
expected:
changed: false
win_reg_stat:
exists: false
exists: false
- name: validate test
assert:
@ -313,5 +305,5 @@
- name: remove registry entry
win_regedit:
key: HKCU:\Test
path: HKCU:\Test
state: absent