diff --git a/CHANGELOG.md b/CHANGELOG.md index 4a136e12d7..24f1ea4c86 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,9 @@ Ansible Changes By Release ### Deprecations * Previously deprecated 'hostfile' config settings have been 're-deprecated' as previously code did not warn about deprecated configuration settings. * Using Ansible provided Jinja tests as filters is deprecated and will be removed in Ansible 2.9 +* `stat` and `win_stat` have deprecated `get_md5` and the `md5` return value + and these options will be removed in Ansible 2.9. `get_md5: no` will still be + allowed in 2.9 but will finally be removed 2 versions after that. ### Minor Changes * added a few new magic vars corresponding to configuration/command line options: @@ -28,6 +31,10 @@ Ansible Changes By Release * combine filter now accepts a list of dicts as well as dicts directly * New CLI options for ansible-inventory, ansible-console and ansible to allow specifying a playbook_dir to be used for relative search paths. +* `stat` and `win_stat` have changed the default value of `get_md5` to `False` which will result + in the `md5` return value not being returned. This option will be removed altogether in Ansible + 2.9. use `get_checksum: True` with `checksum_algorithm: md5` to return an md5 hash of the file + under the `checksum` return value. #### Deprecated Modules (to be removed in 2.9): * ec2_ami_find diff --git a/lib/ansible/modules/files/stat.py b/lib/ansible/modules/files/stat.py index 4a4269c5e0..d7e83b3671 100644 --- a/lib/ansible/modules/files/stat.py +++ b/lib/ansible/modules/files/stat.py @@ -25,26 +25,32 @@ options: follow: description: - Whether to follow symlinks. - choices: [ 'no', 'yes' ] + type: bool default: 'no' get_md5: description: - Whether to return the md5 sum of the file. - Will return None if not a regular file or if we're unable to use md5 (Common for FIPS-140 compliant systems). - choices: [ 'no', 'yes' ] - default: 'yes' + - The default of this option changed from C(yes) to C(no) in Ansible 2.5 + and will be removed altogether in Ansible 2.9. + - Use C(get_checksum=true) with C(checksum_algorithm=md5) to return an + md5 hash under the C(checksum) return value. + type: bool + default: 'no' get_checksum: description: - Whether to return a checksum of the file (default sha1). - choices: [ 'no', 'yes' ] + type: bool default: 'yes' version_added: "1.8" checksum_algorithm: description: - Algorithm to determine checksum of file. Will throw an error if the host is unable to use specified algorithm. - choices: [ sha1, sha224, sha256, sha384, sha512 ] + - The remote host has to support the hashing method specified, C(md5) + can be unavailable if the host is FIPS-140 compliant. + choices: [ md5, sha1, sha224, sha256, sha384, sha512 ] default: sha1 aliases: [ checksum, checksum_algo ] version_added: "2.0" @@ -54,14 +60,14 @@ options: the 'file' utility found on most Linux/Unix systems. - This will add both `mime_type` and 'charset' fields to the return, if possible. - In 2.3 this option changed from 'mime' to 'get_mime' and the default changed to 'Yes'. - choices: [ 'no', 'yes' ] + type: bool default: 'yes' version_added: "2.1" aliases: [ mime, mime_type, mime-type ] get_attributes: description: - Get file attributes using lsattr tool if present. - choices: [ 'no', 'yes' ] + type: bool default: 'yes' version_added: "2.3" aliases: [ attr, attributes ] @@ -294,7 +300,8 @@ stat: sample: ../foobar/21102015-1445431274-908472971 version_added: 2.4 md5: - description: md5 hash of the path + description: md5 hash of the path, this will be removed in Ansible 2.9 in + favour of the checksum return value returned: success, path exists and user can read stats and path supports hashing and md5 is supported type: string @@ -433,12 +440,12 @@ def main(): argument_spec=dict( path=dict(required=True, type='path'), follow=dict(type='bool', default='no'), - get_md5=dict(type='bool', default='yes'), + get_md5=dict(type='bool'), get_checksum=dict(type='bool', default='yes'), get_mime=dict(type='bool', default='yes', aliases=['mime', 'mime_type', 'mime-type']), get_attributes=dict(type='bool', default='yes', aliases=['attr', 'attributes']), checksum_algorithm=dict(type='str', default='sha1', - choices=['sha1', 'sha224', 'sha256', 'sha384', 'sha512'], + choices=['md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512'], aliases=['checksum', 'checksum_algo']), ), supports_check_mode=True, @@ -450,6 +457,14 @@ def main(): get_mime = module.params.get('get_mime') get_attr = module.params.get('get_attributes') get_md5 = module.params.get('get_md5') + + # get_md5 will be an undocumented option in 2.9 to be removed at a later + # date if possible (3.0+) + if get_md5: + module.deprecate("get_md5 has been deprecated along with the md5 return value, use " + "get_checksum=True and checksum_algorithm=md5 instead", 2.9) + else: + get_md5 = False get_checksum = module.params.get('get_checksum') checksum_algorithm = module.params.get('checksum_algorithm') diff --git a/lib/ansible/modules/windows/win_stat.ps1 b/lib/ansible/modules/windows/win_stat.ps1 index 103aa0802b..ec38116490 100644 --- a/lib/ansible/modules/windows/win_stat.ps1 +++ b/lib/ansible/modules/windows/win_stat.ps1 @@ -62,7 +62,7 @@ function Date_To_Timestamp($start_date, $end_date) $params = Parse-Args $args -supports_check_mode $true $path = Get-AnsibleParam -obj $params -name "path" -type "path" -failifempty $true -aliases "dest","name" -$get_md5 = Get-AnsibleParam -obj $params -name "get_md5" -type "bool" -default $true +$get_md5 = Get-AnsibleParam -obj $params -name "get_md5" -type "bool" -default $false $get_checksum = Get-AnsibleParam -obj $params -name "get_checksum" -type "bool" -default $true $checksum_algorithm = Get-AnsibleParam -obj $params -name "checksum_algorithm" -type "str" -default "sha1" -validateset "md5","sha1","sha256","sha384","sha512" @@ -73,9 +73,10 @@ $result = @{ } } -# Backward compatibility -if ($get_md5 -eq $true -and (Get-Member -inputobject $params -name "get_md5") ) { - Add-DeprecationWarning -obj $result -message "The parameter 'get_md5' is being replaced with 'checksum_algorithm: md5'" -version 2.7 +# get_md5 will be an undocumented option in 2.9 to be removed at a later +# date if possible (3.0+) +if (Get-Member -inputobject $params -name "get_md5") { + Add-DepreactionWarning -obj $result -message "get_md5 has been deprecated along with the md5 return value, use get_checksum=True and checksum_algorithm=md5 instead" -version 2.9 } $info = Get-FileItem -path $path @@ -159,7 +160,7 @@ If ($info -ne $null) try { $result.stat.md5 = Get-FileChecksum -path $path -algorithm "md5" } catch { - Fail-Json -obj $result -message "failed to get MD5 hash of file, set get_md5 to False to ignore this error: $($_.Exception.Message)" + Fail-Json -obj $result -message "failed to get MD5 hash of file, remove get_md5 to ignore this error: $($_.Exception.Message)" } } diff --git a/lib/ansible/modules/windows/win_stat.py b/lib/ansible/modules/windows/win_stat.py index a1c4cc4070..64b71d1ccd 100644 --- a/lib/ansible/modules/windows/win_stat.py +++ b/lib/ansible/modules/windows/win_stat.py @@ -42,28 +42,29 @@ options: and 2.2 this is no longer an MD5, but a SHA1 instead. As of Ansible 2.3 this is back to an MD5. Will return None if host is unable to use specified algorithm. - - This option is deprecated in Ansible 2.3 and is replaced with - C(checksum_algorithm=md5). - - This option will be removed in Ansible 2.7 - required: no - default: True + - The default of this option changed from C(yes) to C(no) in Ansible 2.5 + and will be removed altogether in Ansible 2.9. + - Use C(get_checksum=true) with C(checksum_algorithm=md5) to return an + md5 hash under the C(checksum) return value. + type: bool + default: 'no' get_checksum: description: - Whether to return a checksum of the file (default sha1) - required: no - default: True + type: bool + default: 'yes' version_added: "2.1" checksum_algorithm: description: - Algorithm to determine checksum of file. Will throw an error if the host is unable to use specified algorithm. - required: no default: sha1 choices: ['md5', 'sha1', 'sha256', 'sha384', 'sha512'] version_added: "2.3" notes: - For non-Windows targets, use the M(stat) module instead. -author: "Chris Church (@cchurch)" +author: +- Chris Church (@cchurch) ''' EXAMPLES = r''' @@ -200,8 +201,8 @@ stat: type: string sample: C:\temp md5: - description: The MD5 checksum of a file (Between Ansible 1.9 and 2.2 this was returned as a SHA1 hash), will be removed in 2.7 - returned: success, path exist, path is a file, get_md5 == True, md5 is supported + description: The MD5 checksum of a file (Between Ansible 1.9 and 2.2 this was returned as a SHA1 hash), will be removed in 2.9 + returned: success, path exist, path is a file, get_md5 == True type: string sample: 09cb79e8fc7453c84a07f644e441fd81623b7f98 owner: diff --git a/lib/ansible/plugins/action/__init__.py b/lib/ansible/plugins/action/__init__.py index ad6eb0bc25..b8806baed1 100644 --- a/lib/ansible/plugins/action/__init__.py +++ b/lib/ansible/plugins/action/__init__.py @@ -478,7 +478,6 @@ class ActionBase(with_metaclass(ABCMeta, object)): module_args = dict( path=path, follow=follow, - get_md5=False, get_checksum=checksum, checksum_algo='sha1', ) diff --git a/test/integration/targets/copy/tasks/tests.yml b/test/integration/targets/copy/tasks/tests.yml index 902ebf6148..2784febe80 100644 --- a/test/integration/targets/copy/tasks/tests.yml +++ b/test/integration/targets/copy/tasks/tests.yml @@ -76,6 +76,7 @@ - name: Check the stat results of the file stat: path: "{{ remote_file }}" + get_md5: yes register: stat_results - debug: diff --git a/test/integration/targets/stat/tasks/main.yml b/test/integration/targets/stat/tasks/main.yml index c1b21f0a36..9cb551e650 100644 --- a/test/integration/targets/stat/tasks/main.yml +++ b/test/integration/targets/stat/tasks/main.yml @@ -44,7 +44,7 @@ - "'isreg' in stat_result.stat" - "'issock' in stat_result.stat" - "'isuid' in stat_result.stat" - - "'md5' in stat_result.stat" + - "'md5' not in stat_result.stat" # Remove in 2.9 - "'checksum' in stat_result.stat" - "stat_result.stat.checksum == '2aae6c35c94fcfb415dbe95f408b9ce91ee846ed'" - "'mode' in stat_result.stat" @@ -63,9 +63,14 @@ - "'xoth' in stat_result.stat" - "'xusr' in stat_result.stat" +- name: check stat of file with get_md5 + stat: path={{output_dir}}/foo.txt get_md5=True + register: stat_result_with_md5 + when: ansible_fips|bool != True + - assert: that: - - "stat_result.stat.md5 == '5eb63bbbe01eeed093cb22bb8f5acdc3'" + - "stat_result_with_md5.stat.md5 == '5eb63bbbe01eeed093cb22bb8f5acdc3'" when: ansible_fips|bool != True - name: make a symlink @@ -144,7 +149,7 @@ - "'isreg' in stat_result.stat" - "'issock' in stat_result.stat" - "'isuid' in stat_result.stat" - - "'md5' in stat_result.stat" + - "'md5' not in stat_result.stat" - "'checksum' in stat_result.stat" - "stat_result.stat.checksum == '2aae6c35c94fcfb415dbe95f408b9ce91ee846ed'" - "'mode' in stat_result.stat" @@ -163,7 +168,15 @@ - "'xoth' in stat_result.stat" - "'xusr' in stat_result.stat" +- name: check stat of a symlink with follow on with get_md5 + stat: + path: "{{ output_dir }}/foo-link" + follow: True + get_md5: yes + register: stat_result_with_md5 + when: ansible_fips|bool != True + - assert: that: - - "stat_result.stat.md5 == '5eb63bbbe01eeed093cb22bb8f5acdc3'" + - "stat_result_with_md5.stat.md5 == '5eb63bbbe01eeed093cb22bb8f5acdc3'" when: ansible_fips|bool != True diff --git a/test/integration/targets/win_stat/tasks/tests.yml b/test/integration/targets/win_stat/tasks/tests.yml index be0e42c4ef..9146319b6d 100644 --- a/test/integration/targets/win_stat/tasks/tests.yml +++ b/test/integration/targets/win_stat/tasks/tests.yml @@ -21,15 +21,16 @@ - stat_file.stat.isshared == False - stat_file.stat.lastaccesstime == 1477984205 - stat_file.stat.lastwritetime == 1477984205 - - stat_file.stat.md5 == '900150983cd24fb0d6963f7d28e17f72' + - stat_file.stat.md5 is not defined - stat_file.stat.owner == 'BUILTIN\Administrators' - stat_file.stat.path == win_stat_dir + '\\nested\\file.ps1' - stat_file.stat.size == 3 -- name: test win_stat module on file without md5 +# get_md5 will be undocumented in 2.9, remove this test then +- name: test win_stat module on file with md5 win_stat: path: '{{win_stat_dir}}\nested\file.ps1' - get_md5: False + get_md5: True register: stat_file_md5 - name: check actual for file without md5 @@ -49,7 +50,7 @@ - stat_file_md5.stat.isshared == False - stat_file_md5.stat.lastaccesstime == 1477984205 - stat_file_md5.stat.lastwritetime == 1477984205 - - stat_file_md5.stat.md5 is not defined + - stat_file_md5.stat.md5 == '900150983cd24fb0d6963f7d28e17f72' - stat_file_md5.stat.owner == 'BUILTIN\Administrators' - stat_file_md5.stat.path == win_stat_dir + '\\nested\\file.ps1' - stat_file_md5.stat.size == 3 @@ -77,7 +78,7 @@ - stat_file_sha256.stat.isshared == False - stat_file_sha256.stat.lastaccesstime == 1477984205 - stat_file_sha256.stat.lastwritetime == 1477984205 - - stat_file_sha256.stat.md5 == '900150983cd24fb0d6963f7d28e17f72' + - stat_file_sha256.stat.md5 is not defined - stat_file_sha256.stat.owner == 'BUILTIN\Administrators' - stat_file_sha256.stat.path == win_stat_dir + '\\nested\\file.ps1' - stat_file_sha256.stat.size == 3 @@ -105,7 +106,7 @@ - stat_file_sha384.stat.isshared == False - stat_file_sha384.stat.lastaccesstime == 1477984205 - stat_file_sha384.stat.lastwritetime == 1477984205 - - stat_file_sha384.stat.md5 == '900150983cd24fb0d6963f7d28e17f72' + - stat_file_sha384.stat.md5 is not defined - stat_file_sha384.stat.owner == 'BUILTIN\Administrators' - stat_file_sha384.stat.path == win_stat_dir + '\\nested\\file.ps1' - stat_file_sha384.stat.size == 3 @@ -133,7 +134,7 @@ - stat_file_sha512.stat.isshared == False - stat_file_sha512.stat.lastaccesstime == 1477984205 - stat_file_sha512.stat.lastwritetime == 1477984205 - - stat_file_sha512.stat.md5 == '900150983cd24fb0d6963f7d28e17f72' + - stat_file_sha512.stat.md5 is not defined - stat_file_sha512.stat.owner == 'BUILTIN\Administrators' - stat_file_sha512.stat.path == win_stat_dir + '\\nested\\file.ps1' - stat_file_sha512.stat.size == 3 @@ -160,7 +161,7 @@ - stat_file_hidden.stat.isshared == False - stat_file_hidden.stat.lastaccesstime == 1477984205 - stat_file_hidden.stat.lastwritetime == 1477984205 - - stat_file_hidden.stat.md5 == '900150983cd24fb0d6963f7d28e17f72' + - stat_file_hidden.stat.md5 is not defined - stat_file_hidden.stat.owner == 'BUILTIN\Administrators' - stat_file_hidden.stat.path == win_stat_dir + '\\nested\\hidden.ps1' - stat_file_hidden.stat.size == 3 @@ -187,7 +188,7 @@ - stat_readonly.stat.isshared == False - stat_readonly.stat.lastaccesstime == 1477984205 - stat_readonly.stat.lastwritetime == 1477984205 - - stat_readonly.stat.md5 == '900150983cd24fb0d6963f7d28e17f72' + - stat_readonly.stat.md5 is not defined - stat_readonly.stat.owner == 'BUILTIN\Administrators' - stat_readonly.stat.path == win_stat_dir + '\\nested\\read-only.ps1' - stat_readonly.stat.size == 3 @@ -214,7 +215,7 @@ - stat_hard_link.stat.isshared == False - stat_hard_link.stat.lastaccesstime == 1477984205 - stat_hard_link.stat.lastwritetime == 1477984205 - - stat_hard_link.stat.md5 == '900150983cd24fb0d6963f7d28e17f72' + - stat_hard_link.stat.md5 is not defined - stat_hard_link.stat.owner == 'BUILTIN\Administrators' - stat_hard_link.stat.path == win_stat_dir + '\\nested\\hard-link.ps1' - stat_hard_link.stat.size == 3