diff --git a/lib/ansible/modules/windows/win_reg_stat.ps1 b/lib/ansible/modules/windows/win_reg_stat.ps1 index 8f8567c1885..1bdd0ee4b4a 100644 --- a/lib/ansible/modules/windows/win_reg_stat.ps1 +++ b/lib/ansible/modules/windows/win_reg_stat.ps1 @@ -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 diff --git a/lib/ansible/modules/windows/win_reg_stat.py b/lib/ansible/modules/windows/win_reg_stat.py index 4e9684769c5..652a5321d69 100644 --- a/lib/ansible/modules/windows/win_reg_stat.py +++ b/lib/ansible/modules/windows/win_reg_stat.py @@ -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' ''' diff --git a/test/integration/targets/win_reg_stat/tasks/main.yml b/test/integration/targets/win_reg_stat/tasks/main.yml index 82679edbbf2..a212b2b2ddb 100644 --- a/test/integration/targets/win_reg_stat/tasks/main.yml +++ b/test/integration/targets/win_reg_stat/tasks/main.yml @@ -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