From 30227ace9818655f1ef8306c459664d0f160fee2 Mon Sep 17 00:00:00 2001 From: Dag Wieers Date: Fri, 18 Jan 2019 03:24:47 +0100 Subject: [PATCH] Fix parameter types and other fixes (#50111) * Fix parameter types and other fixes * Fix issues after review * Fix Windows-references in system/files modules This PR includes: - Replacing version/v with just Ansible X.Y - Removing Windows-alternatives from notes * Update lib/ansible/modules/system/parted.py Co-Authored-By: dagwieers * Update lib/ansible/modules/system/service.py Co-Authored-By: dagwieers * Update lib/ansible/modules/system/service.py Co-Authored-By: dagwieers * Revert type change, move to separate PR * Update lib/ansible/modules/files/replace.py Co-Authored-By: dagwieers * Update lib/ansible/modules/files/replace.py Co-Authored-By: dagwieers * Update lib/ansible/modules/files/replace.py Co-Authored-By: dagwieers * Update lib/ansible/modules/files/replace.py Co-Authored-By: dagwieers * Update lib/ansible/modules/files/replace.py Co-Authored-By: dagwieers * Update lib/ansible/modules/files/replace.py Co-Authored-By: dagwieers --- lib/ansible/modules/files/acl.py | 34 +- lib/ansible/modules/files/archive.py | 40 +- lib/ansible/modules/files/assemble.py | 29 +- lib/ansible/modules/files/blockinfile.py | 9 +- lib/ansible/modules/files/copy.py | 33 +- lib/ansible/modules/files/fetch.py | 9 +- lib/ansible/modules/files/file.py | 45 +- lib/ansible/modules/files/find.py | 78 ++-- lib/ansible/modules/files/ini_file.py | 90 ++-- lib/ansible/modules/files/iso_extract.py | 10 +- lib/ansible/modules/files/lineinfile.py | 113 ++--- lib/ansible/modules/files/patch.py | 25 +- lib/ansible/modules/files/replace.py | 97 ++-- lib/ansible/modules/files/stat.py | 35 +- lib/ansible/modules/files/synchronize.py | 110 +++-- lib/ansible/modules/files/tempfile.py | 12 +- lib/ansible/modules/files/template.py | 16 +- lib/ansible/modules/files/unarchive.py | 30 +- lib/ansible/modules/files/xattr.py | 14 +- .../modules/net_tools/basics/get_url.py | 60 +-- lib/ansible/modules/net_tools/basics/slurp.py | 4 +- lib/ansible/modules/net_tools/basics/uri.py | 63 ++- lib/ansible/modules/system/aix_inittab.py | 20 +- lib/ansible/modules/system/aix_lvol.py | 33 +- lib/ansible/modules/system/alternatives.py | 37 +- lib/ansible/modules/system/at.py | 17 +- lib/ansible/modules/system/authorized_key.py | 94 ++-- lib/ansible/modules/system/awall.py | 40 +- lib/ansible/modules/system/beadm.py | 55 +-- lib/ansible/modules/system/capabilities.py | 16 +- lib/ansible/modules/system/firewalld.py | 6 +- lib/ansible/modules/system/group.py | 25 +- lib/ansible/modules/system/lvg.py | 24 +- lib/ansible/modules/system/pamd.py | 132 +++--- lib/ansible/modules/system/parted.py | 172 ++++--- lib/ansible/modules/system/ping.py | 4 +- lib/ansible/modules/system/reboot.py | 15 +- lib/ansible/modules/system/service.py | 44 +- lib/ansible/modules/system/svc.py | 8 +- lib/ansible/modules/system/timezone.py | 28 +- lib/ansible/modules/system/user.py | 434 ++++++++++-------- lib/ansible/modules/system/vdo.py | 118 +++-- test/sanity/validate-modules/ignore.txt | 9 - 43 files changed, 1222 insertions(+), 1065 deletions(-) diff --git a/lib/ansible/modules/files/acl.py b/lib/ansible/modules/files/acl.py index bd188515de..bed14d5cf1 100644 --- a/lib/ansible/modules/files/acl.py +++ b/lib/ansible/modules/files/acl.py @@ -22,8 +22,9 @@ options: path: description: - The full path of the file or object. - aliases: [ name ] + type: path required: yes + aliases: [ name ] state: description: - Define whether the ACL should be present or not. @@ -72,7 +73,7 @@ options: version_added: '2.0' use_nfsv4_acls: description: - - Use NFSv4 ACLs instead of POSIX ACLs. + - Use NFSv4 ACLs instead of POSIX ACLs. type: bool default: no version_added: '2.2' @@ -259,31 +260,28 @@ def run_acl(module, cmd, check_rc=True): def main(): module = AnsibleModule( argument_spec=dict( - path=dict(required=True, aliases=['name'], type='path'), - entry=dict(required=False, type='str'), - entity=dict(required=False, type='str', default=''), + path=dict(type='path', required=True, aliases=['name']), + entry=dict(type='str'), + entity=dict(type='str', default=''), etype=dict( - required=False, - choices=['other', 'user', 'group', 'mask'], - type='str' + type='str', + choices=['group', 'mask', 'other', 'user'], ), - permissions=dict(required=False, type='str'), + permissions=dict(type='str'), state=dict( - required=False, + type='str', default='query', - choices=['query', 'present', 'absent'], - type='str' + choices=['absent', 'present', 'query'], ), - follow=dict(required=False, type='bool', default=True), - default=dict(required=False, type='bool', default=False), - recursive=dict(required=False, type='bool', default=False), + follow=dict(type='bool', default=True), + default=dict(type='bool', default=False), + recursive=dict(type='bool', default=False), recalculate_mask=dict( - required=False, + type='str', default='default', choices=['default', 'mask', 'no_mask'], - type='str' ), - use_nfsv4_acls=dict(required=False, type='bool', default=False) + use_nfsv4_acls=dict(type='bool', default=False) ), supports_check_mode=True, ) diff --git a/lib/ansible/modules/files/archive.py b/lib/ansible/modules/files/archive.py index 9db864f80d..1ca3612b9f 100644 --- a/lib/ansible/modules/files/archive.py +++ b/lib/ansible/modules/files/archive.py @@ -13,49 +13,57 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['preview'], 'supported_by': 'community'} -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- module: archive version_added: '2.3' short_description: Creates a compressed archive of one or more files or trees extends_documentation_fragment: files description: - - Packs an archive. It is the opposite of M(unarchive). By default, it assumes the compression source exists on the target. It will not copy the - source file from the local system to the target before archiving. Source files can be deleted after archival by specifying I(remove=True). + - Packs an archive. + - It is the opposite of M(unarchive). + - By default, it assumes the compression source exists on the target. + - It will not copy the source file from the local system to the target before archiving. + - Source files can be deleted after archival by specifying I(remove=True). options: path: description: - Remote absolute path, glob, or list of paths or globs for the file or files to compress or archive. + type: list required: true format: description: - The type of compression to use. - - Support for xz was added in version 2.5. + - Support for xz was added in Ansible 2.5. + type: str choices: [ bz2, gz, tar, xz, zip ] default: gz dest: description: - - The file name of the destination archive. This is required when C(path) refers to multiple files by either specifying a glob, a directory or - multiple paths in a list. + - The file name of the destination archive. + - This is required when C(path) refers to multiple files by either specifying a glob, a directory or multiple paths in a list. + type: path exclude_path: - version_added: '2.4' description: - - Remote absolute path, glob, or list of paths or globs for the file or files to exclude from the archive + - Remote absolute path, glob, or list of paths or globs for the file or files to exclude from the archive. + type: str + version_added: '2.4' remove: description: - Remove any added source files and trees after adding to archive. type: bool - default: 'no' - + default: no +notes: + - Requires tarfile, zipfile, gzip and bzip2 packages on target host. + - Requires lzma or backports.lzma if using xz format. + - Can produce I(gzip), I(bzip2), I(lzma) and I(zip) compressed files or archives. +seealso: +- module: unarchive author: - Ben Doherty (@bendoh) -notes: - - requires tarfile, zipfile, gzip and bzip2 packages on target host - - requires lzma or backports.lzma if using xz format - - can produce I(gzip), I(bzip2), I(lzma) and I(zip) compressed files or archives ''' -EXAMPLES = ''' +EXAMPLES = r''' - name: Compress directory /path/to/foo/ into /path/to/foo.tgz archive: path: /path/to/foo @@ -99,7 +107,7 @@ EXAMPLES = ''' format: bz2 ''' -RETURN = ''' +RETURN = r''' state: description: The current state of the archived file. diff --git a/lib/ansible/modules/files/assemble.py b/lib/ansible/modules/files/assemble.py index ce92191e08..04538733e8 100644 --- a/lib/ansible/modules/files/assemble.py +++ b/lib/ansible/modules/files/assemble.py @@ -29,16 +29,17 @@ description: - This module is also supported for Windows targets. notes: - This module is also supported for Windows targets. -- See also M(copy) and M(template). version_added: '0.5' options: src: description: - An already existing directory full of source files. + type: path required: true dest: description: - A file to create using the concatenation of all of the source files. + type: path required: true backup: description: @@ -50,13 +51,14 @@ options: delimiter: description: - A delimiter to separate the file contents. + type: str version_added: '1.4' remote_src: description: - If C(no), it will search for src at originating/master machine. - If C(yes), it will go to the remote/target machine for the src. type: bool - default: yes + default: no version_added: '1.4' regexp: description: @@ -64,6 +66,7 @@ options: - If not set, all files are assembled. - Every "\" (backslash) must be escaped as "\\" to comply to YAML syntax. - Uses L(Python regular expressions,http://docs.python.org/2/library/re.html). + type: str ignore_hidden: description: - A boolean that controls if files that start with a '.' will be included or not. @@ -75,15 +78,17 @@ options: - The validation command to run before copying into place. - The path to the file to validate is passed in via '%s' which must be present as in the sshd example below. - The command is passed securely so shell features like expansion and pipes won't work. + type: str version_added: '2.0' seealso: - module: copy +- module: template - module: win_copy author: - Stephen Fromm (@sfromm) extends_documentation_fragment: -- files - decrypt +- files ''' EXAMPLES = r''' @@ -102,7 +107,7 @@ EXAMPLES = r''' assemble: src: /etc/ssh/conf.d/ dest: /etc/ssh/sshd_config - validate: '/usr/sbin/sshd -t -f %s' + validate: /usr/sbin/sshd -t -f %s ''' import codecs @@ -173,14 +178,14 @@ def main(): module = AnsibleModule( # not checking because of daisy chain to file module argument_spec=dict( - src=dict(required=True, type='path'), - delimiter=dict(required=False), - dest=dict(required=True, type='path'), - backup=dict(default=False, type='bool'), - remote_src=dict(default=False, type='bool'), - regexp=dict(required=False), - ignore_hidden=dict(default=False, type='bool'), - validate=dict(required=False, type='str'), + src=dict(type='path', required=True), + delimiter=dict(type='str'), + dest=dict(type='path', required=True), + backup=dict(type='bool', default=False), + remote_src=dict(type='bool', default=False), + regexp=dict(type='str'), + ignore_hidden=dict(type='bool', default=False), + validate=dict(type='str'), ), add_file_common_args=True, ) diff --git a/lib/ansible/modules/files/blockinfile.py b/lib/ansible/modules/files/blockinfile.py index dc6a9e76e8..1b5f1dab29 100644 --- a/lib/ansible/modules/files/blockinfile.py +++ b/lib/ansible/modules/files/blockinfile.py @@ -18,8 +18,7 @@ module: blockinfile short_description: Insert/update/remove a text block surrounded by marker lines version_added: '2.0' description: -- This module will insert/update/remove a block of multi-line text - surrounded by customizable marker lines. +- This module will insert/update/remove a block of multi-line text surrounded by customizable marker lines. author: - Yaegashi Takeshi (@yaegashi) options: @@ -27,8 +26,8 @@ options: description: - The file to modify. - Before Ansible 2.3 this option was only usable as I(dest), I(destfile) and I(name). - required: yes type: path + required: yes aliases: [ dest, destfile, name ] state: description: @@ -48,16 +47,16 @@ options: - The text to insert inside the marker lines. - If it is missing or an empty string, the block will be removed as if C(state) were specified to C(absent). type: str - aliases: [ content ] default: '' + aliases: [ content ] insertafter: description: - If specified, the block will be inserted after the last match of specified regular expression. - A special value is available; C(EOF) for inserting the block at the end of the file. - If specified regular expression has no matches, C(EOF) will be used instead. type: str - default: EOF choices: [ EOF, '*regex*' ] + default: EOF insertbefore: description: - If specified, the block will be inserted before the last match of specified regular expression. diff --git a/lib/ansible/modules/files/copy.py b/lib/ansible/modules/files/copy.py index 56521348cf..968d1477c6 100644 --- a/lib/ansible/modules/files/copy.py +++ b/lib/ansible/modules/files/copy.py @@ -19,8 +19,6 @@ version_added: historical short_description: Copy files to remote locations description: - The C(copy) module copies a file from the local or remote machine to a location on the remote machine. - - Use the M(fetch) module to copy files from remote locations to the local box. - - If you need variable interpolation in copied files, use the M(template) module. - For Windows targets, use the M(win_copy) module instead. options: src: @@ -31,10 +29,12 @@ options: with "/", only inside contents of that directory are copied to destination. Otherwise, if it does not end with "/", the directory itself with all contents is copied. This behavior is similar to the C(rsync) command line tool. + type: path content: description: - When used instead of I(src), sets the contents of a file directly to the specified value. - For anything advanced or with formatting also look at the template module. + type: str version_added: '1.1' dest: description: @@ -42,6 +42,7 @@ options: - If I(src) is a directory, this must be a directory too. - If I(dest) is a non-existent path and if either I(dest) ends with "/" or I(src) is a directory, I(dest) is created. - If I(src) and I(dest) are files, the parent directory of I(dest) is not created and the task fails if it does not already exist. + type: path required: yes backup: description: @@ -69,19 +70,21 @@ options: - As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or C(u=rw,g=r,o=r)). - As of Ansible 2.3, the mode may also be the special string C(preserve). - C(preserve) means that the file will be given the same permissions as the source file. + type: path directory_mode: description: - When doing a recursive copy set the mode for the directories. - If this is not set we will use the system defaults. - The mode is only set on directories which are newly created, and will not affect those that already existed. + type: raw version_added: '1.5' remote_src: description: - Influence whether I(src) needs to be transferred or already is present remotely. - If C(no), it will search for I(src) at originating/master machine. - If C(yes) it will go to the remote/target machine for the I(src). - - I(remote_src) supports recursive copying as of version 2.8. - - I(remote_src) only works with C(mode=preserve) as of version 2.6. + - I(remote_src) supports recursive copying as of Ansible 2.8. + - I(remote_src) only works with C(mode=preserve) as of Ansible 2.6. type: bool default: no version_added: '2.0' @@ -102,6 +105,7 @@ options: - SHA1 checksum of the file being transferred. - Used to validate that the copy of the file was successful. - If this is not provided, ansible will use the local calculated checksum of the src file. + type: str version_added: '2.5' extends_documentation_fragment: - decrypt @@ -109,12 +113,11 @@ extends_documentation_fragment: - validate notes: - The M(copy) module recursively copy facility does not scale to lots (>hundreds) of files. -- For alternative, see M(synchronize) module, which is a wrapper around the C(rsync) command line tool. -- For Windows targets, use the M(win_copy) module instead. seealso: - module: assemble - module: fetch - module: file +- module: synchronize - module: template - module: win_copy author: @@ -129,7 +132,7 @@ EXAMPLES = r''' dest: /etc/foo.conf owner: foo group: foo - mode: 0644 + mode: '0644' - name: Copy file with owner and permission, using symbolic representation copy: @@ -153,7 +156,7 @@ EXAMPLES = r''' dest: /etc/ntp.conf owner: root group: root - mode: 0644 + mode: '0644' backup: yes - name: Copy a new "sudoers" file into place, after passing validation with visudo @@ -174,17 +177,17 @@ EXAMPLES = r''' content: '# This file was moved to /etc/other.conf' dest: /etc/mine.conf -- name: if follow is true, /path/to/file will be overwritten by contents of foo.conf +- name: If follow=yes, /path/to/file will be overwritten by contents of foo.conf copy: src: /etc/foo.conf - dest: /path/to/link # /path/to/link is link to /path/to/file - follow: True + dest: /path/to/link # link to /path/to/file + follow: yes -- name: if follow is False, /path/to/link will become a file and be overwritten by contents of foo.conf +- name: If follow=no, /path/to/link will become a file and be overwritten by contents of foo.conf copy: src: /etc/foo.conf - dest: /path/to/link # /path/to/link is link to /path/to/file - follow: False + dest: /path/to/link # link to /path/to/file + follow: no ''' RETURN = r''' @@ -473,7 +476,7 @@ def main(): directory_mode=dict(type='raw'), remote_src=dict(type='bool'), local_follow=dict(type='bool'), - checksum=dict(), + checksum=dict(type='str'), ), add_file_common_args=True, supports_check_mode=True, diff --git a/lib/ansible/modules/files/fetch.py b/lib/ansible/modules/files/fetch.py index 9e4672b365..9075cfc7c1 100644 --- a/lib/ansible/modules/files/fetch.py +++ b/lib/ansible/modules/files/fetch.py @@ -57,9 +57,6 @@ options: - Obviously this is only handy if the filenames are unique. type: bool default: no -author: -- Ansible Core Team -- Michael DeHaan notes: - When running fetch with C(become), the M(slurp) module will also be used to fetch the contents of the file for determining the remote @@ -74,6 +71,12 @@ notes: also explicitly set C(fail_on_missing) to C(no) to get the non-failing behaviour. - This module is also supported for Windows targets. +seealso: +- module: copy +- module: slurp +author: +- Ansible Core Team +- Michael DeHaan ''' EXAMPLES = r''' diff --git a/lib/ansible/modules/files/file.py b/lib/ansible/modules/files/file.py index c54b4f148f..0dc0a3042a 100644 --- a/lib/ansible/modules/files/file.py +++ b/lib/ansible/modules/files/file.py @@ -27,6 +27,7 @@ options: path: description: - Path to the file being managed. + type: path required: yes aliases: [ dest, name ] state: @@ -43,6 +44,7 @@ options: - If C(touch) (new in 1.4), an empty file will be created if the C(path) does not exist, while an existing file or directory will receive updated file access and modification times (similar to the way C(touch) works from the command line). + type: str default: file choices: [ absent, directory, file, hard, link, touch ] src: @@ -52,6 +54,7 @@ options: - Will accept absolute, relative and non-existing paths. - Relative paths are relative to the file being created (C(path)) which is how the Unix command C(ln -s SRC DEST) treats relative paths. + type: path recurse: description: - Recursively set the specified file attributes on directory contents. @@ -79,11 +82,13 @@ options: - This parameter indicates the time the file's modification time should be set to. - Should be C(preserve) when no modification is required, C(YYYYMMDDHHMM.SS) when using default time format, or C(now). - Default is None meaning that C(preserve) is the default for C(state=[file,directory,link,hard]) and C(now) is default for C(state=touch). + type: str version_added: "2.7" modification_time_format: description: - When used with C(modification_time), indicates the time format that must be used. - Based on default Python format (see time.strftime doc). + type: str default: "%Y%m%d%H%M.%S" version_added: '2.7' access_time: @@ -91,15 +96,15 @@ options: - This parameter indicates the time the file's access time should be set to. - Should be C(preserve) when no modification is required, C(YYYYMMDDHHMM.SS) when using default time format, or C(now). - Default is C(None) meaning that C(preserve) is the default for C(state=[file,directory,link,hard]) and C(now) is default for C(state=touch). + type: str version_added: '2.7' access_time_format: description: - When used with C(access_time), indicates the time format that must be used. - Based on default Python format (see time.strftime doc). + type: str default: "%Y%m%d%H%M.%S" version_added: '2.7' -notes: -- For Windows targets, use the M(win_file) module instead. seealso: - module: assemble - module: copy @@ -111,21 +116,19 @@ author: - Michael DeHaan ''' -EXAMPLES = ''' +EXAMPLES = r''' - name: Change file ownership, group and permissions file: path: /etc/foo.conf owner: foo group: foo - # When specifying mode using octal numbers, add a leading 0 - mode: 0644 + mode: '0644' - name: Create an insecure file file: path: /work owner: root group: root - # Or use quotes instead mode: '1777' - name: Create a symbolic link @@ -169,7 +172,7 @@ EXAMPLES = ''' file: path: /etc/some_directory state: directory - mode: 0755 + mode: '0755' - name: Update modification and access time of given file file: @@ -178,7 +181,7 @@ EXAMPLES = ''' modification_time: now access_time: now ''' -RETURN = ''' +RETURN = r''' ''' @@ -817,21 +820,21 @@ def main(): module = AnsibleModule( argument_spec=dict( - state=dict(choices=['file', 'directory', 'link', 'hard', 'touch', 'absent'], default=None), - path=dict(aliases=['dest', 'name'], required=True, type='path'), - _original_basename=dict(required=False), # Internal use only, for recursive ops - recurse=dict(default=False, type='bool'), - force=dict(required=False, default=False, type='bool'), # Note: Should not be in file_common_args in future - follow=dict(required=False, default=True, type='bool'), # Note: Different default than file_common_args - _diff_peek=dict(default=None), # Internal use only, for internal checks in the action plugins - src=dict(required=False, default=None, type='path'), # Note: Should not be in file_common_args in future - modification_time=dict(required=False, default=None), - modification_time_format=dict(required=False, default='%Y%m%d%H%M.%S'), - access_time=dict(required=False, default=None), - access_time_format=dict(required=False, default='%Y%m%d%H%M.%S'), + state=dict(type='str', choices=['absent', 'directory', 'file', 'hard', 'link', 'touch']), + path=dict(type='path', required=True, aliases=['dest', 'name']), + _original_basename=dict(type='str'), # Internal use only, for recursive ops + recurse=dict(type='bool', default=False), + force=dict(type='bool', default=False), # Note: Should not be in file_common_args in future + follow=dict(type='bool', default=True), # Note: Different default than file_common_args + _diff_peek=dict(type='str'), # Internal use only, for internal checks in the action plugins + src=dict(type='path'), # Note: Should not be in file_common_args in future + modification_time=dict(type='str'), + modification_time_format=dict(type='str', default='%Y%m%d%H%M.%S'), + access_time=dict(type='str'), + access_time_format=dict(type='str', default='%Y%m%d%H%M.%S'), ), add_file_common_args=True, - supports_check_mode=True + supports_check_mode=True, ) # When we rewrite basic.py, we will do something similar to this on instantiating an AnsibleModule diff --git a/lib/ansible/modules/files/find.py b/lib/ansible/modules/files/find.py index d665b03fb7..d3bfee2d79 100644 --- a/lib/ansible/modules/files/find.py +++ b/lib/ansible/modules/files/find.py @@ -27,9 +27,10 @@ options: age: description: - Select files whose age is equal to or greater than the specified time. - Use a negative age to find files equal to or less than the specified time. - You can choose seconds, minutes, hours, days, or weeks by specifying the + - Use a negative age to find files equal to or less than the specified time. + - You can choose seconds, minutes, hours, days, or weeks by specifying the first letter of any of those words (e.g., "1w"). + type: str patterns: default: '*' description: @@ -40,75 +41,80 @@ options: patterns contain a comma, make sure to put them in a list to avoid splitting the patterns in undesirable ways. type: list - aliases: ['pattern'] + aliases: [ pattern ] excludes: description: - One or more (shell or regex) patterns, which type is controlled by C(use_regex) option. - Items matching an C(excludes) pattern are culled from C(patterns) matches. Multiple patterns can be specified using a list. type: list - aliases: ['exclude'] + aliases: [ exclude ] version_added: "2.5" contains: description: - One or more regex patterns which should be matched against the file content. + type: str paths: - required: true - aliases: [ name, path ] description: - List of paths of directories to search. All paths must be fully qualified. type: list + required: true + aliases: [ name, path ] file_type: description: - Type of file to select. - - The 'link' and 'any' choices were added in version 2.3. + - The 'link' and 'any' choices were added in Ansible 2.3. + type: str choices: [ any, directory, file, link ] default: file recurse: description: - If target is a directory, recursively descend into the directory looking for files. type: bool - default: 'no' + default: no size: description: - Select files whose size is equal to or greater than the specified size. - Use a negative size to find files equal to or less than the specified size. - Unqualified values are in bytes but b, k, m, g, and t can be appended to specify + - Use a negative size to find files equal to or less than the specified size. + - Unqualified values are in bytes but b, k, m, g, and t can be appended to specify bytes, kilobytes, megabytes, gigabytes, and terabytes, respectively. - Size is not evaluated for directories. + - Size is not evaluated for directories. age_stamp: - default: mtime - choices: [ atime, ctime, mtime ] description: - Choose the file property against which we compare age. + type: str + choices: [ atime, ctime, mtime ] + default: mtime hidden: description: - - Set this to true to include hidden files, otherwise they'll be ignored. + - Set this to C(yes) to include hidden files, otherwise they will be ignored. type: bool - default: 'no' + default: no follow: description: - - Set this to true to follow symlinks in path for systems with python 2.6+. + - Set this to C(yes) to follow symlinks in path for systems with python 2.6+. type: bool - default: 'no' + default: no get_checksum: description: - - Set this to true to retrieve a file's sha1 checksum. + - Set this to C(yes) to retrieve a file's SHA1 checksum. type: bool - default: 'no' + default: no use_regex: description: - - If false, the patterns are file globs (shell). If true, they are python regexes. + - If C(no), the patterns are file globs (shell). + - If C(yes), they are python regexes. type: bool - default: 'no' + default: no depth: description: - - Set the maximum number of levels to decend into. Setting recurse - to false will override this value, which is effectively depth 1. - Default is unlimited depth. + - Set the maximum number of levels to decend into. + - Setting recurse to C(no) will override this value, which is effectively depth 1. + - Default is unlimited depth. + type: int version_added: "2.6" -notes: - - For Windows targets, use the M(win_find) module instead. +seealso: +- module: win_find ''' @@ -175,7 +181,7 @@ EXAMPLES = r''' RETURN = r''' files: - description: all matches found with the specified criteria (see stat module for full output of each dictionary) + description: All matches found with the specified criteria (see stat module for full output of each dictionary) returned: success type: list sample: [ @@ -189,12 +195,12 @@ files: }, ] matched: - description: number of matches + description: Number of matches returned: success type: str sample: 14 examined: - description: number of filesystem objects looked at + description: Number of filesystem objects looked at returned: success type: str sample: 34 @@ -355,14 +361,14 @@ def main(): contains=dict(type='str'), file_type=dict(type='str', default="file", choices=['any', 'directory', 'file', 'link']), age=dict(type='str'), - age_stamp=dict(type='str', default="mtime", choices=['atime', 'mtime', 'ctime']), + age_stamp=dict(type='str', default="mtime", choices=['atime', 'ctime', 'mtime']), size=dict(type='str'), - recurse=dict(type='bool', default='no'), - hidden=dict(type='bool', default='no'), - follow=dict(type='bool', default='no'), - get_checksum=dict(type='bool', default='no'), - use_regex=dict(type='bool', default='no'), - depth=dict(type='int', default=None), + recurse=dict(type='bool', default=False), + hidden=dict(type='bool', default=False), + follow=dict(type='bool', default=False), + get_checksum=dict(type='bool', default=False), + use_regex=dict(type='bool', default=False), + depth=dict(type='int'), ), supports_check_mode=True, ) diff --git a/lib/ansible/modules/files/ini_file.py b/lib/ansible/modules/files/ini_file.py index 684a3cf061..bc7e9e652a 100644 --- a/lib/ansible/modules/files/ini_file.py +++ b/lib/ansible/modules/files/ini_file.py @@ -8,99 +8,103 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -# + ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['preview'], 'supported_by': 'community'} -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- module: ini_file short_description: Tweak settings in INI files extends_documentation_fragment: files description: - Manage (add, remove, change) individual settings in an INI-style file without having - to manage the file as a whole with, say, M(template) or M(assemble). Adds missing - sections if they don't exist. - - Before version 2.0, comments are discarded when the source file is read, and therefore will not show up in the destination file. - - Since version 2.3, this module adds missing ending newlines to files to keep in line with the POSIX standard, even when + to manage the file as a whole with, say, M(template) or M(assemble). + - Adds missing sections if they don't exist. + - Before Ansible 2.0, comments are discarded when the source file is read, and therefore will not show up in the destination file. + - Since Ansible 2.3, this module adds missing ending newlines to files to keep in line with the POSIX standard, even when no other modifications need to be applied. version_added: "0.9" options: path: description: - Path to the INI-style file; this file is created if required. - - Before 2.3 this option was only usable as I(dest). - aliases: [ dest ] + - Before Ansible 2.3 this option was only usable as I(dest). + type: path required: true + aliases: [ dest ] section: description: - Section name in INI file. This is added if C(state=present) automatically when a single value is being set. - - If left empty or set to `null`, the I(option) will be placed before the first I(section). - Using `null` is also required if the config format does not support sections. + - If left empty or set to C(null), the I(option) will be placed before the first I(section). + - Using C(null) is also required if the config format does not support sections. + type: str required: true option: description: - If set (required for changing a I(value)), this is the name of the option. - May be omitted if adding/removing a whole I(section). + type: str value: description: - - The string value to be associated with an I(option). May be omitted when removing an I(option). + - The string value to be associated with an I(option). + - May be omitted when removing an I(option). + type: str backup: description: - Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. type: bool - default: 'no' + default: no others: - description: - - All arguments accepted by the M(file) module also work here + description: + - All arguments accepted by the M(file) module also work here. + type: str state: - description: - - If set to C(absent) the option or section will be removed if present instead of created. - choices: [ absent, present ] - default: present + description: + - If set to C(absent) the option or section will be removed if present instead of created. + type: str + choices: [ absent, present ] + default: present no_extra_spaces: - description: - - Do not insert spaces before and after '=' symbol - type: bool - default: 'no' - version_added: "2.1" + description: + - Do not insert spaces before and after '=' symbol. + type: bool + default: no + version_added: "2.1" create: - description: - - If set to 'no', the module will fail if the file does not already exist. - By default it will create the file if it is missing. - type: bool - default: 'yes' - version_added: "2.2" + description: + - If set to C(no), the module will fail if the file does not already exist. + - By default it will create the file if it is missing. + type: bool + default: yes + version_added: "2.2" allow_no_value: - description: - - allow option without value and without '=' symbol - type: bool - required: false - default: false - version_added: "2.6" + description: + - Allow option without value and without '=' symbol. + type: bool + default: no + version_added: "2.6" 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. + - 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 = ''' -# Before 2.3, option 'dest' was used instead of 'path' +EXAMPLES = r''' +# Before Ansible 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 - mode: 0600 + mode: '0600' backup: yes - name: Ensure "temperature=cold is in section "[drinks]" in specified file @@ -302,7 +306,7 @@ def main(): backup=dict(type='bool', default=False), state=dict(type='str', default='present', choices=['absent', 'present']), no_extra_spaces=dict(type='bool', default=False), - allow_no_value=dict(type='bool', default=False, required=False), + allow_no_value=dict(type='bool', default=False), create=dict(type='bool', default=True) ), add_file_common_args=True, diff --git a/lib/ansible/modules/files/iso_extract.py b/lib/ansible/modules/files/iso_extract.py index 4bf9919e0d..ad65a66e9d 100644 --- a/lib/ansible/modules/files/iso_extract.py +++ b/lib/ansible/modules/files/iso_extract.py @@ -38,34 +38,38 @@ options: image: description: - The ISO image to extract files from. + type: path required: yes aliases: [ path, src ] dest: description: - The destination directory to extract files to. + type: path required: yes files: description: - A list of files to extract from the image. - Extracting directories does not work. + type: list required: yes force: description: - If C(yes), which will replace the remote file when contents are different than the source. - If C(no), the file will only be extracted and copied if the destination does not already exist. type: bool - default: 'yes' + default: yes aliases: [ thirsty ] version_added: '2.4' executable: description: - The path to the C(7z) executable to use for extracting files from the ISO. + type: path default: '7z' version_added: '2.4' notes: - Only the file checksum (content) is taken into account when extracting files - from the ISO image. If C(force=no), only checks the presence of the file. -- In Ansible v2.3 this module was using C(mount) and C(umount) commands only, + from the ISO image. If C(force=no), only checks the presence of the file. +- In Ansible 2.3 this module was using C(mount) and C(umount) commands only, requiring root access. This is no longer needed with the introduction of 7zip for extraction. ''' diff --git a/lib/ansible/modules/files/lineinfile.py b/lib/ansible/modules/files/lineinfile.py index 635ac74336..0133cc901e 100644 --- a/lib/ansible/modules/files/lineinfile.py +++ b/lib/ansible/modules/files/lineinfile.py @@ -21,101 +21,107 @@ short_description: Manage lines in text files description: - This module ensures a particular line is in a file, or replace an existing line using a back-referenced regular expression. - - This is primarily useful when you want to change a single line in - a file only. See the M(replace) module if you want to change - multiple, similar lines or check M(blockinfile) if you want to insert/update/remove a block of lines in a file. + - This is primarily useful when you want to change a single line in a file only. + - See the M(replace) module if you want to change multiple, similar lines + or check M(blockinfile) if you want to insert/update/remove a block of lines in a file. For other cases, see the M(copy) or M(template) modules. version_added: "0.7" options: path: description: - The file to modify. - - Before 2.3 this option was only usable as I(dest), I(destfile) and I(name). - aliases: [ dest, destfile, name ] + - Before Ansible 2.3 this option was only usable as I(dest), I(destfile) and I(name). + type: path required: true + aliases: [ dest, destfile, name ] regexp: - aliases: [ regex ] description: - The regular expression to look for in every line of the file. - For C(state=present), the pattern to replace if found. Only the last line found will be replaced. - For C(state=absent), the pattern of the line(s) to remove. - If the regular expression is not matched, the line will be - added to the file in keeping with`insertbefore` or `insertafter` + added to the file in keeping with C(insertbefore) or C(insertafter) settings. - When modifying a line the regexp should typically match both the initial state of the line as well as its state after replacement by C(line) to ensure idempotence. - Uses Python regular expressions. See U(http://docs.python.org/2/library/re.html). + type: str + aliases: [ regex ] version_added: '1.7' state: description: - Whether the line should be there or not. + type: str choices: [ absent, present ] default: present line: description: - - Required for C(state=present). The line to insert/replace into the - file. If C(backrefs) is set, may contain backreferences that will get + - The line to insert/replace into the file. + - Required for C(state=present). + - If C(backrefs) is set, may contain backreferences that will get expanded with the C(regexp) capture groups if the regexp matches. + type: str backrefs: description: - - Used with C(state=present). If set, C(line) can contain backreferences - (both positional and named) that will get populated if the C(regexp) - matches. This flag changes the operation of the module slightly; + - Used with C(state=present). + - If set, C(line) can contain backreferences (both positional and named) + that will get populated if the C(regexp) matches. + - This parameter changes the operation of the module slightly; C(insertbefore) and C(insertafter) will be ignored, and if the C(regexp) doesn't match anywhere in the file, the file will be left unchanged. - If the C(regexp) does match, the last matching line will be replaced by + - If the C(regexp) does match, the last matching line will be replaced by the expanded line parameter. type: bool - default: 'no' + default: no version_added: "1.1" insertafter: description: - - Used with C(state=present). If specified, the line will be inserted - after the last match of specified regular expression. - If the first match is required, use(firstmatch=yes). - A special value is available; C(EOF) for inserting the line at the - end of the file. - If specified regular expression has no matches, EOF will be used instead. - If regular expressions are passed to both C(regexp) and C(insertafter), C(insertafter) is only honored if no match for C(regexp) is found. - May not be used with C(backrefs). + - Used with C(state=present). + - If specified, the line will be inserted after the last match of specified regular expression. + - If the first match is required, use(firstmatch=yes). + - A special value is available; C(EOF) for inserting the line at the end of the file. + - If specified regular expression has no matches, EOF will be used instead. + - If regular expressions are passed to both C(regexp) and C(insertafter), C(insertafter) is only honored if no match for C(regexp) is found. + - May not be used with C(backrefs). + type: str choices: [ EOF, '*regex*' ] default: EOF insertbefore: description: - - Used with C(state=present). If specified, the line will be inserted - before the last match of specified regular expression. - If the first match is required, use(firstmatch=yes). - A value is available; C(BOF) for inserting the line at - the beginning of the file. - If specified regular expression has no matches, the line will be - inserted at the end of the file. - If regular expressions are passed to both C(regexp) and C(insertbefore), C(insertbefore) is only honored if no match for C(regexp) is found. - May not be used with C(backrefs). + - Used with C(state=present). + - If specified, the line will be inserted before the last match of specified regular expression. + - If the first match is required, use C(firstmatch=yes). + - A value is available; C(BOF) for inserting the line at the beginning of the file. + - If specified regular expression has no matches, the line will be inserted at the end of the file. + - If regular expressions are passed to both C(regexp) and C(insertbefore), C(insertbefore) is only honored if no match for C(regexp) is found. + - May not be used with C(backrefs). + type: str choices: [ BOF, '*regex*' ] version_added: "1.1" create: description: - - Used with C(state=present). If specified, the file will be created - if it does not already exist. By default it will fail if the file - is missing. + - Used with C(state=present). + - If specified, the file will be created if it does not already exist. + - By default it will fail if the file is missing. type: bool - default: 'no' + default: no backup: - description: - - Create a backup file including the timestamp information so you can - get the original file back if you somehow clobbered it incorrectly. - type: bool - default: 'no' + description: + - Create a backup file including the timestamp information so you can + get the original file back if you somehow clobbered it incorrectly. + type: bool + default: no firstmatch: description: - - Used with C(insertafter) or C(insertbefore). If set, C(insertafter) and C(inserbefore) find - a first line has regular expression matches. + - Used with C(insertafter) or C(insertbefore). + - If set, C(insertafter) and C(inserbefore) find a first line has regular expression matches. type: bool - default: 'no' + default: no version_added: "2.5" others: - description: - - All arguments accepted by the M(file) module also work here. + description: + - All arguments accepted by the M(file) module also work here. + type: str extends_documentation_fragment: - files - validate @@ -123,7 +129,10 @@ 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. seealso: - module: blockinfile +- module: copy - module: file +- module: replace +- module: template - module: win_lineinfile author: - Daniel Hokka Zakrissoni (@dhozac) @@ -135,7 +144,7 @@ EXAMPLES = r""" - lineinfile: path: /etc/selinux/config regexp: '^SELINUX=' - line: 'SELINUX=enforcing' + line: SELINUX=enforcing - lineinfile: path: /etc/sudoers @@ -146,16 +155,16 @@ EXAMPLES = r""" - lineinfile: path: /etc/hosts regexp: '^127\.0\.0\.1' - line: '127.0.0.1 localhost' + line: 127.0.0.1 localhost owner: root group: root - mode: 0644 + mode: '0644' - lineinfile: path: /etc/httpd/conf/httpd.conf regexp: '^Listen ' insertafter: '^#Listen ' - line: 'Listen 8080' + line: Listen 8080 - lineinfile: path: /etc/services @@ -166,7 +175,7 @@ EXAMPLES = r""" # Add a line to a file if the file does not exist, without passing regexp - lineinfile: path: /tmp/testfile - line: '192.168.1.99 foo.lab.net foo' + line: 192.168.1.99 foo.lab.net foo create: yes # Fully quoted because of the ': ' on the line. See the Gotchas in the YAML docs. @@ -189,7 +198,7 @@ EXAMPLES = r""" state: present regexp: '^%ADMIN ALL=' line: '%ADMIN ALL=(ALL) NOPASSWD: ALL' - validate: '/usr/sbin/visudo -cf %s' + validate: /usr/sbin/visudo -cf %s """ import os @@ -475,7 +484,7 @@ def main(): backrefs=dict(type='bool', default=False), create=dict(type='bool', default=False), backup=dict(type='bool', default=False), - firstmatch=dict(default=False, type='bool'), + firstmatch=dict(type='bool', default=False), validate=dict(type='str'), ), mutually_exclusive=[['insertbefore', 'insertafter']], diff --git a/lib/ansible/modules/files/patch.py b/lib/ansible/modules/files/patch.py index a279a3940a..8550d7566c 100644 --- a/lib/ansible/modules/files/patch.py +++ b/lib/ansible/modules/files/patch.py @@ -27,54 +27,59 @@ options: basedir: description: - Path of a base directory in which the patch file will be applied. - May be omitted when C(dest) option is specified, otherwise required. + - May be omitted when C(dest) option is specified, otherwise required. + type: path dest: description: - Path of the file on the remote machine to be patched. - The names of the files to be patched are usually taken from the patch file, but if there's just one file to be patched it can specified with this option. + type: path aliases: [ originalfile ] src: description: - Path of the patch file as accepted by the GNU patch tool. If C(remote_src) is 'no', the patch source file is looked up from the module's I(files) directory. + type: path required: true aliases: [ patchfile ] state: - version_added: "2.6" description: - Whether the patch should be applied or reverted. + type: str choices: [ absent, present ] default: present + version_added: "2.6" remote_src: description: - If C(no), it will search for src at originating/master machine, if C(yes) it will go to the remote/target machine for the C(src). type: bool - default: 'no' + default: no strip: description: - Number that indicates the smallest prefix containing leading slashes that will be stripped from each file name found in the patch file. - For more information see the strip parameter of the GNU patch tool. + - For more information see the strip parameter of the GNU patch tool. + type: int default: 0 backup: version_added: "2.0" description: - - Passes C(--backup --version-control=numbered) to patch, - producing numbered backup copies. + - Passes C(--backup --version-control=numbered) to patch, producing numbered backup copies. type: bool - default: 'no' + default: no binary: version_added: "2.0" description: - Setting to C(yes) will disable patch's heuristic for transforming CRLF - line endings into LF. Line endings of src and dest must match. If set to - C(no), C(patch) will replace CRLF in C(src) files on POSIX. + line endings into LF. + - Line endings of src and dest must match. + - If set to C(no), C(patch) will replace CRLF in C(src) files on POSIX. type: bool - default: 'no' + default: no notes: - This module requires GNU I(patch) utility to be installed on the remote host. ''' diff --git a/lib/ansible/modules/files/replace.py b/lib/ansible/modules/files/replace.py index 30615b7008..c816d64de1 100644 --- a/lib/ansible/modules/files/replace.py +++ b/lib/ansible/modules/files/replace.py @@ -13,15 +13,15 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'supported_by': 'community'} -DOCUMENTATION = """ +DOCUMENTATION = r''' --- module: replace -author: "Evan Kaufman (@EvanK)" +author: Evan Kaufman (@EvanK) extends_documentation_fragment: - files - validate short_description: Replace all instances of a particular string in a - file using a back-referenced regular expression. + file using a back-referenced regular expression description: - This module will replace all instances of a pattern within a file. - It is up to the user to maintain idempotence by ensuring that the @@ -31,89 +31,96 @@ options: path: description: - The file to modify. - - Before 2.3 this option was only usable as I(dest), I(destfile) and I(name). - aliases: [ dest, destfile, name ] + - Before Ansible 2.3 this option was only usable as I(dest), I(destfile) and I(name). + type: path required: true + aliases: [ dest, destfile, name ] regexp: description: - The regular expression to look for in the contents of the file. - Uses Python regular expressions; see + - Uses Python regular expressions; see U(http://docs.python.org/2/library/re.html). - Uses MULTILINE mode, which means C(^) and C($) match the beginning + - Uses MULTILINE mode, which means C(^) and C($) match the beginning and end of the file, as well as the beginning and end respectively of I(each line) of the file. - Does not use DOTALL, which means the C(.) special character matches any character I(except newlines). A common mistake is to assume that a negated character set like C([^#]) will also not match newlines. - In order to exclude newlines, they must be added to the set like C([^#\\n]). - - Note that, as of ansible 2, short form tasks should have any escape + - In order to exclude newlines, they must be added to the set like C([^#\n]). + - Note that, as of Ansible 2.0, short form tasks should have any escape sequences backslash-escaped in order to prevent them being parsed as string literal escapes. See the examples. + type: str required: true replace: description: - - The string to replace regexp matches. May contain backreferences - that will get expanded with the regexp capture groups if the regexp - matches. If not set, matches are removed entirely. + - The string to replace regexp matches. + - May contain backreferences that will get expanded with the regexp capture groups if the regexp matches. + - If not set, matches are removed entirely. + type: str after: description: - - If specified, the line after the replace/remove will start. Can be used - in combination with C(before). - Uses Python regular expressions; see + - If specified, the line after the replace/remove will start. + - Can be used in combination with C(before). + - Uses Python regular expressions; see U(http://docs.python.org/2/library/re.html). + type: str version_added: "2.4" before: description: - - If specified, the line before the replace/remove will occur. Can be used - in combination with C(after). - Uses Python regular expressions; see + - If specified, the line before the replace/remove will occur. + - Can be used in combination with C(after). + - Uses Python regular expressions; see U(http://docs.python.org/2/library/re.html). + type: str version_added: "2.4" backup: description: - Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. type: bool - default: 'no' + default: no others: description: - All arguments accepted by the M(file) module also work here. + type: str encoding: description: - - "The character encoding for reading and writing the file." - default: "utf-8" + - The character encoding for reading and writing the file. + type: str + default: utf-8 version_added: "2.4" 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. - - Option I(follow) has been removed in version 2.5, because this module modifies the contents of the file so I(follow=no) doesn't make sense. -""" + - Option I(follow) has been removed in Ansible 2.5, because this module modifies the contents of the file so I(follow=no) doesn't make sense. +''' -EXAMPLES = r""" -# Before 2.3, option 'dest', 'destfile' or 'name' was used instead of 'path' +EXAMPLES = r''' +# Before Ansible 2.3, option 'dest', 'destfile' or 'name' was used instead of 'path' - replace: path: /etc/hosts regexp: '(\s+)old\.host\.name(\s+.*)?$' replace: '\1new.host.name\2' backup: yes -# Replace after the expression till the end of the file (requires >=2.4) -- replace: +- name: Replace after the expression till the end of the file (requires Ansible >= 2.4) + replace: path: /etc/hosts regexp: '(\s+)old\.host\.name(\s+.*)?$' replace: '\1new.host.name\2' - after: 'Start after line.*' + after: Start after line.* backup: yes -# Replace before the expression till the begin of the file (requires >=2.4) -- replace: +- name: Replace before the expression till the begin of the file (requires Ansible >= 2.4) + replace: path: /etc/hosts regexp: '(\s+)old\.host\.name(\s+.*)?$' replace: '\1new.host.name\2' before: 'Start before line.*' backup: yes -# Replace between the expressions (requires >=2.4) -- replace: +- name: Replace between the expressions (requires Ansible >= 2.4) + replace: path: /etc/hosts regexp: '(\s+)old\.host\.name(\s+.*)?$' replace: '\1new.host.name\2' @@ -126,7 +133,7 @@ EXAMPLES = r""" regexp: '^old\.host\.name[^\n]*\n' owner: jdoe group: jdoe - mode: 0644 + mode: '0644' - replace: path: /etc/apache/ports @@ -134,15 +141,15 @@ EXAMPLES = r""" replace: '\1 127.0.0.1:8080' validate: '/usr/sbin/apache2ctl -f %s -t' -- name: short form task (in ansible 2+) necessitates backslash-escaped sequences +- name: Short form task (in ansible 2+) necessitates backslash-escaped sequences replace: dest=/etc/hosts regexp='\\b(localhost)(\\d*)\\b' replace='\\1\\2.localdomain\\2 \\1\\2' -- name: long form task does not +- name: Long form task does not replace: dest: /etc/hosts regexp: '\b(localhost)(\d*)\b' replace: '\1\2.localdomain\2 \1\2' -""" +''' import os import re @@ -189,17 +196,17 @@ def check_file_attrs(module, changed, message): def main(): module = AnsibleModule( argument_spec=dict( - path=dict(required=True, aliases=['dest', 'destfile', 'name'], type='path'), - regexp=dict(required=True), - replace=dict(default='', type='str'), - after=dict(required=False), - before=dict(required=False), - backup=dict(default=False, type='bool'), - validate=dict(default=None, type='str'), - encoding=dict(default='utf-8', type='str'), + path=dict(type='path', required=True, aliases=['dest', 'destfile', 'name']), + regexp=dict(type='str', required=True), + replace=dict(type='str', default=''), + after=dict(type='str'), + before=dict(type='str'), + backup=dict(type='bool', default=False), + validate=dict(type='str'), + encoding=dict(type='str', default='utf-8'), ), add_file_common_args=True, - supports_check_mode=True + supports_check_mode=True, ) params = module.params diff --git a/lib/ansible/modules/files/stat.py b/lib/ansible/modules/files/stat.py index 0b627085c0..6aa31108eb 100644 --- a/lib/ansible/modules/files/stat.py +++ b/lib/ansible/modules/files/stat.py @@ -1,4 +1,5 @@ #!/usr/bin/python + # Copyright: (c) 2017, Ansible Project # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) @@ -15,18 +16,19 @@ module: stat version_added: "1.3" short_description: Retrieve file or file system status description: - - Retrieves facts for a file similar to the linux/unix 'stat' command. + - Retrieves facts for a file similar to the Linux/Unix 'stat' command. - For Windows targets, use the M(win_stat) module instead. options: path: description: - The full path of the file/object to get the facts of. + type: path required: true follow: description: - Whether to follow symlinks. type: bool - default: 'no' + default: no get_md5: description: - Whether to return the md5 sum of the file. @@ -37,19 +39,20 @@ options: - 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' + default: no get_checksum: description: - - Whether to return a checksum of the file (default sha1). + - Whether to return a checksum of the file. type: bool - default: 'yes' + 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. + - Algorithm to determine checksum of file. + - Will throw an error if the host is unable to use specified algorithm. - The remote host has to support the hashing method specified, C(md5) can be unavailable if the host is FIPS-140 compliant. + type: str choices: [ md5, sha1, sha224, sha256, sha384, sha512 ] default: sha1 aliases: [ checksum, checksum_algo ] @@ -59,27 +62,25 @@ options: - Use file magic and return data about the nature of the file. this uses 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'. + - In Ansible 2.3 this option changed from 'mime' to 'get_mime' and the default changed to 'Yes'. type: bool - default: 'yes' - version_added: "2.1" + default: yes aliases: [ mime, mime_type, mime-type ] + version_added: "2.1" get_attributes: description: - Get file attributes using lsattr tool if present. type: bool - default: 'yes' - version_added: "2.3" + default: yes aliases: [ attr, attributes ] -notes: - - For Windows targets, use the M(win_stat) module instead. + version_added: "2.3" seealso: - module: file - module: win_stat author: Bruce Pennypacker (@bpennypacker) ''' -EXAMPLES = ''' +EXAMPLES = r''' # Obtain the stats of /etc/foo.conf, and check that the file still belongs # to 'root'. Fail otherwise. - stat: @@ -142,7 +143,7 @@ stat: type: complex contains: exists: - description: if the destination path actually exists or not + description: If the destination path actually exists or not returned: success type: bool sample: True @@ -445,7 +446,7 @@ def main(): follow=dict(type='bool', default=False), get_md5=dict(type='bool'), get_checksum=dict(type='bool', default=True), - get_mime=dict(type='bool', default='yes', aliases=['mime', 'mime_type', 'mime-type']), + get_mime=dict(type='bool', default=True, aliases=['mime', 'mime_type', 'mime-type']), get_attributes=dict(type='bool', default=True, aliases=['attr', 'attributes']), checksum_algorithm=dict(type='str', default='sha1', choices=['md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512'], diff --git a/lib/ansible/modules/files/synchronize.py b/lib/ansible/modules/files/synchronize.py index 8ddd8a61ae..b5728efcd5 100644 --- a/lib/ansible/modules/files/synchronize.py +++ b/lib/ansible/modules/files/synchronize.py @@ -12,70 +12,82 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['preview'], 'supported_by': 'core'} -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- module: synchronize version_added: "1.4" -short_description: A wrapper around rsync to make common tasks in your playbooks quick and easy. +short_description: A wrapper around rsync to make common tasks in your playbooks quick and easy description: - - C(synchronize) is a wrapper around rsync to make common tasks in your playbooks quick and easy. It is run and originates on the local host where - Ansible is being run. Of course, you could just use the C(command) action to call rsync yourself, but you also have to add a fair number of - boilerplate options and host facts. C(synchronize) is not intended to provide access to the full power of rsync, but does make the most common + - C(synchronize) is a wrapper around rsync to make common tasks in your playbooks quick and easy. + - It is run and originates on the local host where Ansible is being run. + - Of course, you could just use the C(command) action to call rsync yourself, but you also have to add a fair number of + boilerplate options and host facts. + - This module is not intended to provide access to the full power of rsync, but does make the most common invocations easier to implement. You `still` may need to call rsync directly via C(command) or C(shell) depending on your use case. options: src: description: - - Path on the source host that will be synchronized to the destination; The path can be absolute or relative. + - Path on the source host that will be synchronized to the destination. + - The path can be absolute or relative. + type: str required: true dest: description: - - Path on the destination host that will be synchronized from the source; The path can be absolute or relative. + - Path on the destination host that will be synchronized from the source. + - The path can be absolute or relative. + type: str required: true dest_port: description: - - Port number for ssh on the destination host. Prior to ansible 2.0, the ansible_ssh_port inventory var took precedence over this value. + - Port number for ssh on the destination host. + - Prior to Ansible 2.0, the ansible_ssh_port inventory var took precedence over this value. + type: int default: Value of ansible_ssh_port for this host, remote_port config setting, or the value from ssh client configuration if none of those are set version_added: "1.5" mode: description: - - Specify the direction of the synchronization. In push mode the localhost or delegate is the source; In pull mode the remote host in context - is the source. + - Specify the direction of the synchronization. + - In push mode the localhost or delegate is the source. + - In pull mode the remote host in context is the source. + type: str choices: [ pull, push ] default: push archive: description: - Mirrors the rsync archive flag, enables recursive, links, perms, times, owner, group flags and -D. type: bool - default: 'yes' + default: yes checksum: description: - Skip based on checksum, rather than mod-time & size; Note that that "archive" option is still enabled by default - the "checksum" option will not disable it. type: bool - default: 'no' + default: no version_added: "1.6" compress: description: - - Compress file data during the transfer. In most cases, leave this enabled unless it causes problems. + - Compress file data during the transfer. + - In most cases, leave this enabled unless it causes problems. type: bool - default: 'yes' + default: yes version_added: "1.7" existing_only: description: - Skip creating new files on receiver. type: bool - default: 'no' + default: no version_added: "1.5" delete: description: - - Delete files in C(dest) that don't exist (after transfer, not before) in the C(src) path. This option requires C(recursive=yes). + - Delete files in C(dest) that don't exist (after transfer, not before) in the C(src) path. + - This option requires C(recursive=yes). type: bool - default: 'no' + default: no dirs: description: - - Transfer directories without recursing + - Transfer directories without recursing. type: bool - default: 'no' + default: no recursive: description: - Recurse into directories. @@ -90,7 +102,7 @@ options: description: - Copy symlinks as the item that they point to (the referent) is copied, rather than the symlink. type: bool - default: 'no' + default: no perms: description: - Preserve permissions. @@ -98,66 +110,72 @@ options: default: the value of the archive option times: description: - - Preserve modification times + - Preserve modification times. type: bool default: the value of the archive option owner: description: - - Preserve owner (super user only) + - Preserve owner (super user only). type: bool default: the value of the archive option group: description: - - Preserve group + - Preserve group. type: bool default: the value of the archive option rsync_path: description: - Specify the rsync command to run on the remote host. See C(--rsync-path) on the rsync man page. - To specify the rsync command to run on the local host, you need to set this your task var C(ansible_rsync_path). + type: path rsync_timeout: description: - Specify a C(--timeout) for the rsync command in seconds. + type: int default: 0 set_remote_user: description: - - put user@ for the remote paths. If you have a custom ssh config to define the remote user for a host - that does not match the inventory user, you should set this parameter to "no". + - Put user@ for the remote paths. + - If you have a custom ssh config to define the remote user for a host + that does not match the inventory user, you should set this parameter to C(no). + type: bool default: yes use_ssh_args: description: - - Use the ssh_args specified in ansible.cfg + - Use the ssh_args specified in ansible.cfg. type: bool - default: 'no' + default: no version_added: "2.0" rsync_opts: description: - - Specify additional rsync options by passing in an array. Note that an empty string in - C(rsync_opts) will end up transfer the current working directory. + - Specify additional rsync options by passing in an array. + - Note that an empty string in C(rsync_opts) will end up transfer the current working directory. + type: str default: version_added: "1.6" partial: description: - Tells rsync to keep the partial file which should make a subsequent transfer of the rest of the file much faster. type: bool - default: 'no' + default: no version_added: "2.0" verify_host: description: - Verify destination host key. type: bool - default: 'no' + default: no version_added: "2.0" private_key: description: - - Specify the private key to use for SSH-based rsync connections (e.g. C(~/.ssh/id_rsa)) + - Specify the private key to use for SSH-based rsync connections (e.g. C(~/.ssh/id_rsa)). + type: path version_added: "1.6" link_dest: description: - - add a destination to hard link against during the rsync. + - Add a destination to hard link against during the rsync. + type: str default: version_added: "2.5" - notes: - rsync must be installed on both the local and remote host. - For the C(synchronize) module, the "local host" is the host `the synchronize task originates on`, and the "destination host" is the host @@ -168,19 +186,16 @@ notes: The user and permissions for the synchronize `src` are those of the user running the Ansible task on the local host (or the remote_user for a delegate_to host when delegate_to is used). - The user and permissions for the synchronize `dest` are those of the `remote_user` on the destination host or the `become_user` if `become=yes` is active. - - In 2.0.0.0 a bug in the synchronize module made become occur on the "local host". This was fixed in 2.0.1. + - In Ansible 2.0 a bug in the synchronize module made become occur on the "local host". This was fixed in Ansible 2.0.1. - Currently, synchronize is limited to elevating permissions via passwordless sudo. This is because rsync itself is connecting to the remote machine and rsync doesn't give us a way to pass sudo credentials in. - Currently there are only a few connection types which support synchronize (ssh, paramiko, local, and docker) because a sync strategy has been determined for those connection types. Note that the connection for these must not need a password as rsync itself is making the connection and rsync does not provide us a way to pass a password to the connection. - Expect that dest=~/x will be ~/x even if using sudo. - - Inspect the verbose output to validate the destination user/host/path - are what was expected. - - To exclude files and directories from being synchronized, you may add - C(.rsync-filter) files to the source directory. - - rsync daemon must be up and running with correct permission when using - rsync protocol in source or destination path. + - Inspect the verbose output to validate the destination user/host/path are what was expected. + - To exclude files and directories from being synchronized, you may add C(.rsync-filter) files to the source directory. + - rsync daemon must be up and running with correct permission when using rsync protocol in source or destination path. - The C(synchronize) module forces `--delay-updates` to avoid leaving a destination in a broken in-between state if the underlying rsync process encounters an error. Those synchronizing large numbers of files that are willing to trade safety for performance should call rsync directly. - link_destination is subject to the same limitations as the underlaying rsync daemon. Hard links are only preserved if the relative subtrees @@ -284,7 +299,7 @@ EXAMPLES = ''' synchronize: src: some/relative/path dest: /some/absolute/path - rsync_path: "su -c rsync" + rsync_path: su -c rsync # Example .rsync-filter file in the source directory # - var # exclude any path whose last part is 'var' @@ -309,15 +324,14 @@ EXAMPLES = ''' # Specify the rsync binary to use on remote host and on local host - hosts: groupofhosts vars: - ansible_rsync_path: "/usr/gnu/bin/rsync" + ansible_rsync_path: /usr/gnu/bin/rsync tasks: - name: copy /tmp/localpath/ to remote location /tmp/remotepath synchronize: - src: "/tmp/localpath/" - dest: "/tmp/remotepath" - rsync_path: "/usr/gnu/bin/rsync" - + src: /tmp/localpath/ + dest: /tmp/remotepath + rsync_path: /usr/gnu/bin/rsync ''' @@ -370,7 +384,7 @@ def main(): private_key=dict(type='path'), rsync_path=dict(type='str'), _local_rsync_path=dict(type='path', default='rsync'), - _local_rsync_password=dict(default=None, no_log=True), + _local_rsync_password=dict(type='str', default=None, no_log=True), _substitute_controller=dict(type='bool', default=False), archive=dict(type='bool', default=True), checksum=dict(type='bool', default=False), diff --git a/lib/ansible/modules/files/tempfile.py b/lib/ansible/modules/files/tempfile.py index 38e7745fe8..987ed5e69e 100644 --- a/lib/ansible/modules/files/tempfile.py +++ b/lib/ansible/modules/files/tempfile.py @@ -16,7 +16,7 @@ DOCUMENTATION = ''' --- module: tempfile version_added: "2.3" -short_description: Creates temporary files and directories. +short_description: Creates temporary files and directories description: - The C(tempfile) module creates temporary files and directories. C(mktemp) command takes different parameters on various systems, this module helps to avoid troubles related to that. Files/directories created by module are accessible only by creator. In case you need to make them world-accessible @@ -26,22 +26,26 @@ options: state: description: - Whether to create file or directory. + type: str choices: [ directory, file ] default: file path: description: - - Location where temporary file or directory should be created. If path is not specified default system temporary directory will be used. + - Location where temporary file or directory should be created. + - If path is not specified, the default system temporary directory will be used. + type: path prefix: description: - Prefix of file/directory name created by module. + type: str default: ansible. suffix: description: - Suffix of file/directory name created by module. + type: str default: "" -notes: - - For Windows targets, use the M(win_tempfile) module instead. seealso: +- module: file - module: win_tempfile author: - Krzysztof Magosa (@krzysztof-magosa) diff --git a/lib/ansible/modules/files/template.py b/lib/ansible/modules/files/template.py index 2ab163bf6c..c7d12026b0 100644 --- a/lib/ansible/modules/files/template.py +++ b/lib/ansible/modules/files/template.py @@ -35,10 +35,12 @@ options: description: - Path of a Jinja2 formatted template on the Ansible controller. - This can be a relative or an absolute path. + type: path required: yes dest: description: - Location to render the template to on the remote machine. + type: path required: yes backup: description: @@ -50,27 +52,32 @@ options: newline_sequence: description: - Specify the newline sequence to use for templating files. + type: str choices: [ '\n', '\r', '\r\n' ] default: '\n' version_added: '2.4' block_start_string: description: - The string marking the beginning of a block. + type: str default: '{%' version_added: '2.4' block_end_string: description: - The string marking the end of a block. + type: str default: '%}' version_added: '2.4' variable_start_string: description: - The string marking the beginning of a print statement. + type: str default: '{{' version_added: '2.4' variable_end_string: description: - The string marking the end of a print statement. + type: str default: '}}' version_added: '2.4' trim_blocks: @@ -84,7 +91,7 @@ options: description: - Determine when leading spaces and tabs should be stripped. - When set to C(yes) leading spaces and tabs are stripped from the start of a line to a block. - - This functionality requires Jinja v2.7 or newer. + - This functionality requires Jinja 2.7 or newer. type: bool default: no version_added: '2.6' @@ -109,11 +116,12 @@ options: - Overrides the encoding used to write the template file defined by C(dest). - It defaults to C(utf-8), but any encoding supported by python can be used. - The source template file must always be encoded using C(utf-8), for homogeneity. + type: str default: utf-8 version_added: '2.7' notes: - Including a string that uses a date in the template will result in the template being marked 'changed' each time. -- Since Ansible version 0.9, templates are loaded with C(trim_blocks=True). +- Since Ansible 0.9, templates are loaded with C(trim_blocks=True). - > Also, you can override jinja2 settings by adding a special header to template file. i.e. C(#jinja2:variable_start_string:'[%', variable_end_string:'%]', trim_blocks: False) @@ -151,7 +159,7 @@ EXAMPLES = r''' dest: /etc/file.conf owner: bin group: wheel - mode: "u=rw,g=r,o=r" + mode: u=rw,g=r,o=r - name: Create a DOS-style text file from a template template: @@ -163,7 +171,7 @@ EXAMPLES = r''' template: src: /mine/sudoers dest: /etc/sudoers - validate: '/usr/sbin/visudo -cf %s' + validate: /usr/sbin/visudo -cf %s - name: Update sshd configuration safely, avoid locking yourself out template: diff --git a/lib/ansible/modules/files/unarchive.py b/lib/ansible/modules/files/unarchive.py index f8a53101ea..707e94c49c 100644 --- a/lib/ansible/modules/files/unarchive.py +++ b/lib/ansible/modules/files/unarchive.py @@ -24,8 +24,8 @@ description: - The C(unarchive) module unpacks an archive. - By default, it will copy the source file from the local system to the target before unpacking. - Set C(remote_src=yes) to unpack an archive which already exists on the target. - - For Windows targets, use the M(win_unzip) module instead. - If checksum validation is desired, use M(get_url) or M(uri) instead to fetch the file and set C(remote_src=yes). + - For Windows targets, use the M(win_unzip) module instead. options: src: description: @@ -33,57 +33,62 @@ options: target server to existing archive file to unpack. - If C(remote_src=yes) and C(src) contains C(://), the remote machine will download the file from the URL first. (version_added 2.0). This is only for simple cases, for full download support use the M(get_url) module. + type: path required: true dest: description: - Remote absolute path where the archive should be unpacked. + type: path required: true copy: description: - If true, the file is copied from local 'master' to the target machine, otherwise, the plugin will look for src archive at the target machine. - This option has been deprecated in favor of C(remote_src). - This option is mutually exclusive with C(remote_src). - type: 'bool' - default: 'yes' + type: bool + default: yes creates: description: - If the specified absolute path (file or directory) already exists, this step will B(not) be run. + type: path version_added: "1.6" list_files: description: - If set to True, return the list of files that are contained in the tarball. - type: 'bool' - default: 'no' + type: bool + default: no version_added: "2.0" exclude: description: - List the directory and file entries that you would like to exclude from the unarchive action. + type: list version_added: "2.1" keep_newer: description: - Do not replace existing files that are newer than files from the archive. - type: 'bool' - default: 'no' + type: bool + default: no version_added: "2.1" extra_opts: description: - Specify additional options by passing in an array. + type: list default: "" version_added: "2.1" remote_src: description: - Set to C(yes) to indicate the archived file is already on the remote system and not local to the Ansible controller. - This option is mutually exclusive with C(copy). - type: 'bool' - default: 'no' + type: bool + default: no version_added: "2.2" validate_certs: description: - This only applies if using a https URL as the source of the file. - This should only set to C(no) used on personally controlled sites using self-signed certificate. - Prior to 2.2 the code worked as if this was set to C(yes). - type: 'bool' - default: 'yes' + type: bool + default: yes version_added: "2.2" extends_documentation_fragment: - decrypt @@ -100,8 +105,9 @@ notes: are not touched. This is the same behavior as a normal archive extraction. - Existing files/directories in the destination which are not in the archive are ignored for purposes of deciding if the archive should be unpacked or not. - - For Windows targets, use the M(win_unzip) module instead. seealso: +- module: archive +- module: iso_extract - module: win_unzip author: Michael DeHaan ''' diff --git a/lib/ansible/modules/files/xattr.py b/lib/ansible/modules/files/xattr.py index 676436fec0..d231001c09 100644 --- a/lib/ansible/modules/files/xattr.py +++ b/lib/ansible/modules/files/xattr.py @@ -16,26 +16,31 @@ module: xattr version_added: "1.3" short_description: Manage user defined extended attributes description: - - Manages filesystem user defined extended attributes, requires that they are enabled - on the target filesystem and that the setfattr/getfattr utilities are present. + - Manages filesystem user defined extended attributes. + - Requires that extended attributes are enabled on the target filesystem + and that the setfattr/getfattr utilities are present. options: path: description: - The full path of the file/object to get the facts of. - Before 2.3 this option was only usable as I(name). - aliases: [ name ] + type: path required: true + aliases: [ name ] namespace: description: - Namespace of the named name/key. + type: str default: user version_added: "2.7" key: description: - The name of a specific Extended attribute key to set/retrieve. + type: str value: description: - The value to set the named name/key to, it automatically sets the C(state) to 'set'. + type: str state: description: - defines which state you want to do. @@ -44,6 +49,7 @@ options: C(all) dumps all data C(keys) retrieves all keys C(absent) deletes the key + type: str choices: [ absent, all, keys, present, read ] default: read follow: @@ -51,7 +57,7 @@ options: - If C(yes), dereferences symlinks and sets/gets attributes on symlink target, otherwise acts on symlink itself. type: bool - default: 'yes' + default: yes 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: diff --git a/lib/ansible/modules/net_tools/basics/get_url.py b/lib/ansible/modules/net_tools/basics/get_url.py index 6a3b3574d8..2c3f8d8c67 100644 --- a/lib/ansible/modules/net_tools/basics/get_url.py +++ b/lib/ansible/modules/net_tools/basics/get_url.py @@ -36,6 +36,7 @@ options: url: description: - HTTP, HTTPS, or FTP URL in the form (http|https|ftp)://[user[:pass]]@host.domain[:port]/path + type: str required: true dest: description: @@ -45,6 +46,7 @@ options: used. If a directory, C(force) has no effect. - If C(dest) is a directory, the file will always be downloaded (regardless of the C(force) option), but replaced only if the contents changed.. + type: path required: true tmp_dest: description: @@ -52,6 +54,7 @@ options: - When run on Ansible 2.5 or greater, path defaults to ansible's remote_tmp setting - When run on Ansible prior to 2.5, it defaults to C(TMPDIR), C(TEMP) or C(TMP) env variables or a platform specific value. - U(https://docs.python.org/2/library/tempfile.html#tempfile.tempdir) + type: path version_added: '2.1' force: description: @@ -60,17 +63,16 @@ options: will only be downloaded if the destination does not exist. Generally should be C(yes) only for small local files. - Prior to 0.6, this module behaved as if C(yes) was the default. - version_added: '0.7' - default: 'no' type: bool + default: no aliases: [ thirsty ] + version_added: '0.7' backup: description: - Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. - required: false - default: 'no' type: bool + default: no version_added: '2.1' sha256sum: description: @@ -94,65 +96,71 @@ options: the C(dest) location, the I(destination_checksum) would be calculated, and if checksum equals I(destination_checksum), the file download would be skipped (unless C(force) is true). + type: str default: '' version_added: "2.0" use_proxy: description: - if C(no), it will not use a proxy, even if one is defined in an environment variable on the target hosts. - default: 'yes' type: bool + default: yes validate_certs: description: - - If C(no), SSL certificates will not be validated. This should only be used - on personally controlled sites using self-signed certificates. - default: 'yes' + - If C(no), SSL certificates will not be validated. + - This should only be used on personally controlled sites using self-signed certificates. type: bool + default: yes timeout: description: - Timeout in seconds for URL request. + type: int default: 10 version_added: '1.8' headers: description: - - Add custom HTTP headers to a request in hash/dict format. The hash/dict format was added in 2.6. - Previous versions used a C("key:value,key:value") string format. The C("key:value,key:value") string - format is deprecated and will be removed in version 2.10. + - Add custom HTTP headers to a request in hash/dict format. + - The hash/dict format was added in 2.6. + - Previous versions used a C("key:value,key:value") string format. + - The C("key:value,key:value") string format is deprecated and will be removed in version 2.10. + type: str version_added: '2.0' url_username: description: - The username for use in HTTP basic authentication. - This parameter can be used without C(url_password) for sites that allow empty passwords. - - Since version 2.8 you can also use the 'username' alias for this option. - version_added: '1.6' + - Since version 2.8 you can also use the C(username) alias for this option. + type: str aliases: ['username'] + version_added: '1.6' url_password: description: - The password for use in HTTP basic authentication. - If the C(url_username) parameter is not specified, the C(url_password) parameter will not be used. - Since version 2.8 you can also use the 'password' alias for this option. - version_added: '1.6' + type: str aliases: ['password'] + version_added: '1.6' force_basic_auth: - version_added: '2.0' description: + - Force the sending of the Basic authentication header upon initial request. - httplib2, the library used by the uri module only sends authentication information when a webservice responds to an initial request with a 401 status. Since some basic auth services do not properly - send a 401, logins will fail. This option forces the sending of the Basic authentication header - upon initial request. - default: 'no' + send a 401, logins will fail. type: bool + default: no + version_added: '2.0' client_cert: description: - - PEM formatted certificate chain file to be used for SSL client - authentication. This file can also include the key as well, and if - the key is included, C(client_key) is not required. + - PEM formatted certificate chain file to be used for SSL client authentication. + - This file can also include the key as well, and if the key is included, C(client_key) is not required. + type: str version_added: '2.4' client_key: description: - - PEM formatted file that contains your private key to be used for SSL - client authentication. If C(client_cert) contains both the certificate - and key, this option is not required. + - PEM formatted file that contains your private key to be used for SSL client authentication. + - If C(client_cert) contains both the certificate and key, this option is not required. + type: str version_added: '2.4' # informational: requirements for nodes extends_documentation_fragment: @@ -171,7 +179,7 @@ EXAMPLES = r''' get_url: url: http://example.com/path/file.conf dest: /etc/foo.conf - mode: 0440 + mode: '0440' - name: Download file and force basic auth get_url: @@ -203,7 +211,7 @@ EXAMPLES = r''' get_url: url: http://example.com/path/file.conf dest: /etc/foo.conf - checksum: 'sha256:http://example.com/path/sha256sum.txt' + checksum: sha256:http://example.com/path/sha256sum.txt - name: Download file from a file path get_url: diff --git a/lib/ansible/modules/net_tools/basics/slurp.py b/lib/ansible/modules/net_tools/basics/slurp.py index 84c9ae2fa8..2bc70c9f2f 100644 --- a/lib/ansible/modules/net_tools/basics/slurp.py +++ b/lib/ansible/modules/net_tools/basics/slurp.py @@ -24,8 +24,8 @@ description: options: src: description: - - The file on the remote system to fetch. This I(must) be a file, not a - directory. + - The file on the remote system to fetch. This I(must) be a file, not a directory. + type: path required: true notes: - This module returns an 'in memory' base64 encoded version of the file, take into account that this will require at least twice the RAM as the diff --git a/lib/ansible/modules/net_tools/basics/uri.py b/lib/ansible/modules/net_tools/basics/uri.py index 8a16453d8d..35e0a916ae 100644 --- a/lib/ansible/modules/net_tools/basics/uri.py +++ b/lib/ansible/modules/net_tools/basics/uri.py @@ -25,53 +25,60 @@ options: url: description: - HTTP or HTTPS URL in the form (http|https)://host.domain[:port]/path + type: str required: true dest: description: - A path of where to download the file to (if desired). If I(dest) is a directory, the basename of the file on the remote server will be used. + type: path user: description: - A username for the module to use for Digest, Basic or WSSE authentication. + type: str password: description: - A password for the module to use for Digest, Basic or WSSE authentication. + type: str body: description: - The body of the http request/response to the web service. If C(body_format) is set to 'json' it will take an already formatted JSON string or convert a data structure into JSON. If C(body_format) is set to 'form-urlencoded' it will convert a dictionary or list of tuples into an 'application/x-www-form-urlencoded' string. (Added in v2.7) + type: raw body_format: description: - The serialization format of the body. When set to C(json) or C(form-urlencoded), encodes the body argument, if needed, and automatically sets the Content-Type header accordingly. As of C(2.3) it is possible to override the `Content-Type` header, when set to C(json) or C(form-urlencoded) via the I(headers) option. + type: str choices: [ form-urlencoded, json, raw ] default: raw version_added: "2.0" method: description: - The HTTP method of the request or response. It MUST be uppercase. + type: str choices: [ CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, REFRESH, TRACE ] default: GET return_content: description: - Whether or not to return the body of the response as a "content" key in - the dictionary result. If the reported Content-type is - "application/json", then the JSON is additionally loaded into a key - called C(json) in the dictionary results. + the dictionary result. + - If the reported Content-type is "application/json", then the JSON is + additionally loaded into a key called C(json) in the dictionary results. type: bool - default: 'no' + default: no force_basic_auth: description: + - Force the sending of the Basic authentication header upon initial request. - The library used by the uri module only sends authentication information when a webservice responds to an initial request with a 401 status. Since some basic auth services do not properly - send a 401, logins will fail. This option forces the sending of the Basic authentication header - upon initial request. + send a 401, logins will fail. type: bool - default: 'no' + default: no follow_redirects: description: - Whether or not the URI module should follow redirects. C(all) will follow all redirects. @@ -80,69 +87,77 @@ options: any redirects. Note that C(yes) and C(no) choices are accepted for backwards compatibility, where C(yes) is the equivalent of C(all) and C(no) is the equivalent of C(safe). C(yes) and C(no) are deprecated and will be removed in some future version of Ansible. + type: str choices: [ all, 'none', safe ] default: safe creates: description: - A filename, when it already exists, this step will not be run. + type: path removes: description: - A filename, when it does not exist, this step will not be run. + type: path status_code: description: - - A list of valid, numeric, HTTP status codes that signifies success of the - request. + - A list of valid, numeric, HTTP status codes that signifies success of the request. + type: int default: 200 timeout: description: - The socket level timeout in seconds + type: int default: 30 HEADER_: description: - Any parameter starting with "HEADER_" is a sent with your request as a header. For example, HEADER_Content-Type="application/json" would send the header "Content-Type" along with your request with a value of "application/json". - This option is deprecated as of C(2.1) and will be removed in Ansible-2.9. + - This option is deprecated as of C(2.1) and will be removed in Ansible 2.9. Use I(headers) instead. + type: dict headers: description: - Add custom HTTP headers to a request in the format of a YAML hash. As of C(2.3) supplying C(Content-Type) here will override the header generated by supplying C(json) or C(form-urlencoded) for I(body_format). + type: dict version_added: '2.1' others: description: - All arguments accepted by the M(file) module also work here validate_certs: description: - - If C(no), SSL certificates will not be validated. This should only - set to C(no) used on personally controlled sites using self-signed - certificates. Prior to 1.9.2 the code defaulted to C(no). + - If C(no), SSL certificates will not be validated. + - This should only set to C(no) used on personally controlled sites using self-signed certificates. + - Prior to 1.9.2 the code defaulted to C(no). type: bool - default: 'yes' + default: yes version_added: '1.9.2' client_cert: description: - - PEM formatted certificate chain file to be used for SSL client - authentication. This file can also include the key as well, and if - the key is included, I(client_key) is not required + - PEM formatted certificate chain file to be used for SSL client authentication. + - This file can also include the key as well, and if the key is included, I(client_key) is not required + type: path version_added: '2.4' client_key: description: - - PEM formatted file that contains your private key to be used for SSL - client authentication. If I(client_cert) contains both the certificate - and key, this option is not required. + - PEM formatted file that contains your private key to be used for SSL client authentication. + - If I(client_cert) contains both the certificate and key, this option is not required. + type: path version_added: '2.4' src: description: - - Path to file to be submitted to the remote server. Cannot be used with I(body). + - Path to file to be submitted to the remote server. + - Cannot be used with I(body). + type: path version_added: '2.7' remote_src: description: - - If C(no), the module will search for src on originating/master machine, if C(yes) the - module will use the C(src) path on the remote/target machine. + - If C(no), the module will search for src on originating/master machine. + - If C(yes) the module will use the C(src) path on the remote/target machine. type: bool - default: 'no' + default: no version_added: '2.7' notes: - The dependency on httplib2 was removed in Ansible 2.1. diff --git a/lib/ansible/modules/system/aix_inittab.py b/lib/ansible/modules/system/aix_inittab.py index b9efdc1ef7..d19315250b 100644 --- a/lib/ansible/modules/system/aix_inittab.py +++ b/lib/ansible/modules/system/aix_inittab.py @@ -1,7 +1,7 @@ #!/usr/bin/python # -*- coding: utf-8 -*- -# (c) 2017, Joris Weijters +# Copyright: (c) 2017, Joris Weijters # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) from __future__ import absolute_import, division, print_function @@ -24,15 +24,18 @@ options: name: description: - Name of the inittab entry. + type: str required: yes - aliases: ['service'] + aliases: [ service ] runlevel: description: - Runlevel of the entry. + type: str required: yes action: description: - Action what the init has to do with this entry. + type: str required: yes choices: - boot @@ -50,18 +53,21 @@ options: command: description: - What command has to run. + type: str required: yes insertafter: description: - After which inittabline should the new entry inserted. + type: str state: description: - Whether the entry should be present or absent in the inittab file. + type: str choices: [ absent, present ] default: present notes: - - The changes are persistent across reboots, you need root rights to read or adjust the inittab with the C(lsitab), chitab, - C(mkitab) or C(rmitab) commands. + - The changes are persistent across reboots. + - You need root rights to read or adjust the inittab with the C(lsitab), C(chitab), C(mkitab) or C(rmitab) commands. - Tested on AIX 7.1. requirements: - itertools @@ -101,17 +107,17 @@ EXAMPLES = ''' RETURN = ''' name: - description: name of the adjusted inittab entry + description: Name of the adjusted inittab entry returned: always type: str sample: startmyservice msg: - description: action done with the inittab entry + description: Action done with the inittab entry returned: changed type: str sample: changed inittab entry startmyservice changed: - description: whether the inittab changed or not + description: Whether the inittab changed or not returned: always type: bool sample: true diff --git a/lib/ansible/modules/system/aix_lvol.py b/lib/ansible/modules/system/aix_lvol.py index 01bcae21ff..7f47f17c35 100644 --- a/lib/ansible/modules/system/aix_lvol.py +++ b/lib/ansible/modules/system/aix_lvol.py @@ -1,7 +1,7 @@ #!/usr/bin/python # -*- coding: utf-8 -*- -# (c) 2016, Alain Dejoux +# Copyright: (c) 2016, Alain Dejoux # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) from __future__ import absolute_import, division, print_function @@ -25,40 +25,51 @@ options: vg: description: - The volume group this logical volume is part of. + type: str required: true lv: description: - The name of the logical volume. + type: str required: true lv_type: description: - The type of the logical volume. + type: str default: jfs2 size: description: - The size of the logical volume with one of the [MGT] units. + type: str copies: description: - - The number of copies of the logical volume. Maximum copies are 3. - default: '1' + - The number of copies of the logical volume. + - Maximum copies are 3. + type: int + default: 1 policy: + description: + - Sets the interphysical volume allocation policy. + - C(maximum) allocates logical partitions across the maximum number of physical volumes. + - C(minimum) allocates logical partitions across the minimum number of physical volumes. + type: str choices: [ maximum, minimum ] default: maximum - description: - - Sets the interphysical volume allocation policy. C(maximum) allocates logical partitions across the maximum number of physical volumes. - C(minimum) allocates logical partitions across the minimum number of physical volumes. state: - choices: [ absent, present ] - default: present description: - Control if the logical volume exists. If C(present) and the volume does not already exist then the C(size) option is required. + type: str + choices: [ absent, present ] + default: present opts: description: - Free-form options to be passed to the mklv command. + type: str pvs: description: - - Comma separated list of physical volumes e.g. C(hdisk1,hdisk2). + - A list of physical volumes e.g. C(hdisk1,hdisk2). + type: list ''' EXAMPLES = r''' @@ -73,7 +84,7 @@ EXAMPLES = r''' vg: testvg lv: test2lv size: 512M - pvs: hdisk1,hdisk2 + pvs: [ hdisk1, hdisk2 ] - name: Create a logical volume of 512M mirrored aix_lvol: @@ -205,7 +216,7 @@ def main(): lv_type=dict(type='str', default='jfs2'), size=dict(type='str'), opts=dict(type='str', default=''), - copies=dict(type='str', default='1'), + copies=dict(type='str', default=1), state=dict(type='str', default='present', choices=['absent', 'present']), policy=dict(type='str', default='maximum', choices=['maximum', 'minimum']), pvs=dict(type='list', default=list()) diff --git a/lib/ansible/modules/system/alternatives.py b/lib/ansible/modules/system/alternatives.py index 7b49447f58..64126e432c 100644 --- a/lib/ansible/modules/system/alternatives.py +++ b/lib/ansible/modules/system/alternatives.py @@ -1,8 +1,8 @@ #!/usr/bin/python # -*- coding: utf-8 -*- -# (c) 2014, Gabe Mulley -# (c) 2015, David Wittman +# Copyright: (c) 2014, Gabe Mulley +# Copyright: (c) 2015, David Wittman # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) from __future__ import absolute_import, division, print_function @@ -14,54 +14,56 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'supported_by': 'community'} -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- module: alternatives short_description: Manages alternative programs for common commands description: - - Manages symbolic links using the 'update-alternatives' tool + - Manages symbolic links using the 'update-alternatives' tool. - Useful when multiple programs are installed but provide similar functionality (e.g. different editors). version_added: "1.6" author: - - "David Wittman (@DavidWittman)" - - "Gabe Mulley (@mulby)" + - David Wittman (@DavidWittman) + - Gabe Mulley (@mulby) options: name: description: - The generic name of the link. + type: str required: true path: description: - The path to the real executable that the link should point to. + type: path required: true link: description: - The path to the symbolic link that should point to the real executable. - This option is always required on RHEL-based distributions. On Debian-based distributions this option is required when the alternative I(name) is unknown to the system. - required: false + type: path priority: description: - - The priority of the alternative - required: false + - The priority of the alternative. + type: int default: 50 version_added: "2.2" requirements: [ update-alternatives ] ''' -EXAMPLES = ''' -- name: correct java version selected +EXAMPLES = r''' +- name: Correct java version selected alternatives: name: java path: /usr/lib/jvm/java-7-openjdk-amd64/jre/bin/java -- name: alternatives link created +- name: Alternatives link created alternatives: name: hadoop-conf link: /etc/hadoop/conf path: /etc/hadoop/conf.ansible -- name: make java 32 bit an alternative with low priority +- name: Make java 32 bit an alternative with low priority alternatives: name: java path: /usr/lib/jvm/java-7-openjdk-i386/jre/bin/java @@ -79,11 +81,10 @@ def main(): module = AnsibleModule( argument_spec=dict( - name=dict(required=True), - path=dict(required=True, type='path'), - link=dict(required=False, type='path'), - priority=dict(required=False, type='int', - default=50), + name=dict(type='str', required=True), + path=dict(type='path', required=True), + link=dict(type='path'), + priority=dict(type='int', default=50), ), supports_check_mode=True, ) diff --git a/lib/ansible/modules/system/at.py b/lib/ansible/modules/system/at.py index 9516687679..86a577ad3b 100644 --- a/lib/ansible/modules/system/at.py +++ b/lib/ansible/modules/system/at.py @@ -23,28 +23,33 @@ options: command: description: - A command to be executed in the future. + type: str script_file: description: - An existing script file to be executed in the future. + type: str count: description: - The count of units in the future to execute the command or script file. + type: int required: true units: description: - The type of units in the future to execute the command or script file. - choices: [ minutes, hours, days, weeks ] + type: str required: true + choices: [ minutes, hours, days, weeks ] state: description: - The state dictates if the command or script file should be evaluated as present(added) or absent(deleted). + type: str choices: [ absent, present ] default: present unique: description: - If a matching job is present a new job will not be added. type: bool - default: 'no' + default: no requirements: - at author: @@ -52,18 +57,18 @@ author: ''' EXAMPLES = ''' -- name: Schedule a command to execute in 20 minutes as root. +- name: Schedule a command to execute in 20 minutes as root at: command: ls -d / >/dev/null count: 20 units: minutes -- name: Match a command to an existing job and delete the job. +- name: Match a command to an existing job and delete the job at: command: ls -d / >/dev/null state: absent -- name: Schedule a command to execute in 20 minutes making sure it is unique in the queue. +- name: Schedule a command to execute in 20 minutes making sure it is unique in the queue at: command: ls -d / >/dev/null count: 20 @@ -140,7 +145,7 @@ def main(): script_file=dict(type='str'), count=dict(type='int'), units=dict(type='str', choices=['minutes', 'hours', 'days', 'weeks']), - state=dict(type='str', default='present', choices=['present', 'absent']), + state=dict(type='str', default='present', choices=['absent', 'present']), unique=dict(type='bool', default=False), ), mutually_exclusive=[['command', 'script_file']], diff --git a/lib/ansible/modules/system/authorized_key.py b/lib/ansible/modules/system/authorized_key.py index 3df600161a..09d7c53249 100644 --- a/lib/ansible/modules/system/authorized_key.py +++ b/lib/ansible/modules/system/authorized_key.py @@ -1,7 +1,7 @@ #!/usr/bin/python # -*- coding: utf-8 -*- -# (c) 2012, Brad Olson +# Copyright: (c) 2012, Brad Olson # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) from __future__ import absolute_import, division, print_function @@ -13,81 +13,86 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'supported_by': 'core'} -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- module: authorized_key short_description: Adds or removes an SSH authorized key description: - - "Adds or removes SSH authorized keys for particular user accounts" + - Adds or removes SSH authorized keys for particular user accounts. version_added: "0.5" options: user: description: - - The username on the remote host whose authorized_keys file will be modified + - The username on the remote host whose authorized_keys file will be modified. + type: str required: true key: description: - - The SSH public key(s), as a string or (since 1.9) url (https://github.com/username.keys) + - The SSH public key(s), as a string or (since Ansible 1.9) url (https://github.com/username.keys). + type: str required: true path: description: - - Alternate path to the authorized_keys file - default: "(homedir)+/.ssh/authorized_keys" + - Alternate path to the authorized_keys file. + - When unset, this value defaults to I(~/.ssh/authorized_keys). + type: path version_added: "1.2" manage_dir: description: - - Whether this module should manage the directory of the authorized key file. If - set, the module will create the directory, as well as set the owner and permissions - of an existing directory. Be sure to - set C(manage_dir=no) if you are using an alternate directory for - authorized_keys, as set with C(path), since you could lock yourself out of - SSH access. See the example below. + - Whether this module should manage the directory of the authorized key file. + - If set to C(yes), the module will create the directory, as well as set the owner and permissions + of an existing directory. + - Be sure to set C(manage_dir=no) if you are using an alternate directory for authorized_keys, + as set with C(path), since you could lock yourself out of SSH access. + - See the example below. type: bool - default: 'yes' + default: yes version_added: "1.2" state: description: - - Whether the given key (with the given key_options) should or should not be in the file - choices: [ "present", "absent" ] - default: "present" + - Whether the given key (with the given key_options) should or should not be in the file. + type: str + choices: [ absent, present ] + default: present key_options: description: - - A string of ssh key options to be prepended to the key in the authorized_keys file + - A string of ssh key options to be prepended to the key in the authorized_keys file. version_added: "1.4" exclusive: description: - - Whether to remove all other non-specified keys from the authorized_keys file. Multiple keys - can be specified in a single C(key) string value by separating them by newlines. - - This option is not loop aware, so if you use C(with_) , it will be exclusive per iteration - of the loop, if you want multiple keys in the file you need to pass them all to C(key) in a - single batch as mentioned above. + - Whether to remove all other non-specified keys from the authorized_keys file. + - Multiple keys can be specified in a single C(key) string value by separating them by newlines. + - This option is not loop aware, so if you use C(with_) , it will be exclusive per iteration of the loop. + - If you want multiple keys in the file you need to pass them all to C(key) in a single batch as mentioned above. type: bool - default: 'no' + default: no version_added: "1.9" validate_certs: description: - - This only applies if using a https url as the source of the keys. If set to C(no), the SSL certificates will not be validated. + - This only applies if using a https url as the source of the keys. + - If set to C(no), the SSL certificates will not be validated. - This should only set to C(no) used on personally controlled sites using self-signed certificates as it avoids verifying the source site. - Prior to 2.1 the code worked as if this was set to C(yes). type: bool - default: 'yes' + default: yes version_added: "2.1" comment: description: - - Change the comment on the public key. Rewriting the comment is useful in - cases such as fetching it from GitHub or GitLab. + - Change the comment on the public key. + - Rewriting the comment is useful in cases such as fetching it from GitHub or GitLab. - If no comment is specified, the existing comment will be kept. + type: str version_added: "2.4" follow: description: - - Follow path symlink instead of replacing it + - Follow path symlink instead of replacing it. type: bool - default: 'no' + default: no version_added: "2.7" -author: "Ansible Core Team" +author: Ansible Core Team ''' -EXAMPLES = ''' +EXAMPLES = r''' - name: Set authorized key taken from file authorized_key: user: charlie @@ -147,7 +152,7 @@ EXAMPLES = ''' key: "{{ lookup('file', lookup('env','HOME') + '/.ssh/id_rsa.pub') }}" ''' -RETURN = ''' +RETURN = r''' exclusive: description: If the key has been forced to be exclusive or not. returned: success @@ -655,19 +660,18 @@ def enforce_state(module, params): def main(): module = AnsibleModule( argument_spec=dict( - user=dict(required=True, type='str'), - key=dict(required=True, type='str'), - path=dict(required=False, type='str'), - manage_dir=dict(required=False, type='bool', default=True), - state=dict(default='present', choices=['absent', 'present']), - key_options=dict(required=False, type='str'), - unique=dict(default=False, type='bool'), - exclusive=dict(default=False, type='bool'), - comment=dict(required=False, default=None, type='str'), - validate_certs=dict(default=True, type='bool'), - follow=dict(default=False, type='bool') + user=dict(type='str', required=True), + key=dict(type='str', required=True), + path=dict(type='str'), + manage_dir=dict(type='bool', default=True), + state=dict(type='str', default='present', choices=['absent', 'present']), + key_options=dict(type='str'), + exclusive=dict(type='bool', default=False), + comment=dict(type='str'), + validate_certs=dict(type='bool', default=True), + follow=dict(type='bool', default=False), ), - supports_check_mode=True + supports_check_mode=True, ) results = enforce_state(module, module.params) diff --git a/lib/ansible/modules/system/awall.py b/lib/ansible/modules/system/awall.py index 818e41bb4c..3695621ec6 100644 --- a/lib/ansible/modules/system/awall.py +++ b/lib/ansible/modules/system/awall.py @@ -1,7 +1,7 @@ #!/usr/bin/python # -*- coding: utf-8 -*- -# -# (c) 2017, Ted Trask + +# Copyright: (c) 2017, Ted Trask # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) from __future__ import absolute_import, division, print_function @@ -12,7 +12,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['stableinterface'], 'supported_by': 'community'} -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- module: awall short_description: Manage awall policies @@ -20,40 +20,44 @@ version_added: "2.4" author: Ted Trask (@tdtrask) description: - This modules allows for enable/disable/activate of I(awall) policies. - Alpine Wall (I(awall)) generates a firewall configuration from the enabled policy files + - Alpine Wall (I(awall)) generates a firewall configuration from the enabled policy files and activates the configuration on the system. options: name: description: - - A policy name, like C(foo), or multiple policies, like C(foo, bar). + - One or more policy names. + type: list state: description: - - The policy(ies) will be C(enabled) - - The policy(ies) will be C(disabled) + - Whether the policies should be enabled or disabled. + type: str + choices: [ disabled, enabled ] default: enabled - choices: [ "enabled", "disabled" ] activate: description: - - Activate the new firewall rules. Can be run with other steps or on it's own. + - Activate the new firewall rules. + - Can be run with other steps or on its own. type: bool - default: 'no' + default: no ''' -EXAMPLES = ''' +EXAMPLES = r''' - name: Enable "foo" and "bar" policy awall: - name: foo,bar + name: [ foo bar ] state: enabled - name: Disable "foo" and "bar" policy and activate new rules awall: - name: foo,bar + name: + - foo + - bar state: disabled - activate: False + activate: no - name: Activate currently enabled firewall rules awall: - activate: True + activate: yes ''' RETURN = ''' # ''' @@ -122,12 +126,12 @@ def disable_policy(module, names, act): def main(): module = AnsibleModule( argument_spec=dict( - state=dict(default='enabled', choices=['enabled', 'disabled']), + state=dict(type='str', default='enabled', choices=['disabled', 'enabled']), name=dict(type='list'), - activate=dict(default=False, type='bool'), + activate=dict(type='bool', default=False), ), required_one_of=[['name', 'activate']], - supports_check_mode=True + supports_check_mode=True, ) global AWALL_PATH diff --git a/lib/ansible/modules/system/beadm.py b/lib/ansible/modules/system/beadm.py index 1dd474f1dc..1c3764ca16 100644 --- a/lib/ansible/modules/system/beadm.py +++ b/lib/ansible/modules/system/beadm.py @@ -1,7 +1,7 @@ #!/usr/bin/python # -*- coding: utf-8 -*- -# (c) 2016, Adam Števko +# Copyright: (c) 2016, Adam Števko # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) from __future__ import absolute_import, division, print_function @@ -13,7 +13,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'supported_by': 'community'} -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- module: beadm short_description: Manage ZFS boot environments on FreeBSD/Solaris/illumos systems. @@ -26,47 +26,43 @@ options: name: description: - ZFS boot environment name. - aliases: [ "be" ] + type: str required: True + aliases: [ "be" ] snapshot: description: - If specified, the new boot environment will be cloned from the given snapshot or inactive boot environment. - required: false - default: false + type: str description: description: - Associate a description with a new boot environment. This option is available only on Solarish platforms. - required: false - default: false + type: str options: description: - - Create the datasets for new BE with specific ZFS properties. Multiple - options can be specified. This option is available only on - Solarish platforms. - required: false - default: false + - Create the datasets for new BE with specific ZFS properties. + - Multiple options can be specified. + - This option is available only on Solarish platforms. + type: str mountpoint: description: - - Path where to mount the ZFS boot environment - required: false - default: false + - Path where to mount the ZFS boot environment. + type: path state: description: - Create or delete ZFS boot environment. - required: false - default: "present" - choices: [ "present", "absent", "activated", "mounted", "unmounted" ] + type: str + choices: [ absent, activated, mounted, present, unmounted ] + default: present force: description: - Specifies if the unmount should be forced. - required: false - default: false type: bool + default: false ''' -EXAMPLES = ''' +EXAMPLES = r''' - name: Create ZFS boot environment beadm: name: upgrade-be @@ -107,7 +103,7 @@ EXAMPLES = ''' state: activated ''' -RETURN = ''' +RETURN = r''' name: description: BE name returned: always @@ -139,7 +135,7 @@ state: type: str sample: present force: - description: if forced action is wanted + description: If forced action is wanted returned: always type: bool sample: False @@ -288,18 +284,15 @@ class BE(object): def main(): module = AnsibleModule( argument_spec=dict( - name=dict(required=True, aliases=['be'], type='str'), + name=dict(type='str', required=True, aliases=['be']), snapshot=dict(type='str'), description=dict(type='str'), options=dict(type='str'), - mountpoint=dict(default=False, type='path'), - state=dict( - default='present', - choices=['present', 'absent', 'activated', - 'mounted', 'unmounted']), - force=dict(default=False, type='bool'), + mountpoint=dict(type='path'), + state=dict(type='str', default='present', choices=['absent', 'activated', 'mounted', 'present', 'unmounted']), + force=dict(type='bool', default=False), ), - supports_check_mode=True + supports_check_mode=True, ) be = BE(module) diff --git a/lib/ansible/modules/system/capabilities.py b/lib/ansible/modules/system/capabilities.py index 38064229b7..369662618d 100644 --- a/lib/ansible/modules/system/capabilities.py +++ b/lib/ansible/modules/system/capabilities.py @@ -11,7 +11,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['preview'], 'supported_by': 'community'} -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- module: capabilities short_description: Manage Linux capabilities @@ -22,28 +22,30 @@ options: path: description: - Specifies the path to the file to be managed. + type: str required: yes capability: description: - Desired capability to set (with operator and flags, if state is C(present)) or remove (if state is C(absent)) + type: str required: yes aliases: [ cap ] state: description: - Whether the entry should be present or absent in the file's capabilities. + type: str choices: [ absent, present ] default: present notes: - - The capabilities system will automatically transform operators and flags - into the effective set, so (for example, cap_foo=ep will probably become - cap_foo+ep). This module does not attempt to determine the final operator - and flags to compare, so you will want to ensure that your capabilities - argument matches the final capabilities. + - The capabilities system will automatically transform operators and flags into the effective set, + so for example, C(cap_foo=ep) will probably become C(cap_foo+ep). + - This module does not attempt to determine the final operator and flags to compare, + so you will want to ensure that your capabilities argument matches the final capabilities. author: - Nate Coraor (@natefoo) ''' -EXAMPLES = ''' +EXAMPLES = r''' - name: Set cap_sys_chroot+ep on /foo capabilities: path: /foo diff --git a/lib/ansible/modules/system/firewalld.py b/lib/ansible/modules/system/firewalld.py index 94e1e75b74..3d49834e72 100644 --- a/lib/ansible/modules/system/firewalld.py +++ b/lib/ansible/modules/system/firewalld.py @@ -65,9 +65,9 @@ options: default: system-default(public) permanent: description: - - > - Should this configuration be in the running firewalld configuration or persist across reboots. As of Ansible version 2.3, permanent operations can - operate on firewalld configs when it's not running (requires firewalld >= 3.0.9). (NOTE: If this is false, immediate is assumed true.) + - Should this configuration be in the running firewalld configuration or persist across reboots. + - As of Ansible 2.3, permanent operations can operate on firewalld configs when it is not running (requires firewalld >= 3.0.9). + - Note that if this is C(no), immediate is assumed C(yes). type: bool immediate: description: diff --git a/lib/ansible/modules/system/group.py b/lib/ansible/modules/system/group.py index a95bc3c3d9..bf0dfabfe9 100644 --- a/lib/ansible/modules/system/group.py +++ b/lib/ansible/modules/system/group.py @@ -14,8 +14,6 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', DOCUMENTATION = ''' --- module: group -author: -- Stephen Fromm (@sfromm) version_added: "0.0.2" short_description: Add or remove groups requirements: @@ -29,32 +27,37 @@ options: name: description: - Name of the group to manage. + type: str required: true gid: description: - Optional I(GID) to set for the group. + type: int state: description: - Whether the group should be present or not on the remote host. + type: str choices: [ absent, present ] default: present system: description: - If I(yes), indicates that the group created is a system group. type: bool - default: 'no' + default: no local: - version_added: "2.6" - required: false - default: 'no' - type: bool description: - Forces the use of "local" command alternatives on platforms that implement it. - This is useful in environments that use centralized authentication when you want to manipulate the local groups. - I.E. it uses `lgroupadd` instead of `useradd`. + - This is useful in environments that use centralized authentication when you want to manipulate the local groups. + (e.g. it uses C(lgroupadd) instead of C(useradd)). - This requires that these commands exist on the targeted host, otherwise it will be a fatal error. -notes: - - For Windows targets, use the M(win_group) module instead. + type: bool + default: no + version_added: "2.6" +seealso: +- module: user +- module: win_group +author: +- Stephen Fromm (@sfromm) ''' EXAMPLES = ''' diff --git a/lib/ansible/modules/system/lvg.py b/lib/ansible/modules/system/lvg.py index ae16e92a79..abd8039656 100644 --- a/lib/ansible/modules/system/lvg.py +++ b/lib/ansible/modules/system/lvg.py @@ -12,7 +12,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['preview'], 'supported_by': 'community'} -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- author: - Alexander Bulimov (@abulimov) @@ -25,40 +25,50 @@ options: vg: description: - The name of the volume group. + type: str required: true pvs: description: - - List of comma-separated devices to use as physical devices in this volume group. Required when creating or resizing volume group. + - List of comma-separated devices to use as physical devices in this volume group. + - Required when creating or resizing volume group. - The module will take care of running pvcreate if needed. + type: list pesize: description: - - The size of the physical extent. pesize must be a power of 2, or - multiple of 128KiB. Since version 2.6, pesize can be optionally suffixed - by a UNIT (k/K/m/M/g/G), default unit is megabyte. + - The size of the physical extent. pesize must be a power of 2, or multiple of 128KiB. + - Since Ansible 2.6, pesize can be optionally suffixed by a UNIT (k/K/m/M/g/G), default unit is megabyte. + type: int default: 4 pv_options: description: - Additional options to pass to C(pvcreate) when creating the volume group. + type: str version_added: "2.4" vg_options: description: - Additional options to pass to C(vgcreate) when creating the volume group. + type: str version_added: "1.6" state: description: - Control if the volume group exists. + type: str choices: [ absent, present ] default: present force: description: - If C(yes), allows to remove volume group with logical volumes. type: bool - default: 'no' + default: no +seealso: +- module: filesystem +- module: lvol +- module: parted notes: - This module does not modify PE size for already present volume group. ''' -EXAMPLES = ''' +EXAMPLES = r''' - name: Create a volume group on top of /dev/sda1 with physical extent size = 32MB lvg: vg: vg.services diff --git a/lib/ansible/modules/system/pamd.py b/lib/ansible/modules/system/pamd.py index 5ed000562e..1337c54fab 100644 --- a/lib/ansible/modules/system/pamd.py +++ b/lib/ansible/modules/system/pamd.py @@ -1,7 +1,7 @@ #!/usr/bin/python # -*- coding: utf-8 -*- -# (c) 2017, Kenneth D. Evensen +# Copyright: (c) 2017, Kenneth D. Evensen # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) from __future__ import (absolute_import, division, print_function) @@ -13,93 +13,93 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'supported_by': 'community'} -DOCUMENTATION = """ +DOCUMENTATION = r''' module: pamd author: - - "Kenneth D. Evensen (@kevensen)" + - Kenneth D. Evensen (@kevensen) short_description: Manage PAM Modules description: - Edit PAM service's type, control, module path and module arguments. - In order for a PAM rule to be modified, the type, control and + - In order for a PAM rule to be modified, the type, control and module_path must match an existing rule. See man(5) pam.d for details. version_added: "2.3" options: name: - required: true description: - The name generally refers to the PAM service file to change, for example system-auth. + type: str + required: true type: - required: true description: - - The type of the PAM rule being modified. The type, control - and module_path all must match a rule to be modified. + - The type of the PAM rule being modified. + - The C(type), C(control) and C(module_path) all must match a rule to be modified. + type: str + required: true control: - required: true description: - - The control of the PAM rule being modified. This may be a - complicated control with brackets. If this is the case, be - sure to put "[bracketed controls]" in quotes. The type, - control and module_path all must match a rule to be modified. + - The control of the PAM rule being modified. + - This may be a complicated control with brackets. If this is the case, be + sure to put "[bracketed controls]" in quotes. + - The C(type), C(control) and C(module_path) all must match a rule to be modified. + type: str + required: true module_path: - required: true description: - - The module path of the PAM rule being modified. The type, - control and module_path all must match a rule to be modified. + - The module path of the PAM rule being modified. + - The C(type), C(control) and C(module_path) all must match a rule to be modified. + type: str + required: true new_type: description: - The new type to assign to the new rule. + type: str new_control: description: - The new control to assign to the new rule. + type: str new_module_path: description: - The new module path to be assigned to the new rule. + type: str module_arguments: description: - - When state is 'updated', the module_arguments will replace existing - module_arguments. When state is 'args_absent' args matching those - listed in module_arguments will be removed. When state is - 'args_present' any args listed in module_arguments are added if - missing from the existing rule. Furthermore, if the module argument - takes a value denoted by '=', the value will be changed to that specified - in module_arguments. Note that module_arguments is a list. Please see - the examples for usage. + - When state is C(updated), the module_arguments will replace existing module_arguments. + - When state is C(args_absent) args matching those listed in module_arguments will be removed. + - When state is C(args_present) any args listed in module_arguments are added if + missing from the existing rule. + - Furthermore, if the module argument takes a value denoted by C(=), + the value will be changed to that specified in module_arguments. + type: list state: - default: updated - choices: - - updated - - before - - after - - args_present - - args_absent - - absent description: - - The default of 'updated' will modify an existing rule if type, - control and module_path all match an existing rule. With 'before', - the new rule will be inserted before a rule matching type, control - and module_path. Similarly, with 'after', the new rule will be inserted - after an existing rule matching type, control and module_path. With - either 'before' or 'after' new_type, new_control, and new_module_path - must all be specified. If state is 'args_absent' or 'args_present', - new_type, new_control, and new_module_path will be ignored. State - 'absent' will remove the rule. The 'absent' state was added in version - 2.4 and is only available in Ansible versions >= 2.4. + - The default of C(updated) will modify an existing rule if type, + control and module_path all match an existing rule. + - With C(before), the new rule will be inserted before a rule matching type, + control and module_path. + - Similarly, with C(after), the new rule will be inserted after an existing rulematching type, + control and module_path. + - With either C(before) or C(after) new_type, new_control, and new_module_path must all be specified. + - If state is C(args_absent) or C(args_present), new_type, new_control, and new_module_path will be ignored. + - State C(absent) will remove the rule. The 'absent' state was added in Ansible 2.4. + type: str + choices: [ absent, before, after, args_absent, args_present, updated ] + default: updated path: - default: /etc/pam.d/ description: - This is the path to the PAM service files + type: path + default: /etc/pam.d/ backup: description: - Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. type: bool - default: 'no' + default: no version_added: '2.6' +''' -""" - -EXAMPLES = """ +EXAMPLES = r''' - name: Update pamd rule's control in /etc/pam.d/system-auth pamd: name: system-auth @@ -220,9 +220,9 @@ EXAMPLES = """ type: auth module_path: pam_sss.so control: 'requisite' -""" +''' -RETURN = ''' +RETURN = r''' change_count: description: How many rules were changed type: int @@ -230,14 +230,14 @@ change_count: returned: success version_added: 2.4 new_rule: - description: The changes to the rule. This was available in Ansible version 2.4 and 2.5. It was removed in 2.6. + description: The changes to the rule. This was available in Ansible 2.4 and Ansible 2.5. It was removed in Ansible 2.6. type: str sample: None None None sha512 shadow try_first_pass use_authtok returned: success version_added: 2.4 updated_rule_(n): description: The rule(s) that was/were changed. This is only available in - Ansible version 2.4 and was removed in 2.5. + Ansible 2.4 and was removed in Ansible 2.5. type: str sample: - password sufficient pam_unix.so sha512 shadow try_first_pass @@ -248,7 +248,7 @@ action: description: - "That action that was taken and is one of: update_rule, insert_before_rule, insert_after_rule, args_present, args_absent, - absent. This was available in Ansible version 2.4 and removed in 2.8" + absent. This was available in Ansible 2.4 and removed in Ansible 2.8" returned: always type: str sample: "update_rule" @@ -256,7 +256,7 @@ action: dest: description: - "Path to pam.d service that was changed. This is only available in - Ansible version 2.3 and was removed in 2.4." + Ansible 2.3 and was removed in Ansible 2.4." returned: success type: str sample: "/etc/pam.d/system-auth" @@ -770,21 +770,17 @@ def main(): module = AnsibleModule( argument_spec=dict( - name=dict(required=True, type='str'), - type=dict(required=True, - choices=VALID_TYPES), - control=dict(required=True, type='str'), - module_path=dict(required=True, type='str'), - new_type=dict(required=False, - choices=VALID_TYPES), - new_control=dict(required=False, type='str'), - new_module_path=dict(required=False, type='str'), - module_arguments=dict(required=False, type='list'), - state=dict(required=False, default="updated", - choices=['before', 'after', 'updated', - 'args_absent', 'args_present', 'absent']), - path=dict(required=False, default='/etc/pam.d', type='str'), - backup=dict(default=False, type='bool') + name=dict(type='str', required=True), + type=dict(type='str', required=True, choices=VALID_TYPES), + control=dict(type='str', required=True), + module_path=dict(type='str', required=True), + new_type=dict(type='str', choices=VALID_TYPES), + new_control=dict(type='str'), + new_module_path=dict(type='str'), + module_arguments=dict(type='list'), + state=dict(type='str', default='updated', choices=['absent', 'after', 'args_absent', 'args_present', 'before', 'updated']), + path=dict(type='path', default='/etc/pam.d'), + backup=dict(type='bool', default=False), ), supports_check_mode=True, required_if=[ diff --git a/lib/ansible/modules/system/parted.py b/lib/ansible/modules/system/parted.py index 5ef98adfc8..fdae37f339 100644 --- a/lib/ansible/modules/system/parted.py +++ b/lib/ansible/modules/system/parted.py @@ -1,7 +1,7 @@ #!/usr/bin/python # -*- coding: utf-8 -*- -# (c) 2016, Fabrizio Colonna +# Copyright: (c) 2016, Fabrizio Colonna # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) from __future__ import absolute_import, division, print_function @@ -13,10 +13,10 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'supported_by': 'community'} -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- author: - - "Fabrizio Colonna (@ColOfAbRiX)" + - Fabrizio Colonna (@ColOfAbRiX) module: parted short_description: Configure block device partitions version_added: "2.3" @@ -24,11 +24,6 @@ description: - This module allows configuring block device partition using the C(parted) command line tool. For a full description of the fields and the options check the GNU parted manual. -notes: - - When fetching information about a new disk and when the version of parted - installed on the system is before version 3.1, the module queries the kernel - through C(/sys/) to obtain disk information. In this case the units CHS and - CYL are not supported. requirements: - This module requires parted version 1.8.3 and above. - If the version of parted is below 3.1, it requires a Linux version running @@ -36,70 +31,79 @@ requirements: options: device: description: The block device (disk) where to operate. + type: str required: True align: description: Set alignment for newly created partitions. - choices: ['none', 'cylinder', 'minimal', 'optimal'] + type: str + choices: [ cylinder, minimal, none, optimal ] default: optimal number: description: - - The number of the partition to work with or the number of the partition - that will be created. Required when performing any action on the disk, - except fetching information. + - The number of the partition to work with or the number of the partition + that will be created. + - Required when performing any action on the disk, except fetching information. + type: int unit: description: - - Selects the current default unit that Parted will use to display - locations and capacities on the disk and to interpret those given by the - user if they are not suffixed by an unit. When fetching information about - a disk, it is always recommended to specify a unit. - choices: [ - 's', 'B', 'KB', 'KiB', 'MB', 'MiB', 'GB', 'GiB', 'TB', 'TiB', '%', 'cyl', - 'chs', 'compact' - ] + - Selects the current default unit that Parted will use to display + locations and capacities on the disk and to interpret those given by the + user if they are not suffixed by an unit. + - When fetching information about a disk, it is always recommended to specify a unit. + type: str + choices: [ s, B, KB, KiB, MB, MiB, GB, GiB, TB, TiB, '%', cyl, chs, compact ] default: KiB label: description: Creates a new disk label. - choices: [ - 'aix', 'amiga', 'bsd', 'dvh', 'gpt', 'loop', 'mac', 'msdos', 'pc98', - 'sun' - ] + type: str + choices: [ aix, amiga, bsd, dvh, gpt, loop, mac, msdos, pc98, sun ] default: msdos part_type: description: - - Is one of 'primary', 'extended' or 'logical' and may be specified only - with 'msdos' or 'dvh' partition tables. A name must be specified for a - 'gpt' partition table. Neither part-type nor name may be used with a - 'sun' partition table. - choices: ['primary', 'extended', 'logical'] + - May be specified only with 'msdos' or 'dvh' partition tables. + - A C(name) must be specified for a 'gpt' partition table. + - Neither C(part_type) nor C(name) may be used with a 'sun' partition table. + type: str + choices: [ extended, logical, primary ] default: primary part_start: description: - - Where the partition will start as offset from the beginning of the disk, - that is, the "distance" from the start of the disk. The distance can be - specified with all the units supported by parted (except compat) and - it is case sensitive. E.g. C(10GiB), C(15%). + - Where the partition will start as offset from the beginning of the disk, + that is, the "distance" from the start of the disk. + - The distance can be specified with all the units supported by parted + (except compat) and it is case sensitive, e.g. C(10GiB), C(15%). + type: str default: 0% part_end : description: - - Where the partition will end as offset from the beginning of the disk, - that is, the "distance" from the start of the disk. The distance can be - specified with all the units supported by parted (except compat) and - it is case sensitive. E.g. C(10GiB), C(15%). + - Where the partition will end as offset from the beginning of the disk, + that is, the "distance" from the start of the disk. + - The distance can be specified with all the units supported by parted + (except compat) and it is case sensitive, e.g. C(10GiB), C(15%). + type: str default: 100% name: description: - - Sets the name for the partition number (GPT, Mac, MIPS and PC98 only). + - Sets the name for the partition number (GPT, Mac, MIPS and PC98 only). + type: str flags: description: A list of the flags that has to be set on the partition. + type: list state: description: - - If to create or delete a partition. If set to C(info) the module will - only return the device information. - choices: ['present', 'absent', 'info'] + - Whether to create or delete a partition. + - If set to C(info) the module will only return the device information. + type: str + choices: [ absent, present, info ] default: info +notes: + - When fetching information about a new disk and when the version of parted + installed on the system is before version 3.1, the module queries the kernel + through C(/sys/) to obtain disk information. In this case the units CHS and + CYL are not supported. ''' -RETURN = ''' +RETURN = r''' partition_info: description: Current partition information returned: success @@ -142,46 +146,47 @@ partition_info: } ''' -EXAMPLES = """ -# Create a new primary partition -- parted: +EXAMPLES = r''' +- name: Create a new primary partition + parted: device: /dev/sdb number: 1 state: present -# Remove partition number 1 -- parted: +- name: Remove partition number 1 + parted: device: /dev/sdb number: 1 state: absent -# Create a new primary partition with a size of 1GiB -- parted: +- name: Create a new primary partition with a size of 1GiB + parted: device: /dev/sdb number: 1 state: present part_end: 1GiB -# Create a new primary partition for LVM -- parted: +- name: Create a new primary partition for LVM + parted: device: /dev/sdb number: 2 flags: [ lvm ] state: present part_start: 1GiB -# Read device information (always use unit when probing) -- parted: device=/dev/sdb unit=MiB +# Example on how to read info and reuse it in subsequent task +- name: Read device information (always use unit when probing) + parted: device=/dev/sdb unit=MiB register: sdb_info -# Remove all partitions from disk -- parted: +- name: Remove all partitions from disk + parted: device: /dev/sdb - number: "{{ item.num }}" + number: '{{ item.num }}' state: absent with_items: - - "{{ sdb_info.partitions }}" -""" + - '{{ sdb_info.partitions }}' +''' from ansible.module_utils.basic import AnsibleModule @@ -192,7 +197,7 @@ import os # Reference prefixes (International System of Units and IEC) units_si = ['B', 'KB', 'MB', 'GB', 'TB'] -units_iec = ['B', 'KiB', 'MiB', 'GiB', 'TiB'] +units_iec = ['KiB', 'MiB', 'GiB', 'TiB'] parted_units = units_si + units_iec + ['s', '%', 'cyl', 'chs', 'compact'] @@ -531,54 +536,31 @@ def main(): output_script = "" script = "" module = AnsibleModule( - argument_spec={ - 'device': {'required': True, 'type': 'str'}, - 'align': { - 'default': 'optimal', - 'choices': ['none', 'cylinder', 'minimal', 'optimal'], - 'type': 'str' - }, - 'number': {'default': None, 'type': 'int'}, + argument_spec=dict( + device=dict(type='str', required=True), + align=dict(type='str', default='optimal', choices=['cylinder', 'minimal', 'none', 'optimal']), + number=dict(type='int'), # unit command - 'unit': { - 'default': 'KiB', - 'choices': parted_units, - 'type': 'str' - }, + unit=dict(type='str', default='KiB', choices=parted_units), # mklabel command - 'label': { - 'default': 'msdos', - 'choices': [ - 'aix', 'amiga', 'bsd', 'dvh', 'gpt', 'loop', 'mac', 'msdos', - 'pc98', 'sun' - ], - 'type': 'str' - }, + label=dict(type='str', default='msdos', choices=['aix', 'amiga', 'bsd', 'dvh', 'gpt', 'loop', 'mac', 'msdos', 'pc98', 'sun']), # mkpart [] command - 'part_type': { - 'default': 'primary', - 'choices': ['primary', 'extended', 'logical'], - 'type': 'str' - }, - 'part_start': {'default': '0%', 'type': 'str'}, - 'part_end': {'default': '100%', 'type': 'str'}, + part_type=dict(type='str', default='primary', choices=['extended', 'logical', 'primary']), + part_start=dict(type='str', default='0%'), + part_end=dict(type='str', default='100%'), # name command - 'name': {'type': 'str'}, + name=dict(type='str'), # set command - 'flags': {'type': 'list'}, + flags=dict(type='list'), # rm/mkpart command - 'state': { - 'choices': ['present', 'absent', 'info'], - 'default': 'info', - 'type': 'str' - } - }, + state=dict(type='str', default='info', choices=['absent', 'info', 'present']), + ), required_if=[ ['state', 'present', ['number']], ['state', 'absent', ['number']], diff --git a/lib/ansible/modules/system/ping.py b/lib/ansible/modules/system/ping.py index 715be21433..4cf384b35f 100644 --- a/lib/ansible/modules/system/ping.py +++ b/lib/ansible/modules/system/ping.py @@ -25,14 +25,12 @@ description: - This is NOT ICMP ping, this is just a trivial test module that requires Python on the remote-node. - For Windows targets, use the M(win_ping) module instead. - For Network targets, use the M(net_ping) module instead. -notes: - - For Windows targets, use the M(win_ping) module instead. - - For Network targets, use the M(net_ping) module instead. options: data: description: - Data to return for the C(ping) return value. - If this parameter is set to C(crash), the module will cause an exception. + type: str default: pong seealso: - module: net_ping diff --git a/lib/ansible/modules/system/reboot.py b/lib/ansible/modules/system/reboot.py index ff4d4086f0..9e45ed4003 100644 --- a/lib/ansible/modules/system/reboot.py +++ b/lib/ansible/modules/system/reboot.py @@ -14,7 +14,8 @@ DOCUMENTATION = r''' module: reboot short_description: Reboot a machine description: - - Reboot a machine, wait for it to go down, come back up, and respond to commands. + - Reboot a machine, wait for it to go down, come back up, and respond to commands. + - For Windows targets, use the M(win_reboot) module instead. version_added: "2.7" options: pre_reboot_delay: @@ -22,21 +23,21 @@ options: - Seconds for shutdown to wait before requesting reboot. - On Linux, macOS and OpenBSD, this is converted to minutes and rounded down. If less than 60, it will be set to 0. - On Solaris and FreeBSD, this will be seconds. - default: 0 type: int + default: 0 post_reboot_delay: description: - Seconds to wait after the reboot was successful and the connection was re-established. - This is useful if you want wait for something to settle despite your connection already working. - default: 0 type: int + default: 0 reboot_timeout: description: - Maximum seconds to wait for machine to reboot and respond to a test command. - This timeout is evaluated separately for both network connection and test command success so the maximum execution time for the module is twice this amount. - default: 600 type: int + default: 600 connect_timeout: description: - Maximum seconds to wait for a successful connection to the managed hosts before trying again. @@ -46,15 +47,13 @@ options: description: - Command to run on the rebooted host and expect success from to determine the machine is ready for further tasks. - default: whoami type: str + default: whoami msg: description: - Message to display to users before reboot. - default: Reboot initiated by Ansible type: str -notes: - - For Windows targets, use the M(win_reboot) module instead. + default: Reboot initiated by Ansible seealso: - module: win_reboot author: diff --git a/lib/ansible/modules/system/service.py b/lib/ansible/modules/system/service.py index 9d2f292563..7529b6c83c 100644 --- a/lib/ansible/modules/system/service.py +++ b/lib/ansible/modules/system/service.py @@ -11,7 +11,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['stableinterface'], 'supported_by': 'core'} -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- module: service version_added: "0.1" @@ -24,52 +24,60 @@ options: name: description: - Name of the service. + type: str required: true state: description: - C(started)/C(stopped) are idempotent actions that will not run - commands unless necessary. C(restarted) will always bounce the - service. C(reloaded) will always reload. B(At least one of state - and enabled are required.) Note that reloaded will start the - service if it is not already started, even if your chosen init - system wouldn't normally. + commands unless necessary. + - C(restarted) will always bounce the service. + - C(reloaded) will always reload. + - B(At least one of state and enabled are required.) + - Note that reloaded will start the service if it is not already started, + even if your chosen init system wouldn't normally. + type: str choices: [ reloaded, restarted, started, stopped ] sleep: description: - If the service is being C(restarted) then sleep this many seconds - between the stop and start command. This helps to workaround badly - behaving init scripts that exit immediately after signaling a process - to stop. + between the stop and start command. + - This helps to work around badly-behaving init scripts that exit immediately + after signaling a process to stop. + type: int version_added: "1.3" pattern: description: - If the service does not respond to the status command, name a substring to look for as would be found in the output of the I(ps) - command as a stand-in for a status result. If the string is found, - the service will be assumed to be started. + command as a stand-in for a status result. + - If the string is found, the service will be assumed to be started. + type: str version_added: "0.7" enabled: description: - - Whether the service should start on boot. B(At least one of state and - enabled are required.) + - Whether the service should start on boot. + - B(At least one of state and enabled are required.) type: bool runlevel: description: - - "For OpenRC init scripts (ex: Gentoo) only. The runlevel that this service belongs to." + - For OpenRC init scripts (e.g. Gentoo) only. + - The runlevel that this service belongs to. + type: str default: default arguments: description: - - Additional arguments provided on the command line + - Additional arguments provided on the command line. + type: str aliases: [ args ] use: description: - The service module actually uses system specific modules, normally through auto detection, this setting can force a specific module. - Normally it uses the value of the 'ansible_service_mgr' fact and falls back to the old 'service' module when none matching is found. + type: str default: auto version_added: 2.2 notes: - - For AIX group subsystem names can be used. - - For Windows targets, use the M(win_service) module instead. + - For AIX, group subsystem names can be used. seealso: - module: win_service author: @@ -77,7 +85,7 @@ author: - Michael DeHaan ''' -EXAMPLES = ''' +EXAMPLES = r''' - name: Start service httpd, if not started service: name: httpd diff --git a/lib/ansible/modules/system/svc.py b/lib/ansible/modules/system/svc.py index 89c99039ee..813916b654 100644 --- a/lib/ansible/modules/system/svc.py +++ b/lib/ansible/modules/system/svc.py @@ -24,6 +24,7 @@ options: name: description: - Name of the service to manage. + type: str required: true state: description: @@ -33,13 +34,14 @@ options: C(reloaded) will send a sigusr1 (svc -1). C(once) will run a normally downed svc once (svc -o), not really an idempotent operation. + type: str choices: [ killed, once, reloaded, restarted, started, stopped ] downed: description: - Should a 'down' file exist or not, if it exists it disables auto startup. Defaults to no. Downed does not imply stopped. type: bool - default: 'no' + default: no enabled: description: - Whether the service is enabled or not, if disabled it also implies stopped. @@ -48,10 +50,13 @@ options: service_dir: description: - Directory svscan watches for services + type: path default: /service service_src: description: - Directory where services are defined, the source of symlinks to service_dir. + type: path + default: /etc/service ''' EXAMPLES = ''' @@ -247,7 +252,6 @@ def main(): state=dict(type='str', choices=['killed', 'once', 'reloaded', 'restarted', 'started', 'stopped']), enabled=dict(type='bool'), downed=dict(type='bool'), - dist=dict(type='str', default='daemontools'), service_dir=dict(type='str', default='/service'), service_src=dict(type='str', default='/etc/service'), ), diff --git a/lib/ansible/modules/system/timezone.py b/lib/ansible/modules/system/timezone.py index 79babdb0e8..b42d82f36a 100644 --- a/lib/ansible/modules/system/timezone.py +++ b/lib/ansible/modules/system/timezone.py @@ -11,7 +11,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['preview'], 'supported_by': 'community'} -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- module: timezone short_description: Configure timezone setting @@ -21,26 +21,28 @@ description: - Several different tools are used depending on the OS/Distribution involved. For Linux it can use C(timedatectl) or edit C(/etc/sysconfig/clock) or C(/etc/timezone) and C(hwclock). On SmartOS, C(sm-set-timezone), for macOS, C(systemsetup), for BSD, C(/etc/localtime) is modified. - - As of version 2.3 support was added for SmartOS and BSDs. - - As of version 2.4 support was added for macOS. + - As of Ansible 2.3 support was added for SmartOS and BSDs. + - As of Ansible 2.4 support was added for macOS. - Windows, AIX and HPUX are not supported, please let us know if you find any other OS/distro in which this fails. version_added: "2.2" options: name: description: - Name of the timezone for the system clock. - Default is to keep current setting. B(At least one of name and - hwclock are required.) + - Default is to keep current setting. + - B(At least one of name and hwclock are required.) + type: str hwclock: description: - Whether the hardware clock is in UTC or in local timezone. - Default is to keep current setting. - Note that this option is recommended not to change and may fail + - Default is to keep current setting. + - Note that this option is recommended not to change and may fail to configure, especially on virtual environments such as AWS. - B(At least one of name and hwclock are required.) - I(Only used on Linux.) + - B(At least one of name and hwclock are required.) + - I(Only used on Linux.) + type: str aliases: [ rtc ] - choices: [ "UTC", "local" ] + choices: [ local, UTC ] notes: - On SmartOS the C(sm-set-timezone) utility (part of the smtools package) is required to set the zone timezone author: @@ -49,7 +51,7 @@ author: - Indrajit Raychaudhuri (@indrajitr) ''' -RETURN = ''' +RETURN = r''' diff: description: The differences about the given arguments. returned: success @@ -63,8 +65,8 @@ diff: type: dict ''' -EXAMPLES = ''' -- name: set timezone to Asia/Tokyo +EXAMPLES = r''' +- name: Set timezone to Asia/Tokyo timezone: name: Asia/Tokyo ''' diff --git a/lib/ansible/modules/system/user.py b/lib/ansible/modules/system/user.py index 1cb990c67b..129fdcce30 100644 --- a/lib/ansible/modules/system/user.py +++ b/lib/ansible/modules/system/user.py @@ -13,15 +13,235 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', DOCUMENTATION = ''' module: user -author: -- Stephen Fromm (@sfromm) version_added: "0.2" short_description: Manage user accounts +description: + - Manage user accounts and user attributes. + - For Windows targets, use the M(win_user) module instead. +options: + name: + description: + - Name of the user to create, remove or modify. + type: str + required: true + aliases: [ user ] + uid: + description: + - Optionally sets the I(UID) of the user. + type: int + comment: + description: + - Optionally sets the description (aka I(GECOS)) of user account. + type: str + hidden: + description: + - macOS only, optionally hide the user from the login window and system preferences. + - The default will be C(yes) if the I(system) option is used. + type: bool + required: false + version_added: "2.6" + non_unique: + description: + - Optionally when used with the -u option, this option allows to change the user ID to a non-unique value. + type: bool + default: no + version_added: "1.1" + seuser: + description: + - Optionally sets the seuser type (user_u) on selinux enabled systems. + type: str + version_added: "2.1" + group: + description: + - Optionally sets the user's primary group (takes a group name). + type: str + groups: + description: + - List of groups user will be added to. When set to an empty string C(''), + C(null), or C(~), the user is removed from all groups except the + primary group. (C(~) means C(null) in YAML) + - Before Ansible 2.3, the only input format allowed was a comma separated string. + type: list + append: + description: + - If C(yes), add the user to the groups specified in C(groups). + - If C(no), user will only be added to the groups specified in C(groups), + removing them from all other groups. + type: bool + default: no + shell: + description: + - Optionally set the user's shell. + - On macOS, before Ansible 2.5, the default shell for non-system users was C(/usr/bin/false). + Since Ansible 2.5, the default shell for non-system users on macOS is C(/bin/bash). + - On other operating systems, the default shell is determined by the underlying tool being + used. See Notes for details. + type: str + home: + description: + - Optionally set the user's home directory. + type: path + skeleton: + description: + - Optionally set a home skeleton directory. + - Requires C(create_home) option! + type: str + version_added: "2.0" + password: + description: + - Optionally set the user's password to this crypted value. + - On macOS systems, this value has to be cleartext. Beware of security issues. + - To create a disabled account on Linux systems, set this to C('!') or C('*'). + - See U(https://docs.ansible.com/ansible/faq.html#how-do-i-generate-crypted-passwords-for-the-user-module) + for details on various ways to generate these password values. + type: str + state: + description: + - Whether the account should exist or not, taking action if the state is different from what is stated. + type: str + choices: [ absent, present ] + default: present + create_home: + description: + - Unless set to C(no), a home directory will be made for the user + when the account is created or if the home directory does not exist. + - Changed from C(createhome) to C(create_home) in Ansible 2.5. + type: bool + default: yes + aliases: [ createhome ] + move_home: + description: + - "If set to C(yes) when used with C(home: ), attempt to move the user's old home + directory to the specified directory if it isn't there already and the old home exists." + type: bool + default: no + system: + description: + - When creating an account C(state=present), setting this to C(yes) makes the user a system account. + - This setting cannot be changed on existing users. + type: bool + default: no + force: + description: + - This only affects C(state=absent), it forces removal of the user and associated directories on supported platforms. + - The behavior is the same as C(userdel --force), check the man page for C(userdel) on your system for details and support. + - When used with C(generate_ssh_key=yes) this forces an existing key to be overwritten. + type: bool + default: no + remove: + description: + - This only affects C(state=absent), it attempts to remove directories associated with the user. + - The behavior is the same as C(userdel --remove), check the man page for details and support. + type: bool + default: no + login_class: + description: + - Optionally sets the user's login class, a feature of most BSD OSs. + type: str + generate_ssh_key: + description: + - Whether to generate a SSH key for the user in question. + - This will B(not) overwrite an existing SSH key unless used with C(force=yes). + type: bool + default: no + version_added: "0.9" + ssh_key_bits: + description: + - Optionally specify number of bits in SSH key to create. + type: int + default: default set by ssh-keygen + version_added: "0.9" + ssh_key_type: + description: + - Optionally specify the type of SSH key to generate. + - Available SSH key types will depend on implementation + present on target host. + type: str + default: rsa + version_added: "0.9" + ssh_key_file: + description: + - Optionally specify the SSH key filename. + - If this is a relative filename then it will be relative to the user's home directory. + type: path + default: .ssh/id_rsa + version_added: "0.9" + ssh_key_comment: + description: + - Optionally define the comment for the SSH key. + type: str + default: ansible-generated on $HOSTNAME + version_added: "0.9" + ssh_key_passphrase: + description: + - Set a passphrase for the SSH key. + - If no passphrase is provided, the SSH key will default to having no passphrase. + type: str + version_added: "0.9" + update_password: + description: + - C(always) will update passwords if they differ. + - C(on_create) will only set the password for newly created users. + type: str + choices: [ always, on_create ] + default: always + version_added: "1.3" + expires: + description: + - An expiry time for the user in epoch, it will be ignored on platforms that do not support this. + - Currently supported on GNU/Linux, FreeBSD, and DragonFlyBSD. + - Since Ansible 2.6 you can remove the expiry time specify a negative value. + Currently supported on GNU/Linux and FreeBSD. + type: float + version_added: "1.9" + password_lock: + description: + - Lock the password (usermod -L, pw lock, usermod -C). + - BUT implementation differs on different platforms, this option does not always mean the user cannot login via other methods. + - This option does not disable the user, only lock the password. Do not change the password in the same task. + - Currently supported on Linux, FreeBSD, DragonFlyBSD, NetBSD, OpenBSD. + type: bool + version_added: "2.6" + local: + description: + - Forces the use of "local" command alternatives on platforms that implement it. + - This is useful in environments that use centralized authentification when you want to manipulate the local users + (i.e. it uses C(luseradd) instead of C(useradd)). + - This requires that these commands exist on the targeted host, otherwise it will be a fatal error. + type: bool + default: no + version_added: "2.4" + profile: + description: + - Sets the profile of the user. + - Does nothing when used with other platforms. + - Can set multiple profiles using comma separation. + - To delete all the profiles, use C(profile=''). + - Currently supported on Illumos/Solaris. + type: str + version_added: "2.8" + authorization: + description: + - Sets the authorization of the user. + - Does nothing when used with other platforms. + - Can set multiple authorizations using comma separation. + - To delete all authorizations, use C(authorization=''). + - Currently supported on Illumos/Solaris. + type: str + version_added: "2.8" + role: + description: + - Sets the role of the user. + - Does nothing when used with other platforms. + - Can set multiple roles using comma separation. + - To delete all roles, use C(role=''). + - Currently supported on Illumos/Solaris. + type: str + version_added: "2.8" notes: - There are specific requirements per platform on user management utilities. However they generally come pre-installed with the system and Ansible will require they are present at runtime. If they are not, a descriptive error message will be shown. - - For Windows targets, use the M(win_user) module instead. - On SunOS platforms, the shadow file is backed up automatically since this module edits it directly. On other platforms, the shadow file is backed up by the underlying tools used by this module. - On macOS, this module uses C(dscl) to create, modify, and delete accounts. C(dseditgroup) is used to @@ -31,206 +251,12 @@ notes: C(pw userdel) remove, C(pw lock) to lock, and C(pw unlock) to unlock accounts. - On all other platforms, this module uses C(useradd) to create, C(usermod) to modify, and C(userdel) to remove accounts. -description: - - Manage user accounts and user attributes. - - For Windows targets, use the M(win_user) module instead. -options: - name: - description: - - Name of the user to create, remove or modify. - required: true - aliases: [ user ] - uid: - description: - - Optionally sets the I(UID) of the user. - comment: - description: - - Optionally sets the description (aka I(GECOS)) of user account. - hidden: - required: false - type: bool - description: - - macOS only, optionally hide the user from the login window and system preferences. - - The default will be 'True' if the I(system) option is used. - version_added: "2.6" - non_unique: - description: - - Optionally when used with the -u option, this option allows to change the user ID to a non-unique value. - type: bool - default: "no" - version_added: "1.1" - seuser: - description: - - Optionally sets the seuser type (user_u) on selinux enabled systems. - version_added: "2.1" - group: - description: - - Optionally sets the user's primary group (takes a group name). - groups: - description: - - List of groups user will be added to. When set to an empty string C(''), - C(null), or C(~), the user is removed from all groups except the - primary group. (C(~) means C(null) in YAML) - - Before version 2.3, the only input format allowed was a comma separated string. - Now this parameter accepts a list as well as a comma separated string. - append: - description: - - If C(yes), add the user to the groups specified in C(groups). - - If C(no), user will only be added to the groups specified in C(groups), - removing them from all other groups. - type: bool - default: "no" - shell: - description: - - Optionally set the user's shell. - - On macOS, before version 2.5, the default shell for non-system users was /usr/bin/false. - Since 2.5, the default shell for non-system users on macOS is /bin/bash. - - On other operating systems, the default shell is determined by the underlying tool being - used. See Notes for details. - home: - description: - - Optionally set the user's home directory. - skeleton: - description: - - Optionally set a home skeleton directory. Requires create_home option! - version_added: "2.0" - password: - description: - - Optionally set the user's password to this crypted value. - - On macOS systems, this value has to be cleartext. Beware of security issues. - - To create a disabled account on Linux systems, set this to C('!') or C('*'). - - See U(https://docs.ansible.com/ansible/faq.html#how-do-i-generate-crypted-passwords-for-the-user-module) - for details on various ways to generate these password values. - state: - description: - - Whether the account should exist or not, taking action if the state is different from what is stated. - choices: [ absent, present ] - default: present - create_home: - description: - - Unless set to C(no), a home directory will be made for the user - when the account is created or if the home directory does not exist. - - Changed from C(createhome) to C(create_home) in version 2.5. - type: bool - default: 'yes' - aliases: ['createhome'] - move_home: - description: - - "If set to C(yes) when used with C(home: ), attempt to move the user's old home - directory to the specified directory if it isn't there already and the old home exists." - type: bool - default: "no" - system: - description: - - "When creating an account C(state: present), setting this to C(yes) makes the user a system account. - This setting cannot be changed on existing users." - type: bool - default: "no" - force: - description: - - "This only affects C(state: absent), it forces removal of the user and associated directories on supported platforms. - The behavior is the same as C(userdel --force), check the man page for C(userdel) on your system for details and support." - - "When used with C(generate_ssh_key: yes) this forces an existing key to be overwritten." - type: bool - default: "no" - remove: - description: - - "This only affects C(state: absent), it attempts to remove directories associated with the user. - The behavior is the same as C(userdel --remove), check the man page for details and support." - type: bool - default: "no" - login_class: - description: - - Optionally sets the user's login class, a feature of most BSD OSs. - generate_ssh_key: - description: - - "Whether to generate a SSH key for the user in question. - This will not overwrite an existing SSH key unless used with C(force: yes)." - type: bool - default: "no" - version_added: "0.9" - ssh_key_bits: - description: - - Optionally specify number of bits in SSH key to create. - default: default set by ssh-keygen - version_added: "0.9" - ssh_key_type: - description: - - Optionally specify the type of SSH key to generate. - Available SSH key types will depend on implementation - present on target host. - default: rsa - version_added: "0.9" - ssh_key_file: - description: - - Optionally specify the SSH key filename. If this is a relative - filename then it will be relative to the user's home directory. - default: .ssh/id_rsa - version_added: "0.9" - ssh_key_comment: - description: - - Optionally define the comment for the SSH key. - default: ansible-generated on $HOSTNAME - version_added: "0.9" - ssh_key_passphrase: - description: - - Set a passphrase for the SSH key. If no - passphrase is provided, the SSH key will default to - having no passphrase. - version_added: "0.9" - update_password: - description: - - C(always) will update passwords if they differ. C(on_create) will only set the password for newly created users. - choices: [ always, on_create ] - default: always - version_added: "1.3" - expires: - description: - - An expiry time for the user in epoch, it will be ignored on platforms that do not support this. - Currently supported on GNU/Linux, FreeBSD, and DragonFlyBSD. - - Since version 2.6 you can remove the expiry time specify a negative value. Currently supported on GNU/Linux and FreeBSD. - version_added: "1.9" - password_lock: - description: - - Lock the password (usermod -L, pw lock, usermod -C). - BUT implementation differs on different platforms, this option does not always mean the user cannot login via other methods. - This option does not disable the user, only lock the password. Do not change the password in the same task. - Currently supported on Linux, FreeBSD, DragonFlyBSD, NetBSD, OpenBSD. - type: bool - version_added: "2.6" - local: - description: - - Forces the use of "local" command alternatives on platforms that implement it. - This is useful in environments that use centralized authentification when you want to manipulate the local users. - I.E. it uses `luseradd` instead of `useradd`. - - This requires that these commands exist on the targeted host, otherwise it will be a fatal error. - type: bool - default: 'no' - version_added: "2.4" - profile: - description: - - Sets the profile of the user. - - Does nothing when used with other platforms. - - Can set multiple profiles using comma separation. - - "To delete all the profiles, use C(profile: '')" - - Currently supported on Illumos/Solaris. - version_added: "2.8" - authorization: - description: - - Sets the authorization of the user. - - Does nothing when used with other platforms. - - Can set multiple authorizations using comma separation. - - "To delete all authorizations, use C(authorization: '')" - - Currently supported on Illumos/Solaris. - version_added: "2.8" - role: - description: - - Sets the role of the user. - - Does nothing when used with other platforms. - - Can set multiple roles using comma separation. - - "To delete all roles, use C(role: '')" - - Currently supported on Illumos/Solaris. - version_added: "2.8" +seealso: +- module: authorized_key +- module: group +- module: win_user +author: +- Stephen Fromm (@sfromm) ''' EXAMPLES = ''' @@ -268,7 +294,7 @@ EXAMPLES = ''' groups: developers expires: 1422403387 -- name: starting at version 2.6, modify user, remove expiry time +- name: Starting at Ansible 2.6, modify user, remove expiry time user: name: james18 expires: -1 diff --git a/lib/ansible/modules/system/vdo.py b/lib/ansible/modules/system/vdo.py index 900c4d73b6..488a4c6357 100644 --- a/lib/ansible/modules/system/vdo.py +++ b/lib/ansible/modules/system/vdo.py @@ -16,10 +16,10 @@ ANSIBLE_METADATA = { 'supported_by': 'community' } -DOCUMENTATION = ''' +DOCUMENTATION = r''' --- author: - - "Bryan Gurney (@bgurney-rh)" + - Bryan Gurney (@bgurney-rh) module: vdo @@ -29,7 +29,7 @@ version_added: "2.5" description: - This module controls the VDO dedupe and compression device. - VDO, or Virtual Data Optimizer, is a device-mapper target that + - VDO, or Virtual Data Optimizer, is a device-mapper target that provides inline block-level deduplication, compression, and thin provisioning capabilities to primary storage. @@ -37,9 +37,9 @@ options: name: description: - The name of the VDO volume. + type: str required: true state: - choices: [ "present", "absent" ] description: - Whether this VDO volume should be "present" or "absent". If a "present" VDO volume does not exist, it will be @@ -51,9 +51,11 @@ options: parameters that can be modified after creation. If an "absent" VDO volume does not exist, it will not be removed. + type: str required: true + choices: [ absent, present ] + default: present activated: - choices: [ "yes", "no" ] description: - The "activate" status for a VDO volume. If this is set to "no", the VDO volume cannot be started, and it will @@ -65,19 +67,17 @@ options: (filesystem, LVM headers, etc.) to the VDO volume prior to stopping the volume, and leaving it deactivated until ready to use. - - required: false + type: bool running: - choices: [ "yes", "no" ] description: - - Whether this VDO volume is running. A VDO volume must - be activated in order to be started. - required: false + - Whether this VDO volume is running. + - A VDO volume must be activated in order to be started. + type: bool device: description: - The full path of the device to use for VDO storage. - This is required if "state" is "present". - required: false + - This is required if "state" is "present". + type: str logicalsize: description: - The logical size of the VDO volume (in megabytes, or @@ -89,24 +89,24 @@ options: than or identical to the current size. If the specified size is larger than the current size, a growlogical operation will be performed. - required: false + type: str deduplication: - choices: [ "enabled", "disabled" ] description: - Configures whether deduplication is enabled. The default for a created volume is 'enabled'. Existing volumes will maintain their previously configured setting unless a different value is specified in the playbook. - required: false + type: str + choices: [ disabled, enabled ] compression: - choices: [ "enabled", "disabled" ] description: - Configures whether compression is enabled. The default for a created volume is 'enabled'. Existing volumes will maintain their previously configured setting unless a different value is specified in the playbook. - required: false + type: str + choices: [ disabled, enabled ] blockmapcachesize: description: - The amount of memory allocated for caching block map @@ -120,9 +120,8 @@ options: volumes will maintain their previously configured setting unless a different value is specified in the playbook. - required: false + type: str readcache: - choices: [ "enabled", "disabled" ] description: - Enables or disables the read cache. The default is 'disabled'. Choosing 'enabled' enables a read cache @@ -132,7 +131,8 @@ options: volumes will maintain their previously configured setting unless a different value is specified in the playbook. - required: false + type: str + choices: [ disabled, enabled ] readcachesize: description: - Specifies the extra VDO device read cache size in @@ -146,9 +146,8 @@ options: Existing volumes will maintain their previously configured setting unless a different value is specified in the playbook. - required: false + type: str emulate512: - type: bool description: - Enables 512-byte emulation mode, allowing drivers or filesystems to access the VDO volume at 512-byte @@ -158,16 +157,15 @@ options: a device. This option is only available when creating a new volume, and cannot be changed for an existing volume. - required: false - growphysical: type: bool + growphysical: description: - Specifies whether to attempt to execute a growphysical operation, if there is enough unused space on the device. A growphysical operation will be executed if there is at least 64 GB of free space, relative to the previous physical size of the affected VDO volume. - required: false + type: bool default: false slabsize: description: @@ -179,9 +177,8 @@ options: The maximum, 32G, supports a physical size of up to 256T. This option is only available when creating a new volume, and cannot be changed for an existing volume. - required: false + type: str writepolicy: - choices: [ "auto", "sync", "async" ] description: - Specifies the write policy of the VDO volume. The 'sync' mode acknowledges writes only after data is on @@ -195,7 +192,8 @@ options: Existing volumes will maintain their previously configured setting unless a different value is specified in the playbook. - required: false + type: str + choices: [ async, auto, sync ] indexmem: description: - Specifies the amount of index memory in gigabytes. The @@ -203,7 +201,7 @@ options: and 0.75 can be used, as can any positive integer. This option is only available when creating a new volume, and cannot be changed for an existing volume. - required: false + type: str indexmode: description: - Specifies the index mode of the Albireo index. The @@ -215,7 +213,7 @@ options: 100 GB of index data on persistent storage. This option is only available when creating a new volume, and cannot be changed for an existing volume. - required: false + type: str ackthreads: description: - Specifies the number of threads to use for @@ -225,7 +223,7 @@ options: 1. Existing volumes will maintain their previously configured setting unless a different value is specified in the playbook. - required: false + type: str biothreads: description: - Specifies the number of threads to use for submitting I/O @@ -235,7 +233,7 @@ options: Existing volumes will maintain their previously configured setting unless a different value is specified in the playbook. - required: false + type: str cputhreads: description: - Specifies the number of threads to use for CPU-intensive @@ -245,7 +243,7 @@ options: Existing volumes will maintain their previously configured setting unless a different value is specified in the playbook. - required: false + type: str logicalthreads: description: - Specifies the number of threads across which to @@ -255,7 +253,7 @@ options: The default is 1. Existing volumes will maintain their previously configured setting unless a different value is specified in the playbook. - required: false + type: str physicalthreads: description: - Specifies the number of threads across which to @@ -267,7 +265,7 @@ options: is 1. Existing volumes will maintain their previously configured setting unless a different value is specified in the playbook. - required: false + type: str notes: - In general, the default thread configuration should be used. requirements: @@ -276,8 +274,7 @@ requirements: - vdo ''' -EXAMPLES = ''' -# Create a VDO volume +EXAMPLES = r''' - name: Create 2 TB VDO volume vdo1 on device /dev/md0 vdo: name: vdo1 @@ -285,14 +282,13 @@ EXAMPLES = ''' device: /dev/md0 logicalsize: 2T -# Remove a VDO volume - name: Remove VDO volume vdo1 vdo: name: vdo1 state: absent ''' -RETURN = '''# ''' +RETURN = r'''# ''' from ansible.module_utils.basic import AnsibleModule import re @@ -453,35 +449,35 @@ def run_module(): # Creation param defaults are determined by the creation section. module_args = dict( - name=dict(required=True), - state=dict(choices=['absent', 'present'], default='present'), - activated=dict(choices=['yes', 'no']), - running=dict(choices=['yes', 'no']), + name=dict(type='str', required=True), + state=dict(type='str', default='present', choices=['absent', 'present']), + activated=dict(type='bool'), + running=dict(type='bool'), growphysical=dict(type='bool', default=False), - device=dict(), - logicalsize=dict(), - deduplication=dict(choices=['enabled', 'disabled']), - compression=dict(choices=['enabled', 'disabled']), + device=dict(type='str'), + logicalsize=dict(type='str'), + deduplication=dict(type='str', choices=['disabled', 'enabled']), + compression=dict(type='str', choices=['disabled', 'enabled']), blockmapcachesize=dict(type='str'), - readcache=dict(choices=['enabled', 'disabled']), - readcachesize=dict(), + readcache=dict(type='str', choices=['disabled', 'enabled']), + readcachesize=dict(type='str'), emulate512=dict(type='bool', default=False), - slabsize=dict(), - writepolicy=dict(choices=['auto', 'sync', 'async']), - indexmem=dict(), - indexmode=dict(choices=['dense', 'sparse']), - ackthreads=dict(), - biothreads=dict(), - cputhreads=dict(), - logicalthreads=dict(), - physicalthreads=dict() + slabsize=dict(type='str'), + writepolicy=dict(type='str', choices=['async', 'auto', 'sync']), + indexmem=dict(type='str'), + indexmode=dict(type='str', choices=['dense', 'sparse']), + ackthreads=dict(type='str'), + biothreads=dict(type='str'), + cputhreads=dict(type='str'), + logicalthreads=dict(type='str'), + physicalthreads=dict(type='str') ) # Seed the result dictionary in the object. There will be an # 'invocation' dictionary added with 'module_args' (arguments # given). result = dict( - changed=False + changed=False, ) # the AnsibleModule object will be our abstraction working with Ansible @@ -490,7 +486,7 @@ def run_module(): # supports check mode module = AnsibleModule( argument_spec=module_args, - supports_check_mode=False + supports_check_mode=False, ) if not HAS_YAML: diff --git a/test/sanity/validate-modules/ignore.txt b/test/sanity/validate-modules/ignore.txt index a01081f18a..b47157dc34 100644 --- a/test/sanity/validate-modules/ignore.txt +++ b/test/sanity/validate-modules/ignore.txt @@ -403,7 +403,6 @@ lib/ansible/modules/database/vertica/vertica_role.py E322 lib/ansible/modules/database/vertica/vertica_schema.py E322 lib/ansible/modules/database/vertica/vertica_user.py E322 lib/ansible/modules/files/assemble.py E323 -lib/ansible/modules/files/assemble.py E324 lib/ansible/modules/files/blockinfile.py E324 lib/ansible/modules/files/blockinfile.py E326 lib/ansible/modules/files/copy.py E322 @@ -872,10 +871,6 @@ lib/ansible/modules/storage/zfs/zfs_facts.py E323 lib/ansible/modules/storage/zfs/zpool_facts.py E323 lib/ansible/modules/system/aix_inittab.py E324 lib/ansible/modules/system/aix_inittab.py E326 -lib/ansible/modules/system/authorized_key.py E322 -lib/ansible/modules/system/authorized_key.py E324 -lib/ansible/modules/system/authorized_key.py E325 -lib/ansible/modules/system/beadm.py E324 lib/ansible/modules/system/capabilities.py E322 lib/ansible/modules/system/cron.py E324 lib/ansible/modules/system/cronvar.py E324 @@ -892,7 +887,6 @@ lib/ansible/modules/system/osx_defaults.py E322 lib/ansible/modules/system/osx_defaults.py E324 lib/ansible/modules/system/pamd.py E324 lib/ansible/modules/system/pamd.py E326 -lib/ansible/modules/system/parted.py E326 lib/ansible/modules/system/puppet.py E322 lib/ansible/modules/system/puppet.py E325 lib/ansible/modules/system/runit.py E322 @@ -905,14 +899,11 @@ lib/ansible/modules/system/service.py E323 lib/ansible/modules/system/service.py E210 lib/ansible/modules/system/systemd.py E324 lib/ansible/modules/system/solaris_zone.py E324 -lib/ansible/modules/system/svc.py E322 -lib/ansible/modules/system/svc.py E324 lib/ansible/modules/system/ufw.py E322 lib/ansible/modules/system/ufw.py E326 lib/ansible/modules/system/user.py E210 lib/ansible/modules/system/user.py E324 lib/ansible/modules/system/user.py E327 -lib/ansible/modules/system/vdo.py E324 lib/ansible/modules/system/vdo.py E326 lib/ansible/modules/web_infrastructure/ansible_tower/tower_credential.py E326 lib/ansible/modules/web_infrastructure/ansible_tower/tower_group.py E324