diff --git a/lib/ansible/modules/files/acl.py b/lib/ansible/modules/files/acl.py index ebd46d53c9..6f3bbfaf60 100644 --- a/lib/ansible/modules/files/acl.py +++ b/lib/ansible/modules/files/acl.py @@ -27,12 +27,12 @@ short_description: Sets and retrieves file ACL information. description: - Sets and retrieves file ACL information. options: - name: + path: required: true default: null description: - The full path of the file or object. - aliases: ['path'] + aliases: ['name'] state: required: false @@ -54,7 +54,7 @@ options: default: no choices: [ 'yes', 'no' ] description: - - if the target is a directory, setting this to yes will make it the default acl for entities created inside the directory. It causes an error if name is a file. + - if the target is a directory, setting this to yes will make it the default acl for entities created inside the directory. It causes an error if path is a file. entity: version_added: "1.5" @@ -70,7 +70,6 @@ options: description: - the entity type of the ACL to apply, see setfacl documentation for more info. - permissions: version_added: "1.5" required: false @@ -97,12 +96,13 @@ author: notes: - The "acl" module requires that acls are enabled on the target filesystem and that the setfacl and getfacl binaries are installed. - As of Ansible 2.0, this module only supports Linux distributions. + - As of Ansible 2.3, the I(name) option has been changed to I(path) as default, but I(name) still works as well. ''' EXAMPLES = ''' # Grant user Joe read access to a file - acl: - name: /etc/foo.conf + path: /etc/foo.conf entity: joe etype: user permissions: r @@ -110,14 +110,14 @@ EXAMPLES = ''' # Removes the acl for Joe on a specific file - acl: - name: /etc/foo.conf + path: /etc/foo.conf entity: joe etype: user state: absent # Sets default acl for joe on foo.d - acl: - name: /etc/foo.d + path: /etc/foo.d entity: joe etype: user permissions: rw @@ -126,13 +126,13 @@ EXAMPLES = ''' # Same as previous but using entry shorthand - acl: - name: /etc/foo.d + path: /etc/foo.d entry: "default:user:joe:rw-" state: present # Obtain the acl for a specific file - acl: - name: /etc/foo.conf + path: /etc/foo.conf register: acl_info ''' @@ -144,6 +144,10 @@ acl: sample: [ "user::rwx", "group::rwx", "other::rwx" ] ''' +import os + +# import module snippets +from ansible.module_utils.basic import AnsibleModule, get_platform def split_entry(entry): ''' splits entry and ensures normalized return''' @@ -258,7 +262,7 @@ def run_acl(module, cmd, check_rc=True): def main(): module = AnsibleModule( argument_spec=dict( - name=dict(required=True, aliases=['path'], type='path'), + path=dict(required=True, aliases=['name'], type='path'), entry=dict(required=False, type='str'), entity=dict(required=False, type='str', default=''), etype=dict( @@ -284,7 +288,7 @@ def main(): if get_platform().lower() not in ['linux', 'freebsd']: module.fail_json(msg="The acl module is not available on this system.") - path = module.params.get('name') + path = module.params.get('path') entry = module.params.get('entry') entity = module.params.get('entity') etype = module.params.get('etype') @@ -369,8 +373,5 @@ def main(): module.exit_json(changed=changed, msg=msg, acl=acl) -# import module snippets -from ansible.module_utils.basic import * - if __name__ == '__main__': main() diff --git a/lib/ansible/modules/files/blockinfile.py b/lib/ansible/modules/files/blockinfile.py index 0956935994..e243c1352e 100755 --- a/lib/ansible/modules/files/blockinfile.py +++ b/lib/ansible/modules/files/blockinfile.py @@ -36,15 +36,13 @@ version_added: '2.0' description: - This module will insert/update/remove a block of multi-line text surrounded by customizable marker lines. -notes: - - This module supports check mode. - - When using 'with_*' loops be aware that if you do not set a unique mark the block will be overwritten on each iteration. options: - dest: - aliases: [ name, destfile ] + path: + aliases: [ dest, destfile, name ] required: true description: - The file to modify. + - Before 2.3 this option was only usable as I(dest), I(destfile) and I(name). state: required: false choices: [ present, absent ] @@ -104,12 +102,17 @@ options: description: - 'This flag indicates that filesystem links, if they exist, should be followed.' version_added: "2.1" +notes: + - This module supports check mode. + - When using 'with_*' loops be aware that if you do not set a unique mark the block will be overwritten on each iteration. + - As of Ansible 2.3, the I(dest) option has been changed to I(path) as default, but I(dest) still works as well. """ EXAMPLES = r""" +# Before 2.3, option 'dest' or 'name' was used instead of 'path' - name: insert/update "Match User" configuration block in /etc/ssh/sshd_config blockinfile: - dest: /etc/ssh/sshd_config + path: /etc/ssh/sshd_config block: | Match User ansible-agent PasswordAuthentication no @@ -117,7 +120,7 @@ EXAMPLES = r""" - name: insert/update eth0 configuration stanza in /etc/network/interfaces (it might be better to copy files into /etc/network/interfaces.d/) blockinfile: - dest: /etc/network/interfaces + path: /etc/network/interfaces block: | iface eth0 inet static address 192.0.2.23 @@ -125,7 +128,7 @@ EXAMPLES = r""" - name: insert/update HTML surrounded by custom markers after
line blockinfile: - dest: /var/www/html/index.html + path: /var/www/html/index.html marker: "" insertafter: "" content: | @@ -134,13 +137,13 @@ EXAMPLES = r""" - name: remove HTML as well as surrounding markers blockinfile: - dest: /var/www/html/index.html + path: /var/www/html/index.html marker: "" content: "" - name: Add mappings to /etc/hosts blockinfile: - dest: /etc/hosts + path: /etc/hosts block: | {{ item.ip }} {{ item.name }} marker: "# {mark} ANSIBLE MANAGED BLOCK {{ item.name }}" @@ -157,7 +160,7 @@ from ansible.module_utils.six import b from ansible.module_utils.basic import AnsibleModule from ansible.module_utils._text import to_bytes -def write_changes(module, contents, dest): +def write_changes(module, contents, path): tmpfd, tmpfile = tempfile.mkstemp() f = os.fdopen(tmpfd, 'wb') @@ -175,7 +178,7 @@ def write_changes(module, contents, dest): module.fail_json(msg='failed to validate: ' 'rc:%s error:%s' % (rc, err)) if valid: - module.atomic_move(tmpfile, dest, unsafe_writes=module.params['unsafe_writes']) + module.atomic_move(tmpfile, path, unsafe_writes=module.params['unsafe_writes']) def check_file_attrs(module, changed, message): @@ -194,7 +197,7 @@ def check_file_attrs(module, changed, message): def main(): module = AnsibleModule( argument_spec=dict( - dest=dict(required=True, aliases=['name', 'destfile'], type='path'), + path=dict(required=True, aliases=['dest', 'destfile', 'name'], type='path'), state=dict(default='present', choices=['absent', 'present']), marker=dict(default='# {mark} ANSIBLE MANAGED BLOCK', type='str'), block=dict(default='', type='str', aliases=['content']), @@ -210,23 +213,23 @@ def main(): ) params = module.params - dest = params['dest'] + path = params['path'] if module.boolean(params.get('follow', None)): - dest = os.path.realpath(dest) + path = os.path.realpath(path) - if os.path.isdir(dest): + if os.path.isdir(path): module.fail_json(rc=256, - msg='Destination %s is a directory !' % dest) + msg='Path %s is a directory !' % path) - path_exists = os.path.exists(dest) + path_exists = os.path.exists(path) if not path_exists: if not module.boolean(params['create']): module.fail_json(rc=257, - msg='Destination %s does not exist !' % dest) + msg='Path %s does not exist !' % path) original = None lines = [] else: - f = open(dest, 'rb') + f = open(path, 'rb') original = f.read() f.close() lines = original.splitlines() @@ -238,7 +241,7 @@ def main(): present = params['state'] == 'present' if not present and not path_exists: - module.exit_json(changed=False, msg="File not present") + module.exit_json(changed=False, msg="File %s not present" % path) if insertbefore is None and insertafter is None: insertafter = 'EOF' @@ -310,8 +313,8 @@ def main(): if changed and not module.check_mode: if module.boolean(params['backup']) and path_exists: - module.backup_local(dest) - write_changes(module, result, dest) + module.backup_local(path) + write_changes(module, result, path) if module.check_mode and not path_exists: module.exit_json(changed=changed, msg=msg) diff --git a/lib/ansible/modules/files/ini_file.py b/lib/ansible/modules/files/ini_file.py index 3bbce18409..5b0ef922de 100644 --- a/lib/ansible/modules/files/ini_file.py +++ b/lib/ansible/modules/files/ini_file.py @@ -36,11 +36,13 @@ description: - Before version 2.0, comments are discarded when the source file is read, and therefore will not show up in the destination file. version_added: "0.9" options: - dest: + path: description: - - Path to the INI-style file; this file is created if required + - Path to the INI-style file; this file is created if required. + - Before 2.3 this option was only usable as I(dest). required: true default: null + aliases: ['dest'] section: description: - Section name in INI file. This is added if C(state=present) automatically when @@ -94,15 +96,18 @@ options: notes: - While it is possible to add an I(option) without specifying a I(value), this makes no sense. + - As of Ansible 2.3, the I(dest) option has been changed to I(path) as default, but + I(dest) still works as well. author: - "Jan-Piet Mens (@jpmens)" - "Ales Nosek (@noseka1)" ''' EXAMPLES = ''' -# Ensure "fav=lemonade is in section "[drinks]" in specified file -- ini_file: - dest: /etc/conf +# Before 2.3, option 'dest' was used instead of 'path' +- name: Ensure "fav=lemonade is in section "[drinks]" in specified file + ini_file: + path: /etc/conf section: drinks option: fav value: lemonade @@ -110,7 +115,7 @@ EXAMPLES = ''' backup: yes - ini_file: - dest: /etc/anotherconf + path: /etc/anotherconf section: drinks option: temperature value: cold @@ -120,6 +125,9 @@ EXAMPLES = ''' import os import re +# import module snippets +from ansible.module_utils.basic import AnsibleModule + # ============================================================== # match_opt @@ -258,7 +266,7 @@ def main(): module = AnsibleModule( argument_spec = dict( - dest = dict(required=True), + path = dict(required=True, aliases=['dest'], type='path'), section = dict(required=True), option = dict(required=False), value = dict(required=False), @@ -271,7 +279,7 @@ def main(): supports_check_mode = True ) - dest = os.path.expanduser(module.params['dest']) + path = os.path.expanduser(module.params['path']) section = module.params['section'] option = module.params['option'] value = module.params['value'] @@ -280,20 +288,18 @@ def main(): no_extra_spaces = module.params['no_extra_spaces'] create = module.params['create'] - (changed,backup_file,diff,msg) = do_ini(module, dest, section, option, value, state, backup, no_extra_spaces, create) + (changed,backup_file,diff,msg) = do_ini(module, path, section, option, value, state, backup, no_extra_spaces, create) - if not module.check_mode and os.path.exists(dest): + if not module.check_mode and os.path.exists(path): file_args = module.load_file_common_arguments(module.params) changed = module.set_fs_attributes_if_different(file_args, changed) - results = { 'changed': changed, 'msg': msg, 'dest': dest, 'diff': diff } + results = { 'changed': changed, 'msg': msg, 'path': path, 'diff': diff } if backup_file is not None: results['backup_file'] = backup_file # Mission complete module.exit_json(**results) -# import module snippets -from ansible.module_utils.basic import * if __name__ == '__main__': main() diff --git a/lib/ansible/modules/files/lineinfile.py b/lib/ansible/modules/files/lineinfile.py index 28202aa4ac..25329b554d 100644 --- a/lib/ansible/modules/files/lineinfile.py +++ b/lib/ansible/modules/files/lineinfile.py @@ -42,11 +42,12 @@ description: For other cases, see the M(copy) or M(template) modules. version_added: "0.7" options: - dest: + path: required: true - aliases: [ name, destfile ] + aliases: [ 'dest', 'destfile', 'name' ] description: - The file to modify. + - Before 2.3 this option was only usable as I(dest), I(destfile) and I(name). regexp: required: false version_added: 1.7 @@ -121,21 +122,24 @@ options: description: - All arguments accepted by the M(file) module also work here. required: false +notes: + - As of Ansible 2.3, the I(dest) option has been changed to I(path) as default, but I(dest) still works as well. """ EXAMPLES = r""" +# Before 2.3, option 'dest', 'destfile' or 'name' was used instead of 'path' - lineinfile: - dest: /etc/selinux/config + path: /etc/selinux/config regexp: '^SELINUX=' line: 'SELINUX=enforcing' - lineinfile: - dest: /etc/sudoers + path: /etc/sudoers state: absent regexp: '^%wheel' - lineinfile: - dest: /etc/hosts + path: /etc/hosts regexp: '^127\.0\.0\.1' line: '127.0.0.1 localhost' owner: root @@ -143,39 +147,39 @@ EXAMPLES = r""" mode: 0644 - lineinfile: - dest: /etc/httpd/conf/httpd.conf + path: /etc/httpd/conf/httpd.conf regexp: '^Listen ' insertafter: '^#Listen ' line: 'Listen 8080' - lineinfile: - dest: /etc/services + path: /etc/services regexp: '^# port for http' insertbefore: '^www.*80/tcp' line: '# port for http by default' # Add a line to a file if it does not exist, without passing regexp - lineinfile: - dest: /tmp/testfile + path: /tmp/testfile line: '192.168.1.99 foo.lab.net foo' # Fully quoted because of the ': ' on the line. See the Gotchas in the YAML docs. -- lineinfile: - dest: /etc/sudoers +- lineinfile: " + path: /etc/sudoers state: present regexp: '^%wheel\s' line: '%wheel ALL=(ALL) NOPASSWD: ALL' # Yaml requires escaping backslashes in double quotes but not in single quotes - lineinfile: - dest: /opt/jboss-as/bin/standalone.conf - regexp: "^(.*)Xms(\\d+)m(.*)$" + path: /opt/jboss-as/bin/standalone.conf + regexp: '^(.*)Xms(\\d+)m(.*)$' line: '\1Xms${xms}m\3' backrefs: yes # Validate the sudoers file before saving - lineinfile: - dest: /etc/sudoers + path: /etc/sudoers state: present regexp: '^%ADMIN ALL=' line: '%ADMIN ALL=(ALL) NOPASSWD: ALL' @@ -412,7 +416,7 @@ def absent(module, dest, regexp, line, backup): def main(): module = AnsibleModule( argument_spec=dict( - dest=dict(required=True, aliases=['name', 'destfile'], type='path'), + path=dict(required=True, aliases=['dest', 'destfile', 'name'], type='path'), state=dict(default='present', choices=['absent', 'present']), regexp=dict(default=None), line=dict(aliases=['value']), @@ -432,11 +436,11 @@ def main(): create = params['create'] backup = params['backup'] backrefs = params['backrefs'] - dest = params['dest'] + path = params['path'] - b_dest = to_bytes(dest, errors='surrogate_or_strict') - if os.path.isdir(b_dest): - module.fail_json(rc=256, msg='Destination %s is a directory !' % dest) + b_path = to_bytes(path, errors='surrogate_or_strict') + if os.path.isdir(b_path): + module.fail_json(rc=256, msg='Path %s is a directory !' % path) if params['state'] == 'present': if backrefs and params['regexp'] is None: @@ -453,13 +457,13 @@ def main(): line = params['line'] - present(module, dest, params['regexp'], line, + present(module, path, params['regexp'], line, ins_aft, ins_bef, create, backup, backrefs) else: if params['regexp'] is None and params.get('line', None) is None: module.fail_json(msg='one of line= or regexp= is required with state=absent') - absent(module, dest, params['regexp'], params.get('line', None), backup) + absent(module, path, params['regexp'], params.get('line', None), backup) if __name__ == '__main__': main() diff --git a/lib/ansible/modules/files/replace.py b/lib/ansible/modules/files/replace.py index d0f6dfecd1..7e8a99139a 100644 --- a/lib/ansible/modules/files/replace.py +++ b/lib/ansible/modules/files/replace.py @@ -43,11 +43,12 @@ description: same pattern would never match any replacements made. version_added: "1.6" options: - dest: + path: required: true - aliases: [ name, destfile ] + aliases: [ dest, destfile, name ] description: - The file to modify. + - Before 2.3 this option was only usable as I(dest), I(destfile) and I(name). regexp: required: true description: @@ -80,30 +81,38 @@ options: version_added: "1.9" description: - 'This flag indicates that filesystem links, if they exist, should be followed.' +notes: + - As of Ansible 2.3, the I(dest) option has been changed to I(path) as default, but I(dest) still works as well. """ EXAMPLES = r""" +# Before 2.3, option 'dest', 'destfile' or 'name' was used instead of 'path' - replace: - dest: /etc/hosts + path: /etc/hosts regexp: '(\s+)old\.host\.name(\s+.*)?$' replace: '\1new.host.name\2' backup: yes - replace: - dest: /home/jdoe/.ssh/known_hosts + path: /home/jdoe/.ssh/known_hosts regexp: '^old\.host\.name[^\n]*\n' owner: jdoe group: jdoe mode: 0644 - replace: - dest: /etc/apache/ports + path: /etc/apache/ports regexp: '^(NameVirtualHost|Listen)\s+80\s*$' replace: '\1 127.0.0.1:8080' validate: '/usr/sbin/apache2ctl -f %s -t' """ -def write_changes(module,contents,dest): +import os + +# import module snippets +from ansible.module_utils.basic import AnsibleModule + +def write_changes(module, contents, path): tmpfd, tmpfile = tempfile.mkstemp() f = os.fdopen(tmpfd,'wb') @@ -121,7 +130,7 @@ def write_changes(module,contents,dest): module.fail_json(msg='failed to validate: ' 'rc:%s error:%s' % (rc,err)) if valid: - module.atomic_move(tmpfile, dest, unsafe_writes=module.params['unsafe_writes']) + module.atomic_move(tmpfile, path, unsafe_writes=module.params['unsafe_writes']) def check_file_attrs(module, changed, message): @@ -138,7 +147,7 @@ def check_file_attrs(module, changed, message): def main(): module = AnsibleModule( argument_spec=dict( - dest=dict(required=True, aliases=['name', 'destfile']), + path=dict(required=True, aliases=['dest', 'destfile', 'name'], type='path'), regexp=dict(required=True), replace=dict(default='', type='str'), backup=dict(default=False, type='bool'), @@ -149,16 +158,16 @@ def main(): ) params = module.params - dest = os.path.expanduser(params['dest']) + path = os.path.expanduser(params['path']) res_args = dict() - if os.path.isdir(dest): - module.fail_json(rc=256, msg='Destination %s is a directory !' % dest) + if os.path.isdir(path): + module.fail_json(rc=256, msg='Path %s is a directory !' % path) - if not os.path.exists(dest): - module.fail_json(rc=257, msg='Destination %s does not exist !' % dest) + if not os.path.exists(path): + module.fail_json(rc=257, msg='Path %s does not exist !' % path) else: - f = open(dest, 'rb') + f = open(path, 'rb') contents = to_text(f.read(), errors='surrogate_or_strict') f.close() @@ -170,9 +179,9 @@ def main(): changed = True if module._diff: res_args['diff'] = { - 'before_header': dest, + 'before_header': path, 'before': contents, - 'after_header': dest, + 'after_header': path, 'after': result[0], } else: @@ -180,17 +189,14 @@ def main(): changed = False if changed and not module.check_mode: - if params['backup'] and os.path.exists(dest): - res_args['backup_file'] = module.backup_local(dest) - if params['follow'] and os.path.islink(dest): - dest = os.path.realpath(dest) - write_changes(module, result[0], dest) + if params['backup'] and os.path.exists(path): + res_args['backup_file'] = module.backup_local(path) + if params['follow'] and os.path.islink(path): + path = os.path.realpath(path) + write_changes(module, result[0], path) res_args['msg'], res_args['changed'] = check_file_attrs(module, changed, msg) module.exit_json(**res_args) -# this is magic, see lib/ansible/module_common.py -from ansible.module_utils.basic import * - if __name__ == '__main__': main() diff --git a/lib/ansible/modules/files/xattr.py b/lib/ansible/modules/files/xattr.py index 0ae74efbaa..5179dd038d 100644 --- a/lib/ansible/modules/files/xattr.py +++ b/lib/ansible/modules/files/xattr.py @@ -27,12 +27,13 @@ description: - Manages filesystem user defined extended attributes, requires that they are enabled on the target filesystem and that the setfattr/getfattr utilities are present. options: - name: + path: required: true default: None - aliases: ['path'] + aliases: ['name'] description: - - The full path of the file/object to get the facts of + - The full path of the file/object to get the facts of. + - Before 2.3 this option was only usable as I(name). key: required: false default: None @@ -61,6 +62,8 @@ options: description: - if yes, dereferences symlinks and sets/gets attributes on symlink target, otherwise acts on symlink itself. +notes: + - As of Ansible 2.3, the I(name) option has been changed to I(path) as default, but I(name) still works as well. author: "Brian Coca (@bcoca)" ''' @@ -68,7 +71,7 @@ author: "Brian Coca (@bcoca)" EXAMPLES = ''' # Obtain the extended attributes of /etc/foo.conf - xattr: - name: /etc/foo.conf + path: /etc/foo.conf # Sets the key 'foo' to value 'bar' - xattr: @@ -78,7 +81,7 @@ EXAMPLES = ''' # Removes the key 'foo' - xattr: - name: /etc/foo.conf + path: /etc/foo.conf key: user.foo state: absent ''' @@ -87,6 +90,10 @@ import operator import re import os +# import module snippets +from ansible.module_utils.basic import AnsibleModule +from ansible.module_utils.pycompat24 import get_exception + def get_xattr_keys(module,path,follow): cmd = [ module.get_bin_path('getfattr', True) ] # prevents warning and not sure why it's not default @@ -156,7 +163,7 @@ def _run_xattr(module,cmd,check_rc=True): def main(): module = AnsibleModule( argument_spec = dict( - name = dict(required=True, aliases=['path'], type='path'), + path = dict(required=True, aliases=['name'], type='path'), key = dict(required=False, default=None, type='str'), value = dict(required=False, default=None, type='str'), state = dict(required=False, default='read', choices=[ 'read', 'present', 'all', 'keys', 'absent' ], type='str'), @@ -164,7 +171,7 @@ def main(): ), supports_check_mode=True, ) - path = module.params.get('name') + path = module.params.get('path') key = module.params.get('key') value = module.params.get('value') state = module.params.get('state') @@ -214,8 +221,5 @@ def main(): module.exit_json(changed=changed, msg=msg, xattr=res) -# import module snippets -from ansible.module_utils.basic import AnsibleModule -from ansible.module_utils.pycompat24 import get_exception if __name__ == '__main__': main() diff --git a/lib/ansible/modules/system/mount.py b/lib/ansible/modules/system/mount.py index b8fad7747b..14cc4fc809 100644 --- a/lib/ansible/modules/system/mount.py +++ b/lib/ansible/modules/system/mount.py @@ -20,16 +20,6 @@ # You should have received a copy of the GNU General Public License # along with Ansible. If not, see