ansible/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00
Code Releases Activity

Fix parameter types and other fixes (#50111)

Browse source 
* 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 <dag@wieers.com>

* Update lib/ansible/modules/system/service.py

Co-Authored-By: dagwieers <dag@wieers.com>

* Update lib/ansible/modules/system/service.py

Co-Authored-By: dagwieers <dag@wieers.com>

* Revert type change, move to separate PR

* Update lib/ansible/modules/files/replace.py

Co-Authored-By: dagwieers <dag@wieers.com>

* Update lib/ansible/modules/files/replace.py

Co-Authored-By: dagwieers <dag@wieers.com>

* Update lib/ansible/modules/files/replace.py

Co-Authored-By: dagwieers <dag@wieers.com>

* Update lib/ansible/modules/files/replace.py

Co-Authored-By: dagwieers <dag@wieers.com>

* Update lib/ansible/modules/files/replace.py

Co-Authored-By: dagwieers <dag@wieers.com>

* Update lib/ansible/modules/files/replace.py

Co-Authored-By: dagwieers <dag@wieers.com>
This commit is contained in:
Dag Wieers 2019-01-18 03:24:47 +01:00 committed by GitHub
parent b834b29e43
commit 30227ace98
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
43 changed files with 1222 additions and 1065 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

34
lib/ansible/modules/files/acl.py
View file

@ -22,8 +22,9 @@ options:
path: path:
description: description:
- The full path of the file or object. - The full path of the file or object.
aliases: [ name ] type: path
required: yes required: yes
aliases: [ name ]
state: state:
description: description:
- Define whether the ACL should be present or not. - Define whether the ACL should be present or not.
@ -72,7 +73,7 @@ options:
version_added: '2.0' version_added: '2.0'
use_nfsv4_acls: use_nfsv4_acls:
description: description:
- Use NFSv4 ACLs instead of POSIX ACLs. - Use NFSv4 ACLs instead of POSIX ACLs.
type: bool type: bool
default: no default: no
version_added: '2.2' version_added: '2.2'
@ -259,31 +260,28 @@ def run_acl(module, cmd, check_rc=True):
def main(): def main():
module = AnsibleModule( module = AnsibleModule(
argument_spec=dict( argument_spec=dict(
path=dict(required=True, aliases=['name'], type='path'), path=dict(type='path', required=True, aliases=['name']),
entry=dict(required=False, type='str'), entry=dict(type='str'),
entity=dict(required=False, type='str', default=''), entity=dict(type='str', default=''),
etype=dict( etype=dict(
required=False, type='str',
choices=['other', 'user', 'group', 'mask'], choices=['group', 'mask', 'other', 'user'],
type='str'
), ),
permissions=dict(required=False, type='str'), permissions=dict(type='str'),
state=dict( state=dict(
required=False, type='str',
default='query', default='query',
choices=['query', 'present', 'absent'], choices=['absent', 'present', 'query'],
type='str'
), ),
follow=dict(required=False, type='bool', default=True), follow=dict(type='bool', default=True),
default=dict(required=False, type='bool', default=False), default=dict(type='bool', default=False),
recursive=dict(required=False, type='bool', default=False), recursive=dict(type='bool', default=False),
recalculate_mask=dict( recalculate_mask=dict(
required=False, type='str',
default='default', default='default',
choices=['default', 'mask', 'no_mask'], 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, supports_check_mode=True,
) )

40
lib/ansible/modules/files/archive.py
View file

@ -13,49 +13,57 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'], 'status': ['preview'],
'supported_by': 'community'} 'supported_by': 'community'}
DOCUMENTATION = ''' DOCUMENTATION = r'''
--- ---
module: archive module: archive
version_added: '2.3' version_added: '2.3'
short_description: Creates a compressed archive of one or more files or trees short_description: Creates a compressed archive of one or more files or trees
extends_documentation_fragment: files extends_documentation_fragment: files
description: 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 - Packs an archive.
source file from the local system to the target before archiving. Source files can be deleted after archival by specifying I(remove=True). - 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: options:
path: path:
description: description:
- Remote absolute path, glob, or list of paths or globs for the file or files to compress or archive. - Remote absolute path, glob, or list of paths or globs for the file or files to compress or archive.
type: list
required: true required: true
format: format:
description: description:
- The type of compression to use. - 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 ] choices: [ bz2, gz, tar, xz, zip ]
default: gz default: gz
dest: dest:
description: 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 - The file name of the destination archive.
multiple paths in a list. - 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: exclude_path:
version_added: '2.4'
description: 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: remove:
description: description:
- Remove any added source files and trees after adding to archive. - Remove any added source files and trees after adding to archive.
type: bool 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: author:
- Ben Doherty (@bendoh) - 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 - name: Compress directory /path/to/foo/ into /path/to/foo.tgz
archive: archive:
path: /path/to/foo path: /path/to/foo
@ -99,7 +107,7 @@ EXAMPLES = '''
format: bz2 format: bz2
''' '''
RETURN = ''' RETURN = r'''
state: state:
description: description:
The current state of the archived file. The current state of the archived file.

29
lib/ansible/modules/files/assemble.py
View file

@ -29,16 +29,17 @@ description:
- This module is also supported for Windows targets. - This module is also supported for Windows targets.
notes: notes:
- This module is also supported for Windows targets. - This module is also supported for Windows targets.
- See also M(copy) and M(template).
version_added: '0.5' version_added: '0.5'
options: options:
src: src:
description: description:
- An already existing directory full of source files. - An already existing directory full of source files.
type: path
required: true required: true
dest: dest:
description: description:
- A file to create using the concatenation of all of the source files. - A file to create using the concatenation of all of the source files.
type: path
required: true required: true
backup: backup:
description: description:
@ -50,13 +51,14 @@ options:
delimiter: delimiter:
description: description:
- A delimiter to separate the file contents. - A delimiter to separate the file contents.
type: str
version_added: '1.4' version_added: '1.4'
remote_src: remote_src:
description: description:
- If C(no), it will search for src at originating/master machine. - 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. - If C(yes), it will go to the remote/target machine for the src.
type: bool type: bool
default: yes default: no
version_added: '1.4' version_added: '1.4'
regexp: regexp:
description: description:
@ -64,6 +66,7 @@ options:
- If not set, all files are assembled. - If not set, all files are assembled.
- Every "\" (backslash) must be escaped as "\\" to comply to YAML syntax. - Every "\" (backslash) must be escaped as "\\" to comply to YAML syntax.
- Uses L(Python regular expressions,http://docs.python.org/2/library/re.html). - Uses L(Python regular expressions,http://docs.python.org/2/library/re.html).
type: str
ignore_hidden: ignore_hidden:
description: description:
- A boolean that controls if files that start with a '.' will be included or not. - 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 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 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. - The command is passed securely so shell features like expansion and pipes won't work.
type: str
version_added: '2.0' version_added: '2.0'
seealso: seealso:
- module: copy - module: copy
- module: template
- module: win_copy - module: win_copy
author: author:
- Stephen Fromm (@sfromm) - Stephen Fromm (@sfromm)
extends_documentation_fragment: extends_documentation_fragment:
- files
- decrypt - decrypt
- files
''' '''
EXAMPLES = r''' EXAMPLES = r'''
@ -102,7 +107,7 @@ EXAMPLES = r'''
assemble: assemble:
src: /etc/ssh/conf.d/ src: /etc/ssh/conf.d/
dest: /etc/ssh/sshd_config dest: /etc/ssh/sshd_config
validate: '/usr/sbin/sshd -t -f %s' validate: /usr/sbin/sshd -t -f %s
''' '''
import codecs import codecs
@ -173,14 +178,14 @@ def main():
module = AnsibleModule( module = AnsibleModule(
# not checking because of daisy chain to file module # not checking because of daisy chain to file module
argument_spec=dict( argument_spec=dict(
src=dict(required=True, type='path'), src=dict(type='path', required=True),
delimiter=dict(required=False), delimiter=dict(type='str'),
dest=dict(required=True, type='path'), dest=dict(type='path', required=True),
backup=dict(default=False, type='bool'), backup=dict(type='bool', default=False),
remote_src=dict(default=False, type='bool'), remote_src=dict(type='bool', default=False),
regexp=dict(required=False), regexp=dict(type='str'),
ignore_hidden=dict(default=False, type='bool'), ignore_hidden=dict(type='bool', default=False),
validate=dict(required=False, type='str'), validate=dict(type='str'),
), ),
add_file_common_args=True, add_file_common_args=True,
) )

9
lib/ansible/modules/files/blockinfile.py
View file

@ -18,8 +18,7 @@ module: blockinfile
short_description: Insert/update/remove a text block surrounded by marker lines short_description: Insert/update/remove a text block surrounded by marker lines
version_added: '2.0' version_added: '2.0'
description: description:
- This module will insert/update/remove a block of multi-line text - This module will insert/update/remove a block of multi-line text surrounded by customizable marker lines.
surrounded by customizable marker lines.
author: author:
- Yaegashi Takeshi (@yaegashi) - Yaegashi Takeshi (@yaegashi)
options: options:
@ -27,8 +26,8 @@ options:
description: description:
- The file to modify. - The file to modify.
- Before Ansible 2.3 this option was only usable as I(dest), I(destfile) and I(name). - Before Ansible 2.3 this option was only usable as I(dest), I(destfile) and I(name).
required: yes
type: path type: path
required: yes
aliases: [ dest, destfile, name ] aliases: [ dest, destfile, name ]
state: state:
description: description:
@ -48,16 +47,16 @@ options:
- The text to insert inside the marker lines. - 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). - If it is missing or an empty string, the block will be removed as if C(state) were specified to C(absent).
type: str type: str
aliases: [ content ]
default: '' default: ''
aliases: [ content ]
insertafter: insertafter:
description: description:
- If specified, the block will be inserted after the last match of specified regular expression. - 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. - 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. - If specified regular expression has no matches, C(EOF) will be used instead.
type: str type: str
default: EOF
choices: [ EOF, '*regex*' ] choices: [ EOF, '*regex*' ]
default: EOF
insertbefore: insertbefore:
description: description:
- If specified, the block will be inserted before the last match of specified regular expression. - If specified, the block will be inserted before the last match of specified regular expression.

33
lib/ansible/modules/files/copy.py
View file

@ -19,8 +19,6 @@ version_added: historical
short_description: Copy files to remote locations short_description: Copy files to remote locations
description: description:
- The C(copy) module copies a file from the local or remote machine to a location on the remote machine. - 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. - For Windows targets, use the M(win_copy) module instead.
options: options:
src: src:
@ -31,10 +29,12 @@ options:
with "/", only inside contents of that directory are copied to destination. with "/", only inside contents of that directory are copied to destination.
Otherwise, if it does not end with "/", the directory itself with all contents 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. is copied. This behavior is similar to the C(rsync) command line tool.
type: path
content: content:
description: description:
- When used instead of I(src), sets the contents of a file directly to the specified value. - 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. - For anything advanced or with formatting also look at the template module.
type: str
version_added: '1.1' version_added: '1.1'
dest: dest:
description: description:
@ -42,6 +42,7 @@ options:
- If I(src) is a directory, this must be a directory too. - 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(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. - 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 required: yes
backup: backup:
description: 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 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). - 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. - C(preserve) means that the file will be given the same permissions as the source file.
type: path
directory_mode: directory_mode:
description: description:
- When doing a recursive copy set the mode for the directories. - When doing a recursive copy set the mode for the directories.
- If this is not set we will use the system defaults. - 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. - 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' version_added: '1.5'
remote_src: remote_src:
description: description:
- Influence whether I(src) needs to be transferred or already is present remotely. - 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(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). - 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) supports recursive copying as of Ansible 2.8.
- I(remote_src) only works with C(mode=preserve) as of version 2.6. - I(remote_src) only works with C(mode=preserve) as of Ansible 2.6.
type: bool type: bool
default: no default: no
version_added: '2.0' version_added: '2.0'
@ -102,6 +105,7 @@ options:
- SHA1 checksum of the file being transferred. - SHA1 checksum of the file being transferred.
- Used to validate that the copy of the file was successful. - 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. - If this is not provided, ansible will use the local calculated checksum of the src file.
type: str
version_added: '2.5' version_added: '2.5'
extends_documentation_fragment: extends_documentation_fragment:
- decrypt - decrypt
@ -109,12 +113,11 @@ extends_documentation_fragment:
- validate - validate
notes: notes:
- The M(copy) module recursively copy facility does not scale to lots (>hundreds) of files. - 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: seealso:
- module: assemble - module: assemble
- module: fetch - module: fetch
- module: file - module: file
- module: synchronize
- module: template - module: template
- module: win_copy - module: win_copy
author: author:
@ -129,7 +132,7 @@ EXAMPLES = r'''
dest: /etc/foo.conf dest: /etc/foo.conf
owner: foo owner: foo
group: foo group: foo
mode: 0644 mode: '0644'
- name: Copy file with owner and permission, using symbolic representation - name: Copy file with owner and permission, using symbolic representation
copy: copy:
@ -153,7 +156,7 @@ EXAMPLES = r'''
dest: /etc/ntp.conf dest: /etc/ntp.conf
owner: root owner: root
group: root group: root
mode: 0644 mode: '0644'
backup: yes backup: yes
- name: Copy a new "sudoers" file into place, after passing validation with visudo - 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' content: '# This file was moved to /etc/other.conf'
dest: /etc/mine.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: copy:
src: /etc/foo.conf src: /etc/foo.conf
dest: /path/to/link # /path/to/link is link to /path/to/file dest: /path/to/link # link to /path/to/file
follow: True 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: copy:
src: /etc/foo.conf src: /etc/foo.conf
dest: /path/to/link # /path/to/link is link to /path/to/file dest: /path/to/link # link to /path/to/file
follow: False follow: no
''' '''
RETURN = r''' RETURN = r'''
@ -473,7 +476,7 @@ def main():
directory_mode=dict(type='raw'), directory_mode=dict(type='raw'),
remote_src=dict(type='bool'), remote_src=dict(type='bool'),
local_follow=dict(type='bool'), local_follow=dict(type='bool'),
checksum=dict(), checksum=dict(type='str'),
), ),
add_file_common_args=True, add_file_common_args=True,
supports_check_mode=True, supports_check_mode=True,

9
lib/ansible/modules/files/fetch.py
View file

@ -57,9 +57,6 @@ options:
- Obviously this is only handy if the filenames are unique. - Obviously this is only handy if the filenames are unique.
type: bool type: bool
default: no default: no
author:
- Ansible Core Team
- Michael DeHaan
notes: notes:
- When running fetch with C(become), the M(slurp) module will also be - 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 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 also explicitly set C(fail_on_missing) to C(no) to get the
non-failing behaviour. non-failing behaviour.
- This module is also supported for Windows targets. - This module is also supported for Windows targets.
seealso:
- module: copy
- module: slurp
author:
- Ansible Core Team
- Michael DeHaan
''' '''
EXAMPLES = r''' EXAMPLES = r'''

45
lib/ansible/modules/files/file.py
View file

@ -27,6 +27,7 @@ options:
path: path:
description: description:
- Path to the file being managed. - Path to the file being managed.
type: path
required: yes required: yes
aliases: [ dest, name ] aliases: [ dest, name ]
state: 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 - 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 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). modification times (similar to the way C(touch) works from the command line).
type: str
default: file default: file
choices: [ absent, directory, file, hard, link, touch ] choices: [ absent, directory, file, hard, link, touch ]
src: src:
@ -52,6 +54,7 @@ options:
- Will accept absolute, relative and non-existing paths. - Will accept absolute, relative and non-existing paths.
- Relative paths are relative to the file being created (C(path)) which is how - 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. the Unix command C(ln -s SRC DEST) treats relative paths.
type: path
recurse: recurse:
description: description:
- Recursively set the specified file attributes on directory contents. - 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. - 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). - 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). - 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" version_added: "2.7"
modification_time_format: modification_time_format:
description: description:
- When used with C(modification_time), indicates the time format that must be used. - When used with C(modification_time), indicates the time format that must be used.
- Based on default Python format (see time.strftime doc). - Based on default Python format (see time.strftime doc).
type: str
default: "%Y%m%d%H%M.%S" default: "%Y%m%d%H%M.%S"
version_added: '2.7' version_added: '2.7'
access_time: access_time:
@ -91,15 +96,15 @@ options:
- This parameter indicates the time the file's access time should be set to. - 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). - 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). - 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' version_added: '2.7'
access_time_format: access_time_format:
description: description:
- When used with C(access_time), indicates the time format that must be used. - When used with C(access_time), indicates the time format that must be used.
- Based on default Python format (see time.strftime doc). - Based on default Python format (see time.strftime doc).
type: str
default: "%Y%m%d%H%M.%S" default: "%Y%m%d%H%M.%S"
version_added: '2.7' version_added: '2.7'
notes:
- For Windows targets, use the M(win_file) module instead.
seealso: seealso:
- module: assemble - module: assemble
- module: copy - module: copy
@ -111,21 +116,19 @@ author:
- Michael DeHaan - Michael DeHaan
''' '''
EXAMPLES = ''' EXAMPLES = r'''
- name: Change file ownership, group and permissions - name: Change file ownership, group and permissions
file: file:
path: /etc/foo.conf path: /etc/foo.conf
owner: foo owner: foo
group: foo group: foo
# When specifying mode using octal numbers, add a leading 0 mode: '0644'
mode: 0644
- name: Create an insecure file - name: Create an insecure file
file: file:
path: /work path: /work
owner: root owner: root
group: root group: root
# Or use quotes instead
mode: '1777' mode: '1777'
- name: Create a symbolic link - name: Create a symbolic link
@ -169,7 +172,7 @@ EXAMPLES = '''
file: file:
path: /etc/some_directory path: /etc/some_directory
state: directory state: directory
mode: 0755 mode: '0755'
- name: Update modification and access time of given file - name: Update modification and access time of given file
file: file:
@ -178,7 +181,7 @@ EXAMPLES = '''
modification_time: now modification_time: now
access_time: now access_time: now
''' '''
RETURN = ''' RETURN = r'''
''' '''
@ -817,21 +820,21 @@ def main():
module = AnsibleModule( module = AnsibleModule(
argument_spec=dict( argument_spec=dict(
state=dict(choices=['file', 'directory', 'link', 'hard', 'touch', 'absent'], default=None), state=dict(type='str', choices=['absent', 'directory', 'file', 'hard', 'link', 'touch']),
path=dict(aliases=['dest', 'name'], required=True, type='path'), path=dict(type='path', required=True, aliases=['dest', 'name']),
_original_basename=dict(required=False), # Internal use only, for recursive ops _original_basename=dict(type='str'), # Internal use only, for recursive ops
recurse=dict(default=False, type='bool'), recurse=dict(type='bool', default=False),
force=dict(required=False, default=False, type='bool'), # Note: Should not be in file_common_args in future force=dict(type='bool', default=False), # 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 follow=dict(type='bool', default=True), # Note: Different default than file_common_args
_diff_peek=dict(default=None), # Internal use only, for internal checks in the action plugins _diff_peek=dict(type='str'), # 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 src=dict(type='path'), # Note: Should not be in file_common_args in future
modification_time=dict(required=False, default=None), modification_time=dict(type='str'),
modification_time_format=dict(required=False, default='%Y%m%d%H%M.%S'), modification_time_format=dict(type='str', default='%Y%m%d%H%M.%S'),
access_time=dict(required=False, default=None), access_time=dict(type='str'),
access_time_format=dict(required=False, default='%Y%m%d%H%M.%S'), access_time_format=dict(type='str', default='%Y%m%d%H%M.%S'),
), ),
add_file_common_args=True, 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 # When we rewrite basic.py, we will do something similar to this on instantiating an AnsibleModule

78
lib/ansible/modules/files/find.py
View file

@ -27,9 +27,10 @@ options:
age: age:
description: description:
- Select files whose age is equal to or greater than the specified time. - 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. - 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 - You can choose seconds, minutes, hours, days, or weeks by specifying the
first letter of any of those words (e.g., "1w"). first letter of any of those words (e.g., "1w").
type: str
patterns: patterns:
default: '*' default: '*'
description: description:
@ -40,75 +41,80 @@ options:
patterns contain a comma, make sure to put them in a list to avoid splitting the patterns patterns contain a comma, make sure to put them in a list to avoid splitting the patterns
in undesirable ways. in undesirable ways.
type: list type: list
aliases: ['pattern'] aliases: [ pattern ]
excludes: excludes:
description: description:
- One or more (shell or regex) patterns, which type is controlled by C(use_regex) option. - 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. - Items matching an C(excludes) pattern are culled from C(patterns) matches.
Multiple patterns can be specified using a list. Multiple patterns can be specified using a list.
type: list type: list
aliases: ['exclude'] aliases: [ exclude ]
version_added: "2.5" version_added: "2.5"
contains: contains:
description: description:
- One or more regex patterns which should be matched against the file content. - One or more regex patterns which should be matched against the file content.
type: str
paths: paths:
required: true
aliases: [ name, path ]
description: description:
- List of paths of directories to search. All paths must be fully qualified. - List of paths of directories to search. All paths must be fully qualified.
type: list type: list
required: true
aliases: [ name, path ]
file_type: file_type:
description: description:
- Type of file to select. - 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 ] choices: [ any, directory, file, link ]
default: file default: file
recurse: recurse:
description: description:
- If target is a directory, recursively descend into the directory looking for files. - If target is a directory, recursively descend into the directory looking for files.
type: bool type: bool
default: 'no' default: no
size: size:
description: description:
- Select files whose size is equal to or greater than the specified size. - 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. - 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 - Unqualified values are in bytes but b, k, m, g, and t can be appended to specify
bytes, kilobytes, megabytes, gigabytes, and terabytes, respectively. bytes, kilobytes, megabytes, gigabytes, and terabytes, respectively.
Size is not evaluated for directories. - Size is not evaluated for directories.
age_stamp: age_stamp:
default: mtime
choices: [ atime, ctime, mtime ]
description: description:
- Choose the file property against which we compare age. - Choose the file property against which we compare age.
type: str
choices: [ atime, ctime, mtime ]
default: mtime
hidden: hidden:
description: 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 type: bool
default: 'no' default: no
follow: follow:
description: 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 type: bool
default: 'no' default: no
get_checksum: get_checksum:
description: 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 type: bool
default: 'no' default: no
use_regex: use_regex:
description: 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 type: bool
default: 'no' default: no
depth: depth:
description: description:
- Set the maximum number of levels to decend into. Setting recurse - Set the maximum number of levels to decend into.
to false will override this value, which is effectively depth 1. - Setting recurse to C(no) will override this value, which is effectively depth 1.
Default is unlimited depth. - Default is unlimited depth.
type: int
version_added: "2.6" version_added: "2.6"
notes: seealso:
- For Windows targets, use the M(win_find) module instead. - module: win_find
''' '''
@ -175,7 +181,7 @@ EXAMPLES = r'''
RETURN = r''' RETURN = r'''
files: 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 returned: success
type: list type: list
sample: [ sample: [
@ -189,12 +195,12 @@ files:
}, },
] ]
matched: matched:
description: number of matches description: Number of matches
returned: success returned: success
type: str type: str
sample: 14 sample: 14
examined: examined:
description: number of filesystem objects looked at description: Number of filesystem objects looked at
returned: success returned: success
type: str type: str
sample: 34 sample: 34
@ -355,14 +361,14 @@ def main():
contains=dict(type='str'), contains=dict(type='str'),
file_type=dict(type='str', default="file", choices=['any', 'directory', 'file', 'link']), file_type=dict(type='str', default="file", choices=['any', 'directory', 'file', 'link']),
age=dict(type='str'), 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'), size=dict(type='str'),
recurse=dict(type='bool', default='no'), recurse=dict(type='bool', default=False),
hidden=dict(type='bool', default='no'), hidden=dict(type='bool', default=False),
follow=dict(type='bool', default='no'), follow=dict(type='bool', default=False),
get_checksum=dict(type='bool', default='no'), get_checksum=dict(type='bool', default=False),
use_regex=dict(type='bool', default='no'), use_regex=dict(type='bool', default=False),
depth=dict(type='int', default=None), depth=dict(type='int'),
), ),
supports_check_mode=True, supports_check_mode=True,
) )

90
lib/ansible/modules/files/ini_file.py
View file

@ -8,99 +8,103 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
#
ANSIBLE_METADATA = {'metadata_version': '1.1', ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'], 'status': ['preview'],
'supported_by': 'community'} 'supported_by': 'community'}
DOCUMENTATION = ''' DOCUMENTATION = r'''
--- ---
module: ini_file module: ini_file
short_description: Tweak settings in INI files short_description: Tweak settings in INI files
extends_documentation_fragment: files extends_documentation_fragment: files
description: description:
- Manage (add, remove, change) individual settings in an INI-style file without having - 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 to manage the file as a whole with, say, M(template) or M(assemble).
sections if they don't exist. - 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. - Before Ansible 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 - 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. no other modifications need to be applied.
version_added: "0.9" version_added: "0.9"
options: options:
path: path:
description: description:
- Path to the INI-style file; this file is created if required. - Path to the INI-style file; this file is created if required.
- Before 2.3 this option was only usable as I(dest). - Before Ansible 2.3 this option was only usable as I(dest).
aliases: [ dest ] type: path
required: true required: true
aliases: [ dest ]
section: section:
description: description:
- Section name in INI file. This is added if C(state=present) automatically when - Section name in INI file. This is added if C(state=present) automatically when
a single value is being set. a single value is being set.
- If left empty or set to `null`, the I(option) will be placed before the first I(section). - If left empty or set to C(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. - Using C(null) is also required if the config format does not support sections.
type: str
required: true required: true
option: option:
description: description:
- If set (required for changing a I(value)), this is the name of the option. - 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). - May be omitted if adding/removing a whole I(section).
type: str
value: value:
description: 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: backup:
description: description:
- Create a backup file including the timestamp information so you can get - Create a backup file including the timestamp information so you can get
the original file back if you somehow clobbered it incorrectly. the original file back if you somehow clobbered it incorrectly.
type: bool type: bool
default: 'no' default: no
others: others:
description: description:
- All arguments accepted by the M(file) module also work here - All arguments accepted by the M(file) module also work here.
type: str
state: state:
description: description:
- If set to C(absent) the option or section will be removed if present instead of created. - If set to C(absent) the option or section will be removed if present instead of created.
choices: [ absent, present ] type: str
default: present choices: [ absent, present ]
default: present
no_extra_spaces: no_extra_spaces:
description: description:
- Do not insert spaces before and after '=' symbol - Do not insert spaces before and after '=' symbol.
type: bool type: bool
default: 'no' default: no
version_added: "2.1" version_added: "2.1"
create: create:
description: description:
- If set to 'no', the module will fail if the file does not already exist. - 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. - By default it will create the file if it is missing.
type: bool type: bool
default: 'yes' default: yes
version_added: "2.2" version_added: "2.2"
allow_no_value: allow_no_value:
description: description:
- allow option without value and without '=' symbol - Allow option without value and without '=' symbol.
type: bool type: bool
required: false default: no
default: false version_added: "2.6"
version_added: "2.6"
notes: notes:
- While it is possible to add an I(option) without specifying a I(value), this makes - While it is possible to add an I(option) without specifying a I(value), this makes no sense.
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.
- 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: author:
- Jan-Piet Mens (@jpmens) - Jan-Piet Mens (@jpmens)
- Ales Nosek (@noseka1) - Ales Nosek (@noseka1)
''' '''
EXAMPLES = ''' EXAMPLES = r'''
# Before 2.3, option 'dest' was used instead of 'path' # Before Ansible 2.3, option 'dest' was used instead of 'path'
- name: Ensure "fav=lemonade is in section "[drinks]" in specified file - name: Ensure "fav=lemonade is in section "[drinks]" in specified file
ini_file: ini_file:
path: /etc/conf path: /etc/conf
section: drinks section: drinks
option: fav option: fav
value: lemonade value: lemonade
mode: 0600 mode: '0600'
backup: yes backup: yes
- name: Ensure "temperature=cold is in section "[drinks]" in specified file - name: Ensure "temperature=cold is in section "[drinks]" in specified file
@ -302,7 +306,7 @@ def main():
backup=dict(type='bool', default=False), backup=dict(type='bool', default=False),
state=dict(type='str', default='present', choices=['absent', 'present']), state=dict(type='str', default='present', choices=['absent', 'present']),
no_extra_spaces=dict(type='bool', default=False), 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) create=dict(type='bool', default=True)
), ),
add_file_common_args=True, add_file_common_args=True,

10
lib/ansible/modules/files/iso_extract.py
View file

@ -38,34 +38,38 @@ options:
image: image:
description: description:
- The ISO image to extract files from. - The ISO image to extract files from.
type: path
required: yes required: yes
aliases: [ path, src ] aliases: [ path, src ]
dest: dest:
description: description:
- The destination directory to extract files to. - The destination directory to extract files to.
type: path
required: yes required: yes
files: files:
description: description:
- A list of files to extract from the image. - A list of files to extract from the image.
- Extracting directories does not work. - Extracting directories does not work.
type: list
required: yes required: yes
force: force:
description: description:
- If C(yes), which will replace the remote file when contents are different than the source. - 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. - If C(no), the file will only be extracted and copied if the destination does not already exist.
type: bool type: bool
default: 'yes' default: yes
aliases: [ thirsty ] aliases: [ thirsty ]
version_added: '2.4' version_added: '2.4'
executable: executable:
description: description:
- The path to the C(7z) executable to use for extracting files from the ISO. - The path to the C(7z) executable to use for extracting files from the ISO.
type: path
default: '7z' default: '7z'
version_added: '2.4' version_added: '2.4'
notes: notes:
- Only the file checksum (content) is taken into account when extracting files - 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. 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, - 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 requiring root access. This is no longer needed with the introduction of 7zip
for extraction. for extraction.
''' '''

113
lib/ansible/modules/files/lineinfile.py
View file

@ -21,101 +21,107 @@ short_description: Manage lines in text files
description: description:
- This module ensures a particular line is in a file, or replace an - This module ensures a particular line is in a file, or replace an
existing line using a back-referenced regular expression. existing line using a back-referenced regular expression.
- This is primarily useful when you want to change a single line in - This is primarily useful when you want to change a single line in a file only.
a file only. See the M(replace) module if you want to change - See the M(replace) module if you want to change multiple, similar lines
multiple, similar lines or check M(blockinfile) if you want to insert/update/remove a block of lines in a file. 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. For other cases, see the M(copy) or M(template) modules.
version_added: "0.7" version_added: "0.7"
options: options:
path: path:
description: description:
- The file to modify. - The file to modify.
- Before 2.3 this option was only usable as I(dest), I(destfile) and I(name). - Before Ansible 2.3 this option was only usable as I(dest), I(destfile) and I(name).
aliases: [ dest, destfile, name ] type: path
required: true required: true
aliases: [ dest, destfile, name ]
regexp: regexp:
aliases: [ regex ]
description: description:
- The regular expression to look for in every line of the file. - 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=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. - For C(state=absent), the pattern of the line(s) to remove.
- If the regular expression is not matched, the line will be - 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. settings.
- When modifying a line the regexp should typically match both the initial state of - 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. 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). - Uses Python regular expressions. See U(http://docs.python.org/2/library/re.html).
type: str
aliases: [ regex ]
version_added: '1.7' version_added: '1.7'
state: state:
description: description:
- Whether the line should be there or not. - Whether the line should be there or not.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
line: line:
description: description:
- Required for C(state=present). The line to insert/replace into the - The line to insert/replace into the file.
file. If C(backrefs) is set, may contain backreferences that will get - 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. expanded with the C(regexp) capture groups if the regexp matches.
type: str
backrefs: backrefs:
description: description:
- Used with C(state=present). If set, C(line) can contain backreferences - Used with C(state=present).
(both positional and named) that will get populated if the C(regexp) - If set, C(line) can contain backreferences (both positional and named)
matches. This flag changes the operation of the module slightly; 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) 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. 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. the expanded line parameter.
type: bool type: bool
default: 'no' default: no
version_added: "1.1" version_added: "1.1"
insertafter: insertafter:
description: description:
- Used with C(state=present). If specified, the line will be inserted - Used with C(state=present).
after the last match of specified regular expression. - If specified, the line will be inserted after the last match of specified regular expression.
If the first match is required, use(firstmatch=yes). - If the first match is required, use(firstmatch=yes).
A special value is available; C(EOF) for inserting the line at the - A special value is available; C(EOF) for inserting the line at the end of the file.
end of the file. - If specified regular expression has no matches, EOF will be used instead.
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.
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).
May not be used with C(backrefs). type: str
choices: [ EOF, '*regex*' ] choices: [ EOF, '*regex*' ]
default: EOF default: EOF
insertbefore: insertbefore:
description: description:
- Used with C(state=present). If specified, the line will be inserted - Used with C(state=present).
before the last match of specified regular expression. - If specified, the line will be inserted before the last match of specified regular expression.
If the first match is required, use(firstmatch=yes). - If the first match is required, use C(firstmatch=yes).
A value is available; C(BOF) for inserting the line at - A value is available; C(BOF) for inserting the line at the beginning of the file.
the beginning of the file. - If specified regular expression has no matches, the line will be inserted at the end of the file.
If specified regular expression has no matches, the line will be - 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.
inserted at the end of the file. - May not be used with C(backrefs).
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. type: str
May not be used with C(backrefs).
choices: [ BOF, '*regex*' ] choices: [ BOF, '*regex*' ]
version_added: "1.1" version_added: "1.1"
create: create:
description: description:
- Used with C(state=present). If specified, the file will be created - Used with C(state=present).
if it does not already exist. By default it will fail if the file - If specified, the file will be created if it does not already exist.
is missing. - By default it will fail if the file is missing.
type: bool type: bool
default: 'no' default: no
backup: backup:
description: description:
- Create a backup file including the timestamp information so you can - Create a backup file including the timestamp information so you can
get the original file back if you somehow clobbered it incorrectly. get the original file back if you somehow clobbered it incorrectly.
type: bool type: bool
default: 'no' default: no
firstmatch: firstmatch:
description: description:
- Used with C(insertafter) or C(insertbefore). If set, C(insertafter) and C(inserbefore) find - Used with C(insertafter) or C(insertbefore).
a first line has regular expression matches. - If set, C(insertafter) and C(inserbefore) find a first line has regular expression matches.
type: bool type: bool
default: 'no' default: no
version_added: "2.5" version_added: "2.5"
others: others:
description: description:
- All arguments accepted by the M(file) module also work here. - All arguments accepted by the M(file) module also work here.
type: str
extends_documentation_fragment: extends_documentation_fragment:
- files - files
- validate - 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. - 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: seealso:
- module: blockinfile - module: blockinfile
- module: copy
- module: file - module: file
- module: replace
- module: template
- module: win_lineinfile - module: win_lineinfile
author: author:
- Daniel Hokka Zakrissoni (@dhozac) - Daniel Hokka Zakrissoni (@dhozac)
@ -135,7 +144,7 @@ EXAMPLES = r"""
- lineinfile: - lineinfile:
path: /etc/selinux/config path: /etc/selinux/config
regexp: '^SELINUX=' regexp: '^SELINUX='
line: 'SELINUX=enforcing' line: SELINUX=enforcing
- lineinfile: - lineinfile:
path: /etc/sudoers path: /etc/sudoers
@ -146,16 +155,16 @@ EXAMPLES = r"""
- lineinfile: - lineinfile:
path: /etc/hosts path: /etc/hosts
regexp: '^127\.0\.0\.1' regexp: '^127\.0\.0\.1'
line: '127.0.0.1 localhost' line: 127.0.0.1 localhost
owner: root owner: root
group: root group: root
mode: 0644 mode: '0644'
- lineinfile: - lineinfile:
path: /etc/httpd/conf/httpd.conf path: /etc/httpd/conf/httpd.conf
regexp: '^Listen ' regexp: '^Listen '
insertafter: '^#Listen ' insertafter: '^#Listen '
line: 'Listen 8080' line: Listen 8080
- lineinfile: - lineinfile:
path: /etc/services path: /etc/services
@ -166,7 +175,7 @@ EXAMPLES = r"""
# Add a line to a file if the file does not exist, without passing regexp # Add a line to a file if the file does not exist, without passing regexp
- lineinfile: - lineinfile:
path: /tmp/testfile path: /tmp/testfile
line: '192.168.1.99 foo.lab.net foo' line: 192.168.1.99 foo.lab.net foo
create: yes create: yes
# Fully quoted because of the ': ' on the line. See the Gotchas in the YAML docs. # Fully quoted because of the ': ' on the line. See the Gotchas in the YAML docs.
@ -189,7 +198,7 @@ EXAMPLES = r"""
state: present state: present
regexp: '^%ADMIN ALL=' regexp: '^%ADMIN ALL='
line: '%ADMIN ALL=(ALL) NOPASSWD: ALL' line: '%ADMIN ALL=(ALL) NOPASSWD: ALL'
validate: '/usr/sbin/visudo -cf %s' validate: /usr/sbin/visudo -cf %s
""" """
import os import os
@ -475,7 +484,7 @@ def main():
backrefs=dict(type='bool', default=False), backrefs=dict(type='bool', default=False),
create=dict(type='bool', default=False), create=dict(type='bool', default=False),
backup=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'), validate=dict(type='str'),
), ),
mutually_exclusive=[['insertbefore', 'insertafter']], mutually_exclusive=[['insertbefore', 'insertafter']],

25
lib/ansible/modules/files/patch.py
View file

@ -27,54 +27,59 @@ options:
basedir: basedir:
description: description:
- Path of a base directory in which the patch file will be applied. - 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: dest:
description: description:
- Path of the file on the remote machine to be patched. - 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 - 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 file, but if there's just one file to be patched it can specified with
this option. this option.
type: path
aliases: [ originalfile ] aliases: [ originalfile ]
src: src:
description: description:
- Path of the patch file as accepted by the GNU patch tool. If - 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 C(remote_src) is 'no', the patch source file is looked up from the
module's I(files) directory. module's I(files) directory.
type: path
required: true required: true
aliases: [ patchfile ] aliases: [ patchfile ]
state: state:
version_added: "2.6"
description: description:
- Whether the patch should be applied or reverted. - Whether the patch should be applied or reverted.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
version_added: "2.6"
remote_src: remote_src:
description: description:
- If C(no), it will search for src at originating/master machine, if C(yes) it will - 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). go to the remote/target machine for the C(src).
type: bool type: bool
default: 'no' default: no
strip: strip:
description: description:
- Number that indicates the smallest prefix containing leading slashes - Number that indicates the smallest prefix containing leading slashes
that will be stripped from each file name found in the patch file. 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 default: 0
backup: backup:
version_added: "2.0" version_added: "2.0"
description: description:
- Passes C(--backup --version-control=numbered) to patch, - Passes C(--backup --version-control=numbered) to patch, producing numbered backup copies.
producing numbered backup copies.
type: bool type: bool
default: 'no' default: no
binary: binary:
version_added: "2.0" version_added: "2.0"
description: description:
- Setting to C(yes) will disable patch's heuristic for transforming CRLF - 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 line endings into LF.
C(no), C(patch) will replace CRLF in C(src) files on POSIX. - 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 type: bool
default: 'no' default: no
notes: notes:
- This module requires GNU I(patch) utility to be installed on the remote host. - This module requires GNU I(patch) utility to be installed on the remote host.
''' '''

97
lib/ansible/modules/files/replace.py
View file

@ -13,15 +13,15 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'supported_by': 'community'} 'supported_by': 'community'}
DOCUMENTATION = """ DOCUMENTATION = r'''
--- ---
module: replace module: replace
author: "Evan Kaufman (@EvanK)" author: Evan Kaufman (@EvanK)
extends_documentation_fragment: extends_documentation_fragment:
- files - files
- validate - validate
short_description: Replace all instances of a particular string in a 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: description:
- This module will replace all instances of a pattern within a file. - 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 - It is up to the user to maintain idempotence by ensuring that the
@ -31,89 +31,96 @@ options:
path: path:
description: description:
- The file to modify. - The file to modify.
- Before 2.3 this option was only usable as I(dest), I(destfile) and I(name). - Before Ansible 2.3 this option was only usable as I(dest), I(destfile) and I(name).
aliases: [ dest, destfile, name ] type: path
required: true required: true
aliases: [ dest, destfile, name ]
regexp: regexp:
description: description:
- The regular expression to look for in the contents of the file. - 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). 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 and end of the file, as well as the beginning and end respectively
of I(each line) of the file. of I(each line) of the file.
- Does not use DOTALL, which means the C(.) special character matches - Does not use DOTALL, which means the C(.) special character matches
any character I(except newlines). A common mistake is to assume that any character I(except newlines). A common mistake is to assume that
a negated character set like C([^#]) will also not match newlines. 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]). - 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 - Note that, as of Ansible 2.0, short form tasks should have any escape
sequences backslash-escaped in order to prevent them being parsed sequences backslash-escaped in order to prevent them being parsed
as string literal escapes. See the examples. as string literal escapes. See the examples.
type: str
required: true required: true
replace: replace:
description: description:
- The string to replace regexp matches. May contain backreferences - The string to replace regexp matches.
that will get expanded with the regexp capture groups if the regexp - May contain backreferences that will get expanded with the regexp capture groups if the regexp matches.
matches. If not set, matches are removed entirely. - If not set, matches are removed entirely.
type: str
after: after:
description: description:
- If specified, the line after the replace/remove will start. Can be used - If specified, the line after the replace/remove will start.
in combination with C(before). - Can be used in combination with C(before).
Uses Python regular expressions; see - Uses Python regular expressions; see
U(http://docs.python.org/2/library/re.html). U(http://docs.python.org/2/library/re.html).
type: str
version_added: "2.4" version_added: "2.4"
before: before:
description: description:
- If specified, the line before the replace/remove will occur. Can be used - If specified, the line before the replace/remove will occur.
in combination with C(after). - Can be used in combination with C(after).
Uses Python regular expressions; see - Uses Python regular expressions; see
U(http://docs.python.org/2/library/re.html). U(http://docs.python.org/2/library/re.html).
type: str
version_added: "2.4" version_added: "2.4"
backup: backup:
description: description:
- Create a backup file including the timestamp information so you can - Create a backup file including the timestamp information so you can
get the original file back if you somehow clobbered it incorrectly. get the original file back if you somehow clobbered it incorrectly.
type: bool type: bool
default: 'no' default: no
others: others:
description: description:
- All arguments accepted by the M(file) module also work here. - All arguments accepted by the M(file) module also work here.
type: str
encoding: encoding:
description: description:
- "The character encoding for reading and writing the file." - The character encoding for reading and writing the file.
default: "utf-8" type: str
default: utf-8
version_added: "2.4" version_added: "2.4"
notes: 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. - 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""" EXAMPLES = r'''
# Before 2.3, option 'dest', 'destfile' or 'name' was used instead of 'path' # Before Ansible 2.3, option 'dest', 'destfile' or 'name' was used instead of 'path'
- replace: - replace:
path: /etc/hosts path: /etc/hosts
regexp: '(\s+)old\.host\.name(\s+.*)?$' regexp: '(\s+)old\.host\.name(\s+.*)?$'
replace: '\1new.host.name\2' replace: '\1new.host.name\2'
backup: yes backup: yes
# Replace after the expression till the end of the file (requires >=2.4) - name: Replace after the expression till the end of the file (requires Ansible >= 2.4)
- replace: replace:
path: /etc/hosts path: /etc/hosts
regexp: '(\s+)old\.host\.name(\s+.*)?$' regexp: '(\s+)old\.host\.name(\s+.*)?$'
replace: '\1new.host.name\2' replace: '\1new.host.name\2'
after: 'Start after line.*' after: Start after line.*
backup: yes backup: yes
# Replace before the expression till the begin of the file (requires >=2.4) - name: Replace before the expression till the begin of the file (requires Ansible >= 2.4)
- replace: replace:
path: /etc/hosts path: /etc/hosts
regexp: '(\s+)old\.host\.name(\s+.*)?$' regexp: '(\s+)old\.host\.name(\s+.*)?$'
replace: '\1new.host.name\2' replace: '\1new.host.name\2'
before: 'Start before line.*' before: 'Start before line.*'
backup: yes backup: yes
# Replace between the expressions (requires >=2.4) - name: Replace between the expressions (requires Ansible >= 2.4)
- replace: replace:
path: /etc/hosts path: /etc/hosts
regexp: '(\s+)old\.host\.name(\s+.*)?$' regexp: '(\s+)old\.host\.name(\s+.*)?$'
replace: '\1new.host.name\2' replace: '\1new.host.name\2'
@ -126,7 +133,7 @@ EXAMPLES = r"""
regexp: '^old\.host\.name[^\n]*\n' regexp: '^old\.host\.name[^\n]*\n'
owner: jdoe owner: jdoe
group: jdoe group: jdoe
mode: 0644 mode: '0644'
- replace: - replace:
path: /etc/apache/ports path: /etc/apache/ports
@ -134,15 +141,15 @@ EXAMPLES = r"""
replace: '\1 127.0.0.1:8080' replace: '\1 127.0.0.1:8080'
validate: '/usr/sbin/apache2ctl -f %s -t' 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' 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: replace:
dest: /etc/hosts dest: /etc/hosts
regexp: '\b(localhost)(\d*)\b' regexp: '\b(localhost)(\d*)\b'
replace: '\1\2.localdomain\2 \1\2' replace: '\1\2.localdomain\2 \1\2'
""" '''
import os import os
import re import re
@ -189,17 +196,17 @@ def check_file_attrs(module, changed, message):
def main(): def main():
module = AnsibleModule( module = AnsibleModule(
argument_spec=dict( argument_spec=dict(
path=dict(required=True, aliases=['dest', 'destfile', 'name'], type='path'), path=dict(type='path', required=True, aliases=['dest', 'destfile', 'name']),
regexp=dict(required=True), regexp=dict(type='str', required=True),
replace=dict(default='', type='str'), replace=dict(type='str', default=''),
after=dict(required=False), after=dict(type='str'),
before=dict(required=False), before=dict(type='str'),
backup=dict(default=False, type='bool'), backup=dict(type='bool', default=False),
validate=dict(default=None, type='str'), validate=dict(type='str'),
encoding=dict(default='utf-8', type='str'), encoding=dict(type='str', default='utf-8'),
), ),
add_file_common_args=True, add_file_common_args=True,
supports_check_mode=True supports_check_mode=True,
) )
params = module.params params = module.params

35
lib/ansible/modules/files/stat.py
View file

@ -1,4 +1,5 @@
#!/usr/bin/python #!/usr/bin/python
# Copyright: (c) 2017, Ansible Project # Copyright: (c) 2017, Ansible Project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) # 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" version_added: "1.3"
short_description: Retrieve file or file system status short_description: Retrieve file or file system status
description: 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. - For Windows targets, use the M(win_stat) module instead.
options: options:
path: path:
description: description:
- The full path of the file/object to get the facts of. - The full path of the file/object to get the facts of.
type: path
required: true required: true
follow: follow:
description: description:
- Whether to follow symlinks. - Whether to follow symlinks.
type: bool type: bool
default: 'no' default: no
get_md5: get_md5:
description: description:
- Whether to return the md5 sum of the file. - 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 - Use C(get_checksum=true) with C(checksum_algorithm=md5) to return an
md5 hash under the C(checksum) return value. md5 hash under the C(checksum) return value.
type: bool type: bool
default: 'no' default: no
get_checksum: get_checksum:
description: description:
- Whether to return a checksum of the file (default sha1). - Whether to return a checksum of the file.
type: bool type: bool
default: 'yes' default: yes
version_added: "1.8" version_added: "1.8"
checksum_algorithm: checksum_algorithm:
description: description:
- Algorithm to determine checksum of file. Will throw an error if the - Algorithm to determine checksum of file.
host is unable to use specified algorithm. - 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) - The remote host has to support the hashing method specified, C(md5)
can be unavailable if the host is FIPS-140 compliant. can be unavailable if the host is FIPS-140 compliant.
type: str
choices: [ md5, sha1, sha224, sha256, sha384, sha512 ] choices: [ md5, sha1, sha224, sha256, sha384, sha512 ]
default: sha1 default: sha1
aliases: [ checksum, checksum_algo ] aliases: [ checksum, checksum_algo ]
@ -59,27 +62,25 @@ options:
- Use file magic and return data about the nature of the file. this uses - Use file magic and return data about the nature of the file. this uses
the 'file' utility found on most Linux/Unix systems. the 'file' utility found on most Linux/Unix systems.
- This will add both `mime_type` and 'charset' fields to the return, if possible. - 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 type: bool
default: 'yes' default: yes
version_added: "2.1"
aliases: [ mime, mime_type, mime-type ] aliases: [ mime, mime_type, mime-type ]
version_added: "2.1"
get_attributes: get_attributes:
description: description:
- Get file attributes using lsattr tool if present. - Get file attributes using lsattr tool if present.
type: bool type: bool
default: 'yes' default: yes
version_added: "2.3"
aliases: [ attr, attributes ] aliases: [ attr, attributes ]
notes: version_added: "2.3"
- For Windows targets, use the M(win_stat) module instead.
seealso: seealso:
- module: file - module: file
- module: win_stat - module: win_stat
author: Bruce Pennypacker (@bpennypacker) author: Bruce Pennypacker (@bpennypacker)
''' '''
EXAMPLES = ''' EXAMPLES = r'''
# Obtain the stats of /etc/foo.conf, and check that the file still belongs # Obtain the stats of /etc/foo.conf, and check that the file still belongs
# to 'root'. Fail otherwise. # to 'root'. Fail otherwise.
- stat: - stat:
@ -142,7 +143,7 @@ stat:
type: complex type: complex
contains: contains:
exists: exists:
description: if the destination path actually exists or not description: If the destination path actually exists or not
returned: success returned: success
type: bool type: bool
sample: True sample: True
@ -445,7 +446,7 @@ def main():
follow=dict(type='bool', default=False), follow=dict(type='bool', default=False),
get_md5=dict(type='bool'), get_md5=dict(type='bool'),
get_checksum=dict(type='bool', default=True), 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']), get_attributes=dict(type='bool', default=True, aliases=['attr', 'attributes']),
checksum_algorithm=dict(type='str', default='sha1', checksum_algorithm=dict(type='str', default='sha1',
choices=['md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512'], choices=['md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512'],

110
lib/ansible/modules/files/synchronize.py
View file

@ -12,70 +12,82 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'], 'status': ['preview'],
'supported_by': 'core'} 'supported_by': 'core'}
DOCUMENTATION = ''' DOCUMENTATION = r'''
--- ---
module: synchronize module: synchronize
version_added: "1.4" 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: 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 - C(synchronize) is a wrapper around rsync to make common tasks in your playbooks quick and easy.
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 - It is run and originates on the local host where Ansible is being run.
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 - 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. invocations easier to implement. You `still` may need to call rsync directly via C(command) or C(shell) depending on your use case.
options: options:
src: src:
description: 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 required: true
dest: dest:
description: 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 required: true
dest_port: dest_port:
description: 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 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" version_added: "1.5"
mode: mode:
description: 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 - Specify the direction of the synchronization.
is the source. - 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 ] choices: [ pull, push ]
default: push default: push
archive: archive:
description: description:
- Mirrors the rsync archive flag, enables recursive, links, perms, times, owner, group flags and -D. - Mirrors the rsync archive flag, enables recursive, links, perms, times, owner, group flags and -D.
type: bool type: bool
default: 'yes' default: yes
checksum: checksum:
description: description:
- Skip based on checksum, rather than mod-time & size; Note that that "archive" option is still enabled by default - the "checksum" option will - 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. not disable it.
type: bool type: bool
default: 'no' default: no
version_added: "1.6" version_added: "1.6"
compress: compress:
description: 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 type: bool
default: 'yes' default: yes
version_added: "1.7" version_added: "1.7"
existing_only: existing_only:
description: description:
- Skip creating new files on receiver. - Skip creating new files on receiver.
type: bool type: bool
default: 'no' default: no
version_added: "1.5" version_added: "1.5"
delete: delete:
description: 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 type: bool
default: 'no' default: no
dirs: dirs:
description: description:
- Transfer directories without recursing - Transfer directories without recursing.
type: bool type: bool
default: 'no' default: no
recursive: recursive:
description: description:
- Recurse into directories. - Recurse into directories.
@ -90,7 +102,7 @@ options:
description: description:
- Copy symlinks as the item that they point to (the referent) is copied, rather than the symlink. - Copy symlinks as the item that they point to (the referent) is copied, rather than the symlink.
type: bool type: bool
default: 'no' default: no
perms: perms:
description: description:
- Preserve permissions. - Preserve permissions.
@ -98,66 +110,72 @@ options:
default: the value of the archive option default: the value of the archive option
times: times:
description: description:
- Preserve modification times - Preserve modification times.
type: bool type: bool
default: the value of the archive option default: the value of the archive option
owner: owner:
description: description:
- Preserve owner (super user only) - Preserve owner (super user only).
type: bool type: bool
default: the value of the archive option default: the value of the archive option
group: group:
description: description:
- Preserve group - Preserve group.
type: bool type: bool
default: the value of the archive option default: the value of the archive option
rsync_path: rsync_path:
description: description:
- Specify the rsync command to run on the remote host. See C(--rsync-path) on the rsync man page. - 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). - 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: rsync_timeout:
description: description:
- Specify a C(--timeout) for the rsync command in seconds. - Specify a C(--timeout) for the rsync command in seconds.
type: int
default: 0 default: 0
set_remote_user: set_remote_user:
description: description:
- put user@ for the remote paths. If you have a custom ssh config to define the remote user for a host - Put user@ for the remote paths.
that does not match the inventory user, you should set this parameter to "no". - 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 default: yes
use_ssh_args: use_ssh_args:
description: description:
- Use the ssh_args specified in ansible.cfg - Use the ssh_args specified in ansible.cfg.
type: bool type: bool
default: 'no' default: no
version_added: "2.0" version_added: "2.0"
rsync_opts: rsync_opts:
description: description:
- Specify additional rsync options by passing in an array. Note that an empty string in - Specify additional rsync options by passing in an array.
C(rsync_opts) will end up transfer the current working directory. - Note that an empty string in C(rsync_opts) will end up transfer the current working directory.
type: str
default: default:
version_added: "1.6" version_added: "1.6"
partial: partial:
description: description:
- Tells rsync to keep the partial file which should make a subsequent transfer of the rest of the file much faster. - Tells rsync to keep the partial file which should make a subsequent transfer of the rest of the file much faster.
type: bool type: bool
default: 'no' default: no
version_added: "2.0" version_added: "2.0"
verify_host: verify_host:
description: description:
- Verify destination host key. - Verify destination host key.
type: bool type: bool
default: 'no' default: no
version_added: "2.0" version_added: "2.0"
private_key: private_key:
description: 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" version_added: "1.6"
link_dest: link_dest:
description: description:
- add a destination to hard link against during the rsync. - Add a destination to hard link against during the rsync.
type: str
default: default:
version_added: "2.5" version_added: "2.5"
notes: notes:
- rsync must be installed on both the local and remote host. - 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 - 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 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). 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. - 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 - 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. 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 - 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 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. rsync does not provide us a way to pass a password to the connection.
- Expect that dest=~/x will be ~<remote_user>/x even if using sudo. - Expect that dest=~/x will be ~<remote_user>/x even if using sudo.
- Inspect the verbose output to validate the destination user/host/path - Inspect the verbose output to validate the destination user/host/path are what was expected.
are what was expected. - To exclude files and directories from being synchronized, you may add C(.rsync-filter) files to the source directory.
- To exclude files and directories from being synchronized, you may add - rsync daemon must be up and running with correct permission when using rsync protocol in source or destination path.
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 - 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. 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 - 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: synchronize:
src: some/relative/path src: some/relative/path
dest: /some/absolute/path dest: /some/absolute/path
rsync_path: "su -c rsync" rsync_path: su -c rsync
# Example .rsync-filter file in the source directory # Example .rsync-filter file in the source directory
# - var # exclude any path whose last part is 'var' # - 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 # Specify the rsync binary to use on remote host and on local host
- hosts: groupofhosts - hosts: groupofhosts
vars: vars:
ansible_rsync_path: "/usr/gnu/bin/rsync" ansible_rsync_path: /usr/gnu/bin/rsync
tasks: tasks:
- name: copy /tmp/localpath/ to remote location /tmp/remotepath - name: copy /tmp/localpath/ to remote location /tmp/remotepath
synchronize: synchronize:
src: "/tmp/localpath/" src: /tmp/localpath/
dest: "/tmp/remotepath" dest: /tmp/remotepath
rsync_path: "/usr/gnu/bin/rsync" rsync_path: /usr/gnu/bin/rsync
''' '''
@ -370,7 +384,7 @@ def main():
private_key=dict(type='path'), private_key=dict(type='path'),
rsync_path=dict(type='str'), rsync_path=dict(type='str'),
_local_rsync_path=dict(type='path', default='rsync'), _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), _substitute_controller=dict(type='bool', default=False),
archive=dict(type='bool', default=True), archive=dict(type='bool', default=True),
checksum=dict(type='bool', default=False), checksum=dict(type='bool', default=False),

12
lib/ansible/modules/files/tempfile.py
View file

@ -16,7 +16,7 @@ DOCUMENTATION = '''
--- ---
module: tempfile module: tempfile
version_added: "2.3" version_added: "2.3"
short_description: Creates temporary files and directories. short_description: Creates temporary files and directories
description: description:
- The C(tempfile) module creates temporary files and directories. C(mktemp) command takes different parameters on various systems, this module helps - 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 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: state:
description: description:
- Whether to create file or directory. - Whether to create file or directory.
type: str
choices: [ directory, file ] choices: [ directory, file ]
default: file default: file
path: path:
description: 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: prefix:
description: description:
- Prefix of file/directory name created by module. - Prefix of file/directory name created by module.
type: str
default: ansible. default: ansible.
suffix: suffix:
description: description:
- Suffix of file/directory name created by module. - Suffix of file/directory name created by module.
type: str
default: "" default: ""
notes:
- For Windows targets, use the M(win_tempfile) module instead.
seealso: seealso:
- module: file
- module: win_tempfile - module: win_tempfile
author: author:
- Krzysztof Magosa (@krzysztof-magosa) - Krzysztof Magosa (@krzysztof-magosa)

16
lib/ansible/modules/files/template.py
View file

@ -35,10 +35,12 @@ options:
description: description:
- Path of a Jinja2 formatted template on the Ansible controller. - Path of a Jinja2 formatted template on the Ansible controller.
- This can be a relative or an absolute path. - This can be a relative or an absolute path.
type: path
required: yes required: yes
dest: dest:
description: description:
- Location to render the template to on the remote machine. - Location to render the template to on the remote machine.
type: path
required: yes required: yes
backup: backup:
description: description:
@ -50,27 +52,32 @@ options:
newline_sequence: newline_sequence:
description: description:
- Specify the newline sequence to use for templating files. - Specify the newline sequence to use for templating files.
type: str
choices: [ '\n', '\r', '\r\n' ] choices: [ '\n', '\r', '\r\n' ]
default: '\n' default: '\n'
version_added: '2.4' version_added: '2.4'
block_start_string: block_start_string:
description: description:
- The string marking the beginning of a block. - The string marking the beginning of a block.
type: str
default: '{%' default: '{%'
version_added: '2.4' version_added: '2.4'
block_end_string: block_end_string:
description: description:
- The string marking the end of a block. - The string marking the end of a block.
type: str
default: '%}' default: '%}'
version_added: '2.4' version_added: '2.4'
variable_start_string: variable_start_string:
description: description:
- The string marking the beginning of a print statement. - The string marking the beginning of a print statement.
type: str
default: '{{' default: '{{'
version_added: '2.4' version_added: '2.4'
variable_end_string: variable_end_string:
description: description:
- The string marking the end of a print statement. - The string marking the end of a print statement.
type: str
default: '}}' default: '}}'
version_added: '2.4' version_added: '2.4'
trim_blocks: trim_blocks:
@ -84,7 +91,7 @@ options:
description: description:
- Determine when leading spaces and tabs should be stripped. - 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. - 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 type: bool
default: no default: no
version_added: '2.6' version_added: '2.6'
@ -109,11 +116,12 @@ options:
- Overrides the encoding used to write the template file defined by C(dest). - 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. - 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. - The source template file must always be encoded using C(utf-8), for homogeneity.
type: str
default: utf-8 default: utf-8
version_added: '2.7' version_added: '2.7'
notes: notes:
- Including a string that uses a date in the template will result in the template being marked 'changed' each time. - 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. 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) i.e. C(#jinja2:variable_start_string:'[%', variable_end_string:'%]', trim_blocks: False)
@ -151,7 +159,7 @@ EXAMPLES = r'''
dest: /etc/file.conf dest: /etc/file.conf
owner: bin owner: bin
group: wheel 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 - name: Create a DOS-style text file from a template
template: template:
@ -163,7 +171,7 @@ EXAMPLES = r'''
template: template:
src: /mine/sudoers src: /mine/sudoers
dest: /etc/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 - name: Update sshd configuration safely, avoid locking yourself out
template: template:

30
lib/ansible/modules/files/unarchive.py
View file

@ -24,8 +24,8 @@ description:
- The C(unarchive) module unpacks an archive. - The C(unarchive) module unpacks an archive.
- By default, it will copy the source file from the local system to the target before unpacking. - 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. - 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). - 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: options:
src: src:
description: description:
@ -33,57 +33,62 @@ options:
target server to existing archive file to unpack. 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 - 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. simple cases, for full download support use the M(get_url) module.
type: path
required: true required: true
dest: dest:
description: description:
- Remote absolute path where the archive should be unpacked. - Remote absolute path where the archive should be unpacked.
type: path
required: true required: true
copy: copy:
description: 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. - 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 has been deprecated in favor of C(remote_src).
- This option is mutually exclusive with C(remote_src). - This option is mutually exclusive with C(remote_src).
type: 'bool' type: bool
default: 'yes' default: yes
creates: creates:
description: description:
- If the specified absolute path (file or directory) already exists, this step will B(not) be run. - If the specified absolute path (file or directory) already exists, this step will B(not) be run.
type: path
version_added: "1.6" version_added: "1.6"
list_files: list_files:
description: description:
- If set to True, return the list of files that are contained in the tarball. - If set to True, return the list of files that are contained in the tarball.
type: 'bool' type: bool
default: 'no' default: no
version_added: "2.0" version_added: "2.0"
exclude: exclude:
description: description:
- List the directory and file entries that you would like to exclude from the unarchive action. - List the directory and file entries that you would like to exclude from the unarchive action.
type: list
version_added: "2.1" version_added: "2.1"
keep_newer: keep_newer:
description: description:
- Do not replace existing files that are newer than files from the archive. - Do not replace existing files that are newer than files from the archive.
type: 'bool' type: bool
default: 'no' default: no
version_added: "2.1" version_added: "2.1"
extra_opts: extra_opts:
description: description:
- Specify additional options by passing in an array. - Specify additional options by passing in an array.
type: list
default: "" default: ""
version_added: "2.1" version_added: "2.1"
remote_src: remote_src:
description: description:
- Set to C(yes) to indicate the archived file is already on the remote system and not local to the Ansible controller. - 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). - This option is mutually exclusive with C(copy).
type: 'bool' type: bool
default: 'no' default: no
version_added: "2.2" version_added: "2.2"
validate_certs: validate_certs:
description: description:
- This only applies if using a https URL as the source of the file. - 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. - 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). - Prior to 2.2 the code worked as if this was set to C(yes).
type: 'bool' type: bool
default: 'yes' default: yes
version_added: "2.2" version_added: "2.2"
extends_documentation_fragment: extends_documentation_fragment:
- decrypt - decrypt
@ -100,8 +105,9 @@ notes:
are not touched. This is the same behavior as a normal archive extraction. 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 - 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. 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: seealso:
- module: archive
- module: iso_extract
- module: win_unzip - module: win_unzip
author: Michael DeHaan author: Michael DeHaan
''' '''

14
lib/ansible/modules/files/xattr.py
View file

@ -16,26 +16,31 @@ module: xattr
version_added: "1.3" version_added: "1.3"
short_description: Manage user defined extended attributes short_description: Manage user defined extended attributes
description: description:
- Manages filesystem user defined extended attributes, requires that they are enabled - Manages filesystem user defined extended attributes.
on the target filesystem and that the setfattr/getfattr utilities are present. - Requires that extended attributes are enabled on the target filesystem
and that the setfattr/getfattr utilities are present.
options: options:
path: path:
description: description:
- The full path of the file/object to get the facts of. - The full path of the file/object to get the facts of.
- Before 2.3 this option was only usable as I(name). - Before 2.3 this option was only usable as I(name).
aliases: [ name ] type: path
required: true required: true
aliases: [ name ]
namespace: namespace:
description: description:
- Namespace of the named name/key. - Namespace of the named name/key.
type: str
default: user default: user
version_added: "2.7" version_added: "2.7"
key: key:
description: description:
- The name of a specific Extended attribute key to set/retrieve. - The name of a specific Extended attribute key to set/retrieve.
type: str
value: value:
description: description:
- The value to set the named name/key to, it automatically sets the C(state) to 'set'. - The value to set the named name/key to, it automatically sets the C(state) to 'set'.
type: str
state: state:
description: description:
- defines which state you want to do. - defines which state you want to do.
@ -44,6 +49,7 @@ options:
C(all) dumps all data C(all) dumps all data
C(keys) retrieves all keys C(keys) retrieves all keys
C(absent) deletes the key C(absent) deletes the key
type: str
choices: [ absent, all, keys, present, read ] choices: [ absent, all, keys, present, read ]
default: read default: read
follow: follow:
@ -51,7 +57,7 @@ options:
- If C(yes), dereferences symlinks and sets/gets attributes on symlink target, - If C(yes), dereferences symlinks and sets/gets attributes on symlink target,
otherwise acts on symlink itself. otherwise acts on symlink itself.
type: bool type: bool
default: 'yes' default: yes
notes: 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. - 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: author:

60
lib/ansible/modules/net_tools/basics/get_url.py
View file

@ -36,6 +36,7 @@ options:
url: url:
description: description:
- HTTP, HTTPS, or FTP URL in the form (http|https|ftp)://[user[:pass]]@host.domain[:port]/path - HTTP, HTTPS, or FTP URL in the form (http|https|ftp)://[user[:pass]]@host.domain[:port]/path
type: str
required: true required: true
dest: dest:
description: description:
@ -45,6 +46,7 @@ options:
used. If a directory, C(force) has no effect. used. If a directory, C(force) has no effect.
- If C(dest) is a directory, the file will always be downloaded - 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.. (regardless of the C(force) option), but replaced only if the contents changed..
type: path
required: true required: true
tmp_dest: tmp_dest:
description: 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 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. - 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) - U(https://docs.python.org/2/library/tempfile.html#tempfile.tempdir)
type: path
version_added: '2.1' version_added: '2.1'
force: force:
description: description:
@ -60,17 +63,16 @@ options:
will only be downloaded if the destination does not exist. Generally will only be downloaded if the destination does not exist. Generally
should be C(yes) only for small local files. should be C(yes) only for small local files.
- Prior to 0.6, this module behaved as if C(yes) was the default. - Prior to 0.6, this module behaved as if C(yes) was the default.
version_added: '0.7'
default: 'no'
type: bool type: bool
default: no
aliases: [ thirsty ] aliases: [ thirsty ]
version_added: '0.7'
backup: backup:
description: description:
- Create a backup file including the timestamp information so you can get - Create a backup file including the timestamp information so you can get
the original file back if you somehow clobbered it incorrectly. the original file back if you somehow clobbered it incorrectly.
required: false
default: 'no'
type: bool type: bool
default: no
version_added: '2.1' version_added: '2.1'
sha256sum: sha256sum:
description: description:
@ -94,65 +96,71 @@ options:
the C(dest) location, the I(destination_checksum) would be calculated, and if the C(dest) location, the I(destination_checksum) would be calculated, and if
checksum equals I(destination_checksum), the file download would be skipped checksum equals I(destination_checksum), the file download would be skipped
(unless C(force) is true). (unless C(force) is true).
type: str
default: '' default: ''
version_added: "2.0" version_added: "2.0"
use_proxy: use_proxy:
description: description:
- if C(no), it will not use a proxy, even if one is defined in - if C(no), it will not use a proxy, even if one is defined in
an environment variable on the target hosts. an environment variable on the target hosts.
default: 'yes'
type: bool type: bool
default: yes
validate_certs: validate_certs:
description: description:
- If C(no), SSL certificates will not be validated. This should only be used - If C(no), SSL certificates will not be validated.
on personally controlled sites using self-signed certificates. - This should only be used on personally controlled sites using self-signed certificates.
default: 'yes'
type: bool type: bool
default: yes
timeout: timeout:
description: description:
- Timeout in seconds for URL request. - Timeout in seconds for URL request.
type: int
default: 10 default: 10
version_added: '1.8' version_added: '1.8'
headers: headers:
description: description:
- Add custom HTTP headers to a request in hash/dict format. The hash/dict format was added in 2.6. - Add custom HTTP headers to a request in hash/dict format.
Previous versions used a C("key:value,key:value") string format. The C("key:value,key:value") string - The hash/dict format was added in 2.6.
format is deprecated and will be removed in version 2.10. - 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' version_added: '2.0'
url_username: url_username:
description: description:
- The username for use in HTTP basic authentication. - The username for use in HTTP basic authentication.
- This parameter can be used without C(url_password) for sites that allow empty passwords. - 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. - Since version 2.8 you can also use the C(username) alias for this option.
version_added: '1.6' type: str
aliases: ['username'] aliases: ['username']
version_added: '1.6'
url_password: url_password:
description: description:
- The password for use in HTTP basic authentication. - 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. - 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. - Since version 2.8 you can also use the 'password' alias for this option.
version_added: '1.6' type: str
aliases: ['password'] aliases: ['password']
version_added: '1.6'
force_basic_auth: force_basic_auth:
version_added: '2.0'
description: 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 - 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 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 send a 401, logins will fail.
upon initial request.
default: 'no'
type: bool type: bool
default: no
version_added: '2.0'
client_cert: client_cert:
description: description:
- PEM formatted certificate chain file to be used for SSL client - PEM formatted certificate chain file to be used for SSL client authentication.
authentication. This file can also include the key as well, and if - This file can also include the key as well, and if the key is included, C(client_key) is not required.
the key is included, C(client_key) is not required. type: str
version_added: '2.4' version_added: '2.4'
client_key: client_key:
description: description:
- PEM formatted file that contains your private key to be used for SSL - PEM formatted file that contains your private key to be used for SSL client authentication.
client authentication. If C(client_cert) contains both the certificate - If C(client_cert) contains both the certificate and key, this option is not required.
and key, this option is not required. type: str
version_added: '2.4' version_added: '2.4'
# informational: requirements for nodes # informational: requirements for nodes
extends_documentation_fragment: extends_documentation_fragment:
@ -171,7 +179,7 @@ EXAMPLES = r'''
get_url: get_url:
url: http://example.com/path/file.conf url: http://example.com/path/file.conf
dest: /etc/foo.conf dest: /etc/foo.conf
mode: 0440 mode: '0440'
- name: Download file and force basic auth - name: Download file and force basic auth
get_url: get_url:
@ -203,7 +211,7 @@ EXAMPLES = r'''
get_url: get_url:
url: http://example.com/path/file.conf url: http://example.com/path/file.conf
dest: /etc/foo.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 - name: Download file from a file path
get_url: get_url:

4
lib/ansible/modules/net_tools/basics/slurp.py
View file

@ -24,8 +24,8 @@ description:
options: options:
src: src:
description: description:
- The file on the remote system to fetch. This I(must) be a file, not a - The file on the remote system to fetch. This I(must) be a file, not a directory.
directory. type: path
required: true required: true
notes: 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 - 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

63
lib/ansible/modules/net_tools/basics/uri.py
View file

@ -25,53 +25,60 @@ options:
url: url:
description: description:
- HTTP or HTTPS URL in the form (http|https)://host.domain[:port]/path - HTTP or HTTPS URL in the form (http|https)://host.domain[:port]/path
type: str
required: true required: true
dest: dest:
description: description:
- A path of where to download the file to (if desired). If I(dest) is a - 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. directory, the basename of the file on the remote server will be used.
type: path
user: user:
description: description:
- A username for the module to use for Digest, Basic or WSSE authentication. - A username for the module to use for Digest, Basic or WSSE authentication.
type: str
password: password:
description: description:
- A password for the module to use for Digest, Basic or WSSE authentication. - A password for the module to use for Digest, Basic or WSSE authentication.
type: str
body: body:
description: description:
- The body of the http request/response to the web service. If C(body_format) is set - 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 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 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) or list of tuples into an 'application/x-www-form-urlencoded' string. (Added in v2.7)
type: raw
body_format: body_format:
description: description:
- The serialization format of the body. When set to C(json) or C(form-urlencoded), encodes the - 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. 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 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. set to C(json) or C(form-urlencoded) via the I(headers) option.
type: str
choices: [ form-urlencoded, json, raw ] choices: [ form-urlencoded, json, raw ]
default: raw default: raw
version_added: "2.0" version_added: "2.0"
method: method:
description: description:
- The HTTP method of the request or response. It MUST be uppercase. - 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 ] choices: [ CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, REFRESH, TRACE ]
default: GET default: GET
return_content: return_content:
description: description:
- Whether or not to return the body of the response as a "content" key in - Whether or not to return the body of the response as a "content" key in
the dictionary result. If the reported Content-type is the dictionary result.
"application/json", then the JSON is additionally loaded into a key - If the reported Content-type is "application/json", then the JSON is
called C(json) in the dictionary results. additionally loaded into a key called C(json) in the dictionary results.
type: bool type: bool
default: 'no' default: no
force_basic_auth: force_basic_auth:
description: 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 - 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 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 send a 401, logins will fail.
upon initial request.
type: bool type: bool
default: 'no' default: no
follow_redirects: follow_redirects:
description: description:
- Whether or not the URI module should follow redirects. C(all) will follow all redirects. - 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, 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) 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. are deprecated and will be removed in some future version of Ansible.
type: str
choices: [ all, 'none', safe ] choices: [ all, 'none', safe ]
default: safe default: safe
creates: creates:
description: description:
- A filename, when it already exists, this step will not be run. - A filename, when it already exists, this step will not be run.
type: path
removes: removes:
description: description:
- A filename, when it does not exist, this step will not be run. - A filename, when it does not exist, this step will not be run.
type: path
status_code: status_code:
description: description:
- A list of valid, numeric, HTTP status codes that signifies success of the - A list of valid, numeric, HTTP status codes that signifies success of the request.
request. type: int
default: 200 default: 200
timeout: timeout:
description: description:
- The socket level timeout in seconds - The socket level timeout in seconds
type: int
default: 30 default: 30
HEADER_: HEADER_:
description: description:
- Any parameter starting with "HEADER_" is a sent with your request as a header. - 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 For example, HEADER_Content-Type="application/json" would send the header
"Content-Type" along with your request with a value of "application/json". "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. Use I(headers) instead.
type: dict
headers: headers:
description: description:
- Add custom HTTP headers to a request in the format of a YAML hash. As - 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 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). generated by supplying C(json) or C(form-urlencoded) for I(body_format).
type: dict
version_added: '2.1' version_added: '2.1'
others: others:
description: description:
- All arguments accepted by the M(file) module also work here - All arguments accepted by the M(file) module also work here
validate_certs: validate_certs:
description: description:
- If C(no), SSL certificates will not be validated. This should only - If C(no), SSL certificates will not be validated.
set to C(no) used on personally controlled sites using self-signed - This should only set to C(no) used on personally controlled sites using self-signed certificates.
certificates. Prior to 1.9.2 the code defaulted to C(no). - Prior to 1.9.2 the code defaulted to C(no).
type: bool type: bool
default: 'yes' default: yes
version_added: '1.9.2' version_added: '1.9.2'
client_cert: client_cert:
description: description:
- PEM formatted certificate chain file to be used for SSL client - PEM formatted certificate chain file to be used for SSL client authentication.
authentication. This file can also include the key as well, and if - This file can also include the key as well, and if the key is included, I(client_key) is not required
the key is included, I(client_key) is not required type: path
version_added: '2.4' version_added: '2.4'
client_key: client_key:
description: description:
- PEM formatted file that contains your private key to be used for SSL - PEM formatted file that contains your private key to be used for SSL client authentication.
client authentication. If I(client_cert) contains both the certificate - If I(client_cert) contains both the certificate and key, this option is not required.
and key, this option is not required. type: path
version_added: '2.4' version_added: '2.4'
src: src:
description: 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' version_added: '2.7'
remote_src: remote_src:
description: description:
- If C(no), the module will search for src on originating/master machine, if C(yes) the - If C(no), the module will search for src on originating/master machine.
module will use the C(src) path on the remote/target machine. - If C(yes) the module will use the C(src) path on the remote/target machine.
type: bool type: bool
default: 'no' default: no
version_added: '2.7' version_added: '2.7'
notes: notes:
- The dependency on httplib2 was removed in Ansible 2.1. - The dependency on httplib2 was removed in Ansible 2.1.

20
lib/ansible/modules/system/aix_inittab.py
View file

@ -1,7 +1,7 @@
#!/usr/bin/python #!/usr/bin/python
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
# (c) 2017, Joris Weijters <joris.weijters@gmail.com> # Copyright: (c) 2017, Joris Weijters <joris.weijters@gmail.com>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) # 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 from __future__ import absolute_import, division, print_function
@ -24,15 +24,18 @@ options:
name: name:
description: description:
- Name of the inittab entry. - Name of the inittab entry.
type: str
required: yes required: yes
aliases: ['service'] aliases: [ service ]
runlevel: runlevel:
description: description:
- Runlevel of the entry. - Runlevel of the entry.
type: str
required: yes required: yes
action: action:
description: description:
- Action what the init has to do with this entry. - Action what the init has to do with this entry.
type: str
required: yes required: yes
choices: choices:
- boot - boot
@ -50,18 +53,21 @@ options:
command: command:
description: description:
- What command has to run. - What command has to run.
type: str
required: yes required: yes
insertafter: insertafter:
description: description:
- After which inittabline should the new entry inserted. - After which inittabline should the new entry inserted.
type: str
state: state:
description: description:
- Whether the entry should be present or absent in the inittab file. - Whether the entry should be present or absent in the inittab file.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
notes: notes:
- The changes are persistent across reboots, you need root rights to read or adjust the inittab with the C(lsitab), chitab, - The changes are persistent across reboots.
C(mkitab) or C(rmitab) commands. - 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. - Tested on AIX 7.1.
requirements: requirements:
- itertools - itertools
@ -101,17 +107,17 @@ EXAMPLES = '''
RETURN = ''' RETURN = '''
name: name:
description: name of the adjusted inittab entry description: Name of the adjusted inittab entry
returned: always returned: always
type: str type: str
sample: startmyservice sample: startmyservice
msg: msg:
description: action done with the inittab entry description: Action done with the inittab entry
returned: changed returned: changed
type: str type: str
sample: changed inittab entry startmyservice sample: changed inittab entry startmyservice
changed: changed:
description: whether the inittab changed or not description: Whether the inittab changed or not
returned: always returned: always
type: bool type: bool
sample: true sample: true

33
lib/ansible/modules/system/aix_lvol.py
View file

@ -1,7 +1,7 @@
#!/usr/bin/python #!/usr/bin/python
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
# (c) 2016, Alain Dejoux <adejoux@djouxtech.net> # Copyright: (c) 2016, Alain Dejoux <adejoux@djouxtech.net>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) # 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 from __future__ import absolute_import, division, print_function
@ -25,40 +25,51 @@ options:
vg: vg:
description: description:
- The volume group this logical volume is part of. - The volume group this logical volume is part of.
type: str
required: true required: true
lv: lv:
description: description:
- The name of the logical volume. - The name of the logical volume.
type: str
required: true required: true
lv_type: lv_type:
description: description:
- The type of the logical volume. - The type of the logical volume.
type: str
default: jfs2 default: jfs2
size: size:
description: description:
- The size of the logical volume with one of the [MGT] units. - The size of the logical volume with one of the [MGT] units.
type: str
copies: copies:
description: description:
- The number of copies of the logical volume. Maximum copies are 3. - The number of copies of the logical volume.
default: '1' - Maximum copies are 3.
type: int
default: 1
policy: 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 ] choices: [ maximum, minimum ]
default: maximum 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: state:
choices: [ absent, present ]
default: present
description: description:
- Control if the logical volume exists. If C(present) and the - Control if the logical volume exists. If C(present) and the
volume does not already exist then the C(size) option is required. volume does not already exist then the C(size) option is required.
type: str
choices: [ absent, present ]
default: present
opts: opts:
description: description:
- Free-form options to be passed to the mklv command. - Free-form options to be passed to the mklv command.
type: str
pvs: pvs:
description: 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''' EXAMPLES = r'''
@ -73,7 +84,7 @@ EXAMPLES = r'''
vg: testvg vg: testvg
lv: test2lv lv: test2lv
size: 512M size: 512M
pvs: hdisk1,hdisk2 pvs: [ hdisk1, hdisk2 ]
- name: Create a logical volume of 512M mirrored - name: Create a logical volume of 512M mirrored
aix_lvol: aix_lvol:
@ -205,7 +216,7 @@ def main():
lv_type=dict(type='str', default='jfs2'), lv_type=dict(type='str', default='jfs2'),
size=dict(type='str'), size=dict(type='str'),
opts=dict(type='str', default=''), 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']), state=dict(type='str', default='present', choices=['absent', 'present']),
policy=dict(type='str', default='maximum', choices=['maximum', 'minimum']), policy=dict(type='str', default='maximum', choices=['maximum', 'minimum']),
pvs=dict(type='list', default=list()) pvs=dict(type='list', default=list())

37
lib/ansible/modules/system/alternatives.py
View file

@ -1,8 +1,8 @@
#!/usr/bin/python #!/usr/bin/python
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
# (c) 2014, Gabe Mulley <gabe.mulley@gmail.com> # Copyright: (c) 2014, Gabe Mulley <gabe.mulley@gmail.com>
# (c) 2015, David Wittman <dwittman@gmail.com> # Copyright: (c) 2015, David Wittman <dwittman@gmail.com>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) # 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 from __future__ import absolute_import, division, print_function
@ -14,54 +14,56 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'supported_by': 'community'} 'supported_by': 'community'}
DOCUMENTATION = ''' DOCUMENTATION = r'''
--- ---
module: alternatives module: alternatives
short_description: Manages alternative programs for common commands short_description: Manages alternative programs for common commands
description: 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). - Useful when multiple programs are installed but provide similar functionality (e.g. different editors).
version_added: "1.6" version_added: "1.6"
author: author:
- "David Wittman (@DavidWittman)" - David Wittman (@DavidWittman)
- "Gabe Mulley (@mulby)" - Gabe Mulley (@mulby)
options: options:
name: name:
description: description:
- The generic name of the link. - The generic name of the link.
type: str
required: true required: true
path: path:
description: description:
- The path to the real executable that the link should point to. - The path to the real executable that the link should point to.
type: path
required: true required: true
link: link:
description: description:
- The path to the symbolic link that should point to the real executable. - 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 - 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 when the alternative I(name) is unknown to the system.
required: false type: path
priority: priority:
description: description:
- The priority of the alternative - The priority of the alternative.
required: false type: int
default: 50 default: 50
version_added: "2.2" version_added: "2.2"
requirements: [ update-alternatives ] requirements: [ update-alternatives ]
''' '''
EXAMPLES = ''' EXAMPLES = r'''
- name: correct java version selected - name: Correct java version selected
alternatives: alternatives:
name: java name: java
path: /usr/lib/jvm/java-7-openjdk-amd64/jre/bin/java path: /usr/lib/jvm/java-7-openjdk-amd64/jre/bin/java
- name: alternatives link created - name: Alternatives link created
alternatives: alternatives:
name: hadoop-conf name: hadoop-conf
link: /etc/hadoop/conf link: /etc/hadoop/conf
path: /etc/hadoop/conf.ansible 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: alternatives:
name: java name: java
path: /usr/lib/jvm/java-7-openjdk-i386/jre/bin/java path: /usr/lib/jvm/java-7-openjdk-i386/jre/bin/java
@ -79,11 +81,10 @@ def main():
module = AnsibleModule( module = AnsibleModule(
argument_spec=dict( argument_spec=dict(
name=dict(required=True), name=dict(type='str', required=True),
path=dict(required=True, type='path'), path=dict(type='path', required=True),
link=dict(required=False, type='path'), link=dict(type='path'),
priority=dict(required=False, type='int', priority=dict(type='int', default=50),
default=50),
), ),
supports_check_mode=True, supports_check_mode=True,
) )

17
lib/ansible/modules/system/at.py
View file

@ -23,28 +23,33 @@ options:
command: command:
description: description:
- A command to be executed in the future. - A command to be executed in the future.
type: str
script_file: script_file:
description: description:
- An existing script file to be executed in the future. - An existing script file to be executed in the future.
type: str
count: count:
description: description:
- The count of units in the future to execute the command or script file. - The count of units in the future to execute the command or script file.
type: int
required: true required: true
units: units:
description: description:
- The type of units in the future to execute the command or script file. - The type of units in the future to execute the command or script file.
choices: [ minutes, hours, days, weeks ] type: str
required: true required: true
choices: [ minutes, hours, days, weeks ]
state: state:
description: description:
- The state dictates if the command or script file should be evaluated as present(added) or absent(deleted). - The state dictates if the command or script file should be evaluated as present(added) or absent(deleted).
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
unique: unique:
description: description:
- If a matching job is present a new job will not be added. - If a matching job is present a new job will not be added.
type: bool type: bool
default: 'no' default: no
requirements: requirements:
- at - at
author: author:
@ -52,18 +57,18 @@ author:
''' '''
EXAMPLES = ''' EXAMPLES = '''
- name: Schedule a command to execute in 20 minutes as root. - name: Schedule a command to execute in 20 minutes as root
at: at:
command: ls -d / >/dev/null command: ls -d / >/dev/null
count: 20 count: 20
units: minutes 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: at:
command: ls -d / >/dev/null command: ls -d / >/dev/null
state: absent 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: at:
command: ls -d / >/dev/null command: ls -d / >/dev/null
count: 20 count: 20
@ -140,7 +145,7 @@ def main():
script_file=dict(type='str'), script_file=dict(type='str'),
count=dict(type='int'), count=dict(type='int'),
units=dict(type='str', choices=['minutes', 'hours', 'days', 'weeks']), 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), unique=dict(type='bool', default=False),
), ),
mutually_exclusive=[['command', 'script_file']], mutually_exclusive=[['command', 'script_file']],

94
lib/ansible/modules/system/authorized_key.py
View file

@ -1,7 +1,7 @@
#!/usr/bin/python #!/usr/bin/python
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
# (c) 2012, Brad Olson <brado@movedbylight.com> # Copyright: (c) 2012, Brad Olson <brado@movedbylight.com>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) # 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 from __future__ import absolute_import, division, print_function
@ -13,81 +13,86 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'supported_by': 'core'} 'supported_by': 'core'}
DOCUMENTATION = ''' DOCUMENTATION = r'''
--- ---
module: authorized_key module: authorized_key
short_description: Adds or removes an SSH authorized key short_description: Adds or removes an SSH authorized key
description: 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" version_added: "0.5"
options: options:
user: user:
description: 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 required: true
key: key:
description: 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 required: true
path: path:
description: description:
- Alternate path to the authorized_keys file - Alternate path to the authorized_keys file.
default: "(homedir)+/.ssh/authorized_keys" - When unset, this value defaults to I(~/.ssh/authorized_keys).
type: path
version_added: "1.2" version_added: "1.2"
manage_dir: manage_dir:
description: description:
- Whether this module should manage the directory of the authorized key file. If - Whether this module should manage the directory of the authorized key file.
set, the module will create the directory, as well as set the owner and permissions - 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 of an existing directory.
set C(manage_dir=no) if you are using an alternate directory for - Be sure to set C(manage_dir=no) if you are using an alternate directory for authorized_keys,
authorized_keys, as set with C(path), since you could lock yourself out of as set with C(path), since you could lock yourself out of SSH access.
SSH access. See the example below. - See the example below.
type: bool type: bool
default: 'yes' default: yes
version_added: "1.2" version_added: "1.2"
state: state:
description: description:
- Whether the given key (with the given key_options) should or should not be in the file - Whether the given key (with the given key_options) should or should not be in the file.
choices: [ "present", "absent" ] type: str
default: "present" choices: [ absent, present ]
default: present
key_options: key_options:
description: 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" version_added: "1.4"
exclusive: exclusive:
description: description:
- Whether to remove all other non-specified keys from the authorized_keys file. Multiple keys - Whether to remove all other non-specified keys from the authorized_keys file.
can be specified in a single C(key) string value by separating them by newlines. - 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 - This option is not loop aware, so if you use C(with_) , it will be exclusive per iteration of the loop.
of the loop, if you want multiple keys in the file you need to pass them all to C(key) in a - If you want multiple keys in the file you need to pass them all to C(key) in a single batch as mentioned above.
single batch as mentioned above.
type: bool type: bool
default: 'no' default: no
version_added: "1.9" version_added: "1.9"
validate_certs: validate_certs:
description: 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. - 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). - Prior to 2.1 the code worked as if this was set to C(yes).
type: bool type: bool
default: 'yes' default: yes
version_added: "2.1" version_added: "2.1"
comment: comment:
description: description:
- Change the comment on the public key. Rewriting the comment is useful in - Change the comment on the public key.
cases such as fetching it from GitHub or GitLab. - 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. - If no comment is specified, the existing comment will be kept.
type: str
version_added: "2.4" version_added: "2.4"
follow: follow:
description: description:
- Follow path symlink instead of replacing it - Follow path symlink instead of replacing it.
type: bool type: bool
default: 'no' default: no
version_added: "2.7" version_added: "2.7"
author: "Ansible Core Team" author: Ansible Core Team
''' '''
EXAMPLES = ''' EXAMPLES = r'''
- name: Set authorized key taken from file - name: Set authorized key taken from file
authorized_key: authorized_key:
user: charlie user: charlie
@ -147,7 +152,7 @@ EXAMPLES = '''
key: "{{ lookup('file', lookup('env','HOME') + '/.ssh/id_rsa.pub') }}" key: "{{ lookup('file', lookup('env','HOME') + '/.ssh/id_rsa.pub') }}"
''' '''
RETURN = ''' RETURN = r'''
exclusive: exclusive:
description: If the key has been forced to be exclusive or not. description: If the key has been forced to be exclusive or not.
returned: success returned: success
@ -655,19 +660,18 @@ def enforce_state(module, params):
def main(): def main():
module = AnsibleModule( module = AnsibleModule(
argument_spec=dict( argument_spec=dict(
user=dict(required=True, type='str'), user=dict(type='str', required=True),
key=dict(required=True, type='str'), key=dict(type='str', required=True),
path=dict(required=False, type='str'), path=dict(type='str'),
manage_dir=dict(required=False, type='bool', default=True), manage_dir=dict(type='bool', default=True),
state=dict(default='present', choices=['absent', 'present']), state=dict(type='str', default='present', choices=['absent', 'present']),
key_options=dict(required=False, type='str'), key_options=dict(type='str'),
unique=dict(default=False, type='bool'), exclusive=dict(type='bool', default=False),
exclusive=dict(default=False, type='bool'), comment=dict(type='str'),
comment=dict(required=False, default=None, type='str'), validate_certs=dict(type='bool', default=True),
validate_certs=dict(default=True, type='bool'), follow=dict(type='bool', default=False),
follow=dict(default=False, type='bool')
), ),
supports_check_mode=True supports_check_mode=True,
) )
results = enforce_state(module, module.params) results = enforce_state(module, module.params)

40
lib/ansible/modules/system/awall.py
View file

@ -1,7 +1,7 @@
#!/usr/bin/python #!/usr/bin/python
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
#
# (c) 2017, Ted Trask <ttrask01@yahoo.com> # Copyright: (c) 2017, Ted Trask <ttrask01@yahoo.com>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) # 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 from __future__ import absolute_import, division, print_function
@ -12,7 +12,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['stableinterface'], 'status': ['stableinterface'],
'supported_by': 'community'} 'supported_by': 'community'}
DOCUMENTATION = ''' DOCUMENTATION = r'''
--- ---
module: awall module: awall
short_description: Manage awall policies short_description: Manage awall policies
@ -20,40 +20,44 @@ version_added: "2.4"
author: Ted Trask (@tdtrask) <ttrask01@yahoo.com> author: Ted Trask (@tdtrask) <ttrask01@yahoo.com>
description: description:
- This modules allows for enable/disable/activate of I(awall) policies. - 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. and activates the configuration on the system.
options: options:
name: name:
description: description:
- A policy name, like C(foo), or multiple policies, like C(foo, bar). - One or more policy names.
type: list
state: state:
description: description:
- The policy(ies) will be C(enabled) - Whether the policies should be enabled or disabled.
- The policy(ies) will be C(disabled) type: str
choices: [ disabled, enabled ]
default: enabled default: enabled
choices: [ "enabled", "disabled" ]
activate: activate:
description: 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 type: bool
default: 'no' default: no
''' '''
EXAMPLES = ''' EXAMPLES = r'''
- name: Enable "foo" and "bar" policy - name: Enable "foo" and "bar" policy
awall: awall:
name: foo,bar name: [ foo bar ]
state: enabled state: enabled
- name: Disable "foo" and "bar" policy and activate new rules - name: Disable "foo" and "bar" policy and activate new rules
awall: awall:
name: foo,bar name:
- foo
- bar
state: disabled state: disabled
activate: False activate: no
- name: Activate currently enabled firewall rules - name: Activate currently enabled firewall rules
awall: awall:
activate: True activate: yes
''' '''
RETURN = ''' # ''' RETURN = ''' # '''
@ -122,12 +126,12 @@ def disable_policy(module, names, act):
def main(): def main():
module = AnsibleModule( module = AnsibleModule(
argument_spec=dict( argument_spec=dict(
state=dict(default='enabled', choices=['enabled', 'disabled']), state=dict(type='str', default='enabled', choices=['disabled', 'enabled']),
name=dict(type='list'), name=dict(type='list'),
activate=dict(default=False, type='bool'), activate=dict(type='bool', default=False),
), ),
required_one_of=[['name', 'activate']], required_one_of=[['name', 'activate']],
supports_check_mode=True supports_check_mode=True,
) )
global AWALL_PATH global AWALL_PATH

55
lib/ansible/modules/system/beadm.py
View file

@ -1,7 +1,7 @@
#!/usr/bin/python #!/usr/bin/python
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
# (c) 2016, Adam Števko <adam.stevko@gmail.com> # Copyright: (c) 2016, Adam Števko <adam.stevko@gmail.com>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) # 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 from __future__ import absolute_import, division, print_function
@ -13,7 +13,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'supported_by': 'community'} 'supported_by': 'community'}
DOCUMENTATION = ''' DOCUMENTATION = r'''
--- ---
module: beadm module: beadm
short_description: Manage ZFS boot environments on FreeBSD/Solaris/illumos systems. short_description: Manage ZFS boot environments on FreeBSD/Solaris/illumos systems.
@ -26,47 +26,43 @@ options:
name: name:
description: description:
- ZFS boot environment name. - ZFS boot environment name.
aliases: [ "be" ] type: str
required: True required: True
aliases: [ "be" ]
snapshot: snapshot:
description: description:
- If specified, the new boot environment will be cloned from the given - If specified, the new boot environment will be cloned from the given
snapshot or inactive boot environment. snapshot or inactive boot environment.
required: false type: str
default: false
description: description:
description: description:
- Associate a description with a new boot environment. This option is - Associate a description with a new boot environment. This option is
available only on Solarish platforms. available only on Solarish platforms.
required: false type: str
default: false
options: options:
description: description:
- Create the datasets for new BE with specific ZFS properties. Multiple - Create the datasets for new BE with specific ZFS properties.
options can be specified. This option is available only on - Multiple options can be specified.
Solarish platforms. - This option is available only on Solarish platforms.
required: false type: str
default: false
mountpoint: mountpoint:
description: description:
- Path where to mount the ZFS boot environment - Path where to mount the ZFS boot environment.
required: false type: path
default: false
state: state:
description: description:
- Create or delete ZFS boot environment. - Create or delete ZFS boot environment.
required: false type: str
default: "present" choices: [ absent, activated, mounted, present, unmounted ]
choices: [ "present", "absent", "activated", "mounted", "unmounted" ] default: present
force: force:
description: description:
- Specifies if the unmount should be forced. - Specifies if the unmount should be forced.
required: false
default: false
type: bool type: bool
default: false
''' '''
EXAMPLES = ''' EXAMPLES = r'''
- name: Create ZFS boot environment - name: Create ZFS boot environment
beadm: beadm:
name: upgrade-be name: upgrade-be
@ -107,7 +103,7 @@ EXAMPLES = '''
state: activated state: activated
''' '''
RETURN = ''' RETURN = r'''
name: name:
description: BE name description: BE name
returned: always returned: always
@ -139,7 +135,7 @@ state:
type: str type: str
sample: present sample: present
force: force:
description: if forced action is wanted description: If forced action is wanted
returned: always returned: always
type: bool type: bool
sample: False sample: False
@ -288,18 +284,15 @@ class BE(object):
def main(): def main():
module = AnsibleModule( module = AnsibleModule(
argument_spec=dict( argument_spec=dict(
name=dict(required=True, aliases=['be'], type='str'), name=dict(type='str', required=True, aliases=['be']),
snapshot=dict(type='str'), snapshot=dict(type='str'),
description=dict(type='str'), description=dict(type='str'),
options=dict(type='str'), options=dict(type='str'),
mountpoint=dict(default=False, type='path'), mountpoint=dict(type='path'),
state=dict( state=dict(type='str', default='present', choices=['absent', 'activated', 'mounted', 'present', 'unmounted']),
default='present', force=dict(type='bool', default=False),
choices=['present', 'absent', 'activated',
'mounted', 'unmounted']),
force=dict(default=False, type='bool'),
), ),
supports_check_mode=True supports_check_mode=True,
) )
be = BE(module) be = BE(module)

16
lib/ansible/modules/system/capabilities.py
View file

@ -11,7 +11,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'], 'status': ['preview'],
'supported_by': 'community'} 'supported_by': 'community'}
DOCUMENTATION = ''' DOCUMENTATION = r'''
--- ---
module: capabilities module: capabilities
short_description: Manage Linux capabilities short_description: Manage Linux capabilities
@ -22,28 +22,30 @@ options:
path: path:
description: description:
- Specifies the path to the file to be managed. - Specifies the path to the file to be managed.
type: str
required: yes required: yes
capability: capability:
description: description:
- Desired capability to set (with operator and flags, if state is C(present)) or remove (if state is C(absent)) - Desired capability to set (with operator and flags, if state is C(present)) or remove (if state is C(absent))
type: str
required: yes required: yes
aliases: [ cap ] aliases: [ cap ]
state: state:
description: description:
- Whether the entry should be present or absent in the file's capabilities. - Whether the entry should be present or absent in the file's capabilities.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
notes: notes:
- The capabilities system will automatically transform operators and flags - The capabilities system will automatically transform operators and flags into the effective set,
into the effective set, so (for example, cap_foo=ep will probably become so for example, C(cap_foo=ep) will probably become C(cap_foo+ep).
cap_foo+ep). This module does not attempt to determine the final operator - This module does not attempt to determine the final operator and flags to compare,
and flags to compare, so you will want to ensure that your capabilities so you will want to ensure that your capabilities argument matches the final capabilities.
argument matches the final capabilities.
author: author:
- Nate Coraor (@natefoo) - Nate Coraor (@natefoo)
''' '''
EXAMPLES = ''' EXAMPLES = r'''
- name: Set cap_sys_chroot+ep on /foo - name: Set cap_sys_chroot+ep on /foo
capabilities: capabilities:
path: /foo path: /foo

6
lib/ansible/modules/system/firewalld.py
View file

@ -65,9 +65,9 @@ options:
default: system-default(public) default: system-default(public)
permanent: permanent:
description: description:
- > - Should this configuration be in the running firewalld configuration or persist across reboots.
Should this configuration be in the running firewalld configuration or persist across reboots. As of Ansible version 2.3, permanent operations can - As of Ansible 2.3, permanent operations can operate on firewalld configs when it is not running (requires firewalld >= 3.0.9).
operate on firewalld configs when it's not running (requires firewalld >= 3.0.9). (NOTE: If this is false, immediate is assumed true.) - Note that if this is C(no), immediate is assumed C(yes).
type: bool type: bool
immediate: immediate:
description: description:

25
lib/ansible/modules/system/group.py
View file

@ -14,8 +14,6 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
DOCUMENTATION = ''' DOCUMENTATION = '''
--- ---
module: group module: group
author:
- Stephen Fromm (@sfromm)
version_added: "0.0.2" version_added: "0.0.2"
short_description: Add or remove groups short_description: Add or remove groups
requirements: requirements:
@ -29,32 +27,37 @@ options:
name: name:
description: description:
- Name of the group to manage. - Name of the group to manage.
type: str
required: true required: true
gid: gid:
description: description:
- Optional I(GID) to set for the group. - Optional I(GID) to set for the group.
type: int
state: state:
description: description:
- Whether the group should be present or not on the remote host. - Whether the group should be present or not on the remote host.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
system: system:
description: description:
- If I(yes), indicates that the group created is a system group. - If I(yes), indicates that the group created is a system group.
type: bool type: bool
default: 'no' default: no
local: local:
version_added: "2.6"
required: false
default: 'no'
type: bool
description: description:
- Forces the use of "local" command alternatives on platforms that implement it. - 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. - 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`. (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. - This requires that these commands exist on the targeted host, otherwise it will be a fatal error.
notes: type: bool
- For Windows targets, use the M(win_group) module instead. default: no
version_added: "2.6"
seealso:
- module: user
- module: win_group
author:
- Stephen Fromm (@sfromm)
''' '''
EXAMPLES = ''' EXAMPLES = '''

24
lib/ansible/modules/system/lvg.py
View file

@ -12,7 +12,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'], 'status': ['preview'],
'supported_by': 'community'} 'supported_by': 'community'}
DOCUMENTATION = ''' DOCUMENTATION = r'''
--- ---
author: author:
- Alexander Bulimov (@abulimov) - Alexander Bulimov (@abulimov)
@ -25,40 +25,50 @@ options:
vg: vg:
description: description:
- The name of the volume group. - The name of the volume group.
type: str
required: true required: true
pvs: pvs:
description: 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. - The module will take care of running pvcreate if needed.
type: list
pesize: pesize:
description: description:
- The size of the physical extent. pesize must be a power of 2, or - The size of the physical extent. pesize must be a power of 2, or multiple of 128KiB.
multiple of 128KiB. Since version 2.6, pesize can be optionally suffixed - Since Ansible 2.6, pesize can be optionally suffixed by a UNIT (k/K/m/M/g/G), default unit is megabyte.
by a UNIT (k/K/m/M/g/G), default unit is megabyte. type: int
default: 4 default: 4
pv_options: pv_options:
description: description:
- Additional options to pass to C(pvcreate) when creating the volume group. - Additional options to pass to C(pvcreate) when creating the volume group.
type: str
version_added: "2.4" version_added: "2.4"
vg_options: vg_options:
description: description:
- Additional options to pass to C(vgcreate) when creating the volume group. - Additional options to pass to C(vgcreate) when creating the volume group.
type: str
version_added: "1.6" version_added: "1.6"
state: state:
description: description:
- Control if the volume group exists. - Control if the volume group exists.
type: str
choices: [ absent, present ] choices: [ absent, present ]
default: present default: present
force: force:
description: description:
- If C(yes), allows to remove volume group with logical volumes. - If C(yes), allows to remove volume group with logical volumes.
type: bool type: bool
default: 'no' default: no
seealso:
- module: filesystem
- module: lvol
- module: parted
notes: notes:
- This module does not modify PE size for already present volume group. - 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 - name: Create a volume group on top of /dev/sda1 with physical extent size = 32MB
lvg: lvg:
vg: vg.services vg: vg.services

132
lib/ansible/modules/system/pamd.py
View file

@ -1,7 +1,7 @@
#!/usr/bin/python #!/usr/bin/python
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
# (c) 2017, Kenneth D. Evensen <kdevensen@gmail.com>
# Copyright: (c) 2017, Kenneth D. Evensen <kdevensen@gmail.com>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) # 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) from __future__ import (absolute_import, division, print_function)
@ -13,93 +13,93 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'supported_by': 'community'} 'supported_by': 'community'}
DOCUMENTATION = """ DOCUMENTATION = r'''
module: pamd module: pamd
author: author:
- "Kenneth D. Evensen (@kevensen)" - Kenneth D. Evensen (@kevensen)
short_description: Manage PAM Modules short_description: Manage PAM Modules
description: description:
- Edit PAM service's type, control, module path and module arguments. - 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. module_path must match an existing rule. See man(5) pam.d for details.
version_added: "2.3" version_added: "2.3"
options: options:
name: name:
required: true
description: description:
- The name generally refers to the PAM service file to - The name generally refers to the PAM service file to
change, for example system-auth. change, for example system-auth.
type: str
required: true
type: type:
required: true
description: description:
- The type of the PAM rule being modified. The type, control - The type of the PAM rule being modified.
and module_path all must match a rule to be modified. - The C(type), C(control) and C(module_path) all must match a rule to be modified.
type: str
required: true
control: control:
required: true
description: description:
- The control of the PAM rule being modified. This may be a - The control of the PAM rule being modified.
complicated control with brackets. If this is the case, be - This may be a complicated control with brackets. If this is the case, be
sure to put "[bracketed controls]" in quotes. The type, sure to put "[bracketed controls]" in quotes.
control and module_path all must match a rule to be modified. - The C(type), C(control) and C(module_path) all must match a rule to be modified.
type: str
required: true
module_path: module_path:
required: true
description: description:
- The module path of the PAM rule being modified. The type, - The module path of the PAM rule being modified.
control and module_path all must match a rule to be modified. - The C(type), C(control) and C(module_path) all must match a rule to be modified.
type: str
required: true
new_type: new_type:
description: description:
- The new type to assign to the new rule. - The new type to assign to the new rule.
type: str
new_control: new_control:
description: description:
- The new control to assign to the new rule. - The new control to assign to the new rule.
type: str
new_module_path: new_module_path:
description: description:
- The new module path to be assigned to the new rule. - The new module path to be assigned to the new rule.
type: str
module_arguments: module_arguments:
description: description:
- When state is 'updated', the module_arguments will replace existing - When state is C(updated), the module_arguments will replace existing module_arguments.
module_arguments. When state is 'args_absent' args matching those - When state is C(args_absent) args matching those listed in module_arguments will be removed.
listed in module_arguments will be removed. When state is - When state is C(args_present) any args listed in module_arguments are added if
'args_present' any args listed in module_arguments are added if missing from the existing rule.
missing from the existing rule. Furthermore, if the module argument - Furthermore, if the module argument takes a value denoted by C(=),
takes a value denoted by '=', the value will be changed to that specified the value will be changed to that specified in module_arguments.
in module_arguments. Note that module_arguments is a list. Please see type: list
the examples for usage.
state: state:
default: updated
choices:
- updated
- before
- after
- args_present
- args_absent
- absent
description: description:
- The default of 'updated' will modify an existing rule if type, - The default of C(updated) will modify an existing rule if type,
control and module_path all match an existing rule. With 'before', control and module_path all match an existing rule.
the new rule will be inserted before a rule matching type, control - With C(before), the new rule will be inserted before a rule matching type,
and module_path. Similarly, with 'after', the new rule will be inserted control and module_path.
after an existing rule matching type, control and module_path. With - Similarly, with C(after), the new rule will be inserted after an existing rulematching type,
either 'before' or 'after' new_type, new_control, and new_module_path control and module_path.
must all be specified. If state is 'args_absent' or 'args_present', - With either C(before) or C(after) new_type, new_control, and new_module_path must all be specified.
new_type, new_control, and new_module_path will be ignored. State - If state is C(args_absent) or C(args_present), new_type, new_control, and new_module_path will be ignored.
'absent' will remove the rule. The 'absent' state was added in version - State C(absent) will remove the rule. The 'absent' state was added in Ansible 2.4.
2.4 and is only available in Ansible versions >= 2.4. type: str
choices: [ absent, before, after, args_absent, args_present, updated ]
default: updated
path: path:
default: /etc/pam.d/
description: description:
- This is the path to the PAM service files - This is the path to the PAM service files
type: path
default: /etc/pam.d/
backup: backup:
description: description:
- Create a backup file including the timestamp information so you can - Create a backup file including the timestamp information so you can
get the original file back if you somehow clobbered it incorrectly. get the original file back if you somehow clobbered it incorrectly.
type: bool type: bool
default: 'no' default: no
version_added: '2.6' version_added: '2.6'
'''
""" EXAMPLES = r'''
EXAMPLES = """
- name: Update pamd rule's control in /etc/pam.d/system-auth - name: Update pamd rule's control in /etc/pam.d/system-auth
pamd: pamd:
name: system-auth name: system-auth
@ -220,9 +220,9 @@ EXAMPLES = """
type: auth type: auth
module_path: pam_sss.so module_path: pam_sss.so
control: 'requisite' control: 'requisite'
""" '''
RETURN = ''' RETURN = r'''
change_count: change_count:
description: How many rules were changed description: How many rules were changed
type: int type: int
@ -230,14 +230,14 @@ change_count:
returned: success returned: success
version_added: 2.4 version_added: 2.4
new_rule: 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 type: str
sample: None None None sha512 shadow try_first_pass use_authtok sample: None None None sha512 shadow try_first_pass use_authtok
returned: success returned: success
version_added: 2.4 version_added: 2.4
updated_rule_(n): updated_rule_(n):
description: The rule(s) that was/were changed. This is only available in 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 type: str
sample: sample:
- password sufficient pam_unix.so sha512 shadow try_first_pass - password sufficient pam_unix.so sha512 shadow try_first_pass
@ -248,7 +248,7 @@ action:
description: description:
- "That action that was taken and is one of: update_rule, - "That action that was taken and is one of: update_rule,
insert_before_rule, insert_after_rule, args_present, args_absent, 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 returned: always
type: str type: str
sample: "update_rule" sample: "update_rule"
@ -256,7 +256,7 @@ action:
dest: dest:
description: description:
- "Path to pam.d service that was changed. This is only available in - "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 returned: success
type: str type: str
sample: "/etc/pam.d/system-auth" sample: "/etc/pam.d/system-auth"
@ -770,21 +770,17 @@ def main():
module = AnsibleModule( module = AnsibleModule(
argument_spec=dict( argument_spec=dict(
name=dict(required=True, type='str'), name=dict(type='str', required=True),
type=dict(required=True, type=dict(type='str', required=True, choices=VALID_TYPES),
choices=VALID_TYPES), control=dict(type='str', required=True),
control=dict(required=True, type='str'), module_path=dict(type='str', required=True),
module_path=dict(required=True, type='str'), new_type=dict(type='str', choices=VALID_TYPES),
new_type=dict(required=False, new_control=dict(type='str'),
choices=VALID_TYPES), new_module_path=dict(type='str'),
new_control=dict(required=False, type='str'), module_arguments=dict(type='list'),
new_module_path=dict(required=False, type='str'), state=dict(type='str', default='updated', choices=['absent', 'after', 'args_absent', 'args_present', 'before', 'updated']),
module_arguments=dict(required=False, type='list'), path=dict(type='path', default='/etc/pam.d'),
state=dict(required=False, default="updated", backup=dict(type='bool', default=False),
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')
), ),
supports_check_mode=True, supports_check_mode=True,
required_if=[ required_if=[

172
lib/ansible/modules/system/parted.py
View file

@ -1,7 +1,7 @@
#!/usr/bin/python #!/usr/bin/python
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
# (c) 2016, Fabrizio Colonna <colofabrix@tin.it> # Copyright: (c) 2016, Fabrizio Colonna <colofabrix@tin.it>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) # 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 from __future__ import absolute_import, division, print_function
@ -13,10 +13,10 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'supported_by': 'community'} 'supported_by': 'community'}
DOCUMENTATION = ''' DOCUMENTATION = r'''
--- ---
author: author:
- "Fabrizio Colonna (@ColOfAbRiX)" - Fabrizio Colonna (@ColOfAbRiX)
module: parted module: parted
short_description: Configure block device partitions short_description: Configure block device partitions
version_added: "2.3" version_added: "2.3"
@ -24,11 +24,6 @@ description:
- This module allows configuring block device partition using the C(parted) - This module allows configuring block device partition using the C(parted)
command line tool. For a full description of the fields and the options command line tool. For a full description of the fields and the options
check the GNU parted manual. 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: requirements:
- This module requires parted version 1.8.3 and above. - 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 - If the version of parted is below 3.1, it requires a Linux version running
@ -36,70 +31,79 @@ requirements:
options: options:
device: device:
description: The block device (disk) where to operate. description: The block device (disk) where to operate.
type: str
required: True required: True
align: align:
description: Set alignment for newly created partitions. description: Set alignment for newly created partitions.
choices: ['none', 'cylinder', 'minimal', 'optimal'] type: str
choices: [ cylinder, minimal, none, optimal ]
default: optimal default: optimal
number: number:
description: description:
- The number of the partition to work with or the number of the partition - 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, that will be created.
except fetching information. - Required when performing any action on the disk, except fetching information.
type: int
unit: unit:
description: description:
- Selects the current default unit that Parted will use to display - Selects the current default unit that Parted will use to display
locations and capacities on the disk and to interpret those given by the 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 user if they are not suffixed by an unit.
a disk, it is always recommended to specify a unit. - When fetching information about a disk, it is always recommended to specify a unit.
choices: [ type: str
's', 'B', 'KB', 'KiB', 'MB', 'MiB', 'GB', 'GiB', 'TB', 'TiB', '%', 'cyl', choices: [ s, B, KB, KiB, MB, MiB, GB, GiB, TB, TiB, '%', cyl, chs, compact ]
'chs', 'compact'
]
default: KiB default: KiB
label: label:
description: Creates a new disk label. description: Creates a new disk label.
choices: [ type: str
'aix', 'amiga', 'bsd', 'dvh', 'gpt', 'loop', 'mac', 'msdos', 'pc98', choices: [ aix, amiga, bsd, dvh, gpt, loop, mac, msdos, pc98, sun ]
'sun'
]
default: msdos default: msdos
part_type: part_type:
description: description:
- Is one of 'primary', 'extended' or 'logical' and may be specified only - May be specified only with 'msdos' or 'dvh' partition tables.
with 'msdos' or 'dvh' partition tables. A name must be specified for a - A C(name) must be specified for a 'gpt' partition table.
'gpt' partition table. Neither part-type nor name may be used with a - Neither C(part_type) nor C(name) may be used with a 'sun' partition table.
'sun' partition table. type: str
choices: ['primary', 'extended', 'logical'] choices: [ extended, logical, primary ]
default: primary default: primary
part_start: part_start:
description: description:
- Where the partition will start as offset from the beginning of the disk, - 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 that is, the "distance" from the start of the disk.
specified with all the units supported by parted (except compat) and - The distance can be specified with all the units supported by parted
it is case sensitive. E.g. C(10GiB), C(15%). (except compat) and it is case sensitive, e.g. C(10GiB), C(15%).
type: str
default: 0% default: 0%
part_end : part_end :
description: description:
- Where the partition will end as offset from the beginning of the disk, - 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 that is, the "distance" from the start of the disk.
specified with all the units supported by parted (except compat) and - The distance can be specified with all the units supported by parted
it is case sensitive. E.g. C(10GiB), C(15%). (except compat) and it is case sensitive, e.g. C(10GiB), C(15%).
type: str
default: 100% default: 100%
name: name:
description: 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: flags:
description: A list of the flags that has to be set on the partition. description: A list of the flags that has to be set on the partition.
type: list
state: state:
description: description:
- If to create or delete a partition. If set to C(info) the module will - Whether to create or delete a partition.
only return the device information. - If set to C(info) the module will only return the device information.
choices: ['present', 'absent', 'info'] type: str
choices: [ absent, present, info ]
default: 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: partition_info:
description: Current partition information description: Current partition information
returned: success returned: success
@ -142,46 +146,47 @@ partition_info:
} }
''' '''
EXAMPLES = """ EXAMPLES = r'''
# Create a new primary partition - name: Create a new primary partition
- parted: parted:
device: /dev/sdb device: /dev/sdb
number: 1 number: 1
state: present state: present
# Remove partition number 1 - name: Remove partition number 1
- parted: parted:
device: /dev/sdb device: /dev/sdb
number: 1 number: 1
state: absent state: absent
# Create a new primary partition with a size of 1GiB - name: Create a new primary partition with a size of 1GiB
- parted: parted:
device: /dev/sdb device: /dev/sdb
number: 1 number: 1
state: present state: present
part_end: 1GiB part_end: 1GiB
# Create a new primary partition for LVM - name: Create a new primary partition for LVM
- parted: parted:
device: /dev/sdb device: /dev/sdb
number: 2 number: 2
flags: [ lvm ] flags: [ lvm ]
state: present state: present
part_start: 1GiB part_start: 1GiB
# Read device information (always use unit when probing) # Example on how to read info and reuse it in subsequent task
- parted: device=/dev/sdb unit=MiB - name: Read device information (always use unit when probing)
parted: device=/dev/sdb unit=MiB
register: sdb_info register: sdb_info
# Remove all partitions from disk - name: Remove all partitions from disk
- parted: parted:
device: /dev/sdb device: /dev/sdb
number: "{{ item.num }}" number: '{{ item.num }}'
state: absent state: absent
with_items: with_items:
- "{{ sdb_info.partitions }}" - '{{ sdb_info.partitions }}'
""" '''
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule
@ -192,7 +197,7 @@ import os
# Reference prefixes (International System of Units and IEC) # Reference prefixes (International System of Units and IEC)
units_si = ['B', 'KB', 'MB', 'GB', 'TB'] 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'] parted_units = units_si + units_iec + ['s', '%', 'cyl', 'chs', 'compact']
@ -531,54 +536,31 @@ def main():
output_script = "" output_script = ""
script = "" script = ""
module = AnsibleModule( module = AnsibleModule(
argument_spec={ argument_spec=dict(
'device': {'required': True, 'type': 'str'}, device=dict(type='str', required=True),
'align': { align=dict(type='str', default='optimal', choices=['cylinder', 'minimal', 'none', 'optimal']),
'default': 'optimal', number=dict(type='int'),
'choices': ['none', 'cylinder', 'minimal', 'optimal'],
'type': 'str'
},
'number': {'default': None, 'type': 'int'},
# unit <unit> command # unit <unit> command
'unit': { unit=dict(type='str', default='KiB', choices=parted_units),
'default': 'KiB',
'choices': parted_units,
'type': 'str'
},
# mklabel <label-type> command # mklabel <label-type> command
'label': { label=dict(type='str', default='msdos', choices=['aix', 'amiga', 'bsd', 'dvh', 'gpt', 'loop', 'mac', 'msdos', 'pc98', 'sun']),
'default': 'msdos',
'choices': [
'aix', 'amiga', 'bsd', 'dvh', 'gpt', 'loop', 'mac', 'msdos',
'pc98', 'sun'
],
'type': 'str'
},
# mkpart <part-type> [<fs-type>] <start> <end> command # mkpart <part-type> [<fs-type>] <start> <end> command
'part_type': { part_type=dict(type='str', default='primary', choices=['extended', 'logical', 'primary']),
'default': 'primary', part_start=dict(type='str', default='0%'),
'choices': ['primary', 'extended', 'logical'], part_end=dict(type='str', default='100%'),
'type': 'str'
},
'part_start': {'default': '0%', 'type': 'str'},
'part_end': {'default': '100%', 'type': 'str'},
# name <partition> <name> command # name <partition> <name> command
'name': {'type': 'str'}, name=dict(type='str'),
# set <partition> <flag> <state> command # set <partition> <flag> <state> command
'flags': {'type': 'list'}, flags=dict(type='list'),
# rm/mkpart command # rm/mkpart command
'state': { state=dict(type='str', default='info', choices=['absent', 'info', 'present']),
'choices': ['present', 'absent', 'info'], ),
'default': 'info',
'type': 'str'
}
},
required_if=[ required_if=[
['state', 'present', ['number']], ['state', 'present', ['number']],
['state', 'absent', ['number']], ['state', 'absent', ['number']],

4
lib/ansible/modules/system/ping.py
View file

@ -25,14 +25,12 @@ description:
- This is NOT ICMP ping, this is just a trivial test module that requires Python on the remote-node. - 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 Windows targets, use the M(win_ping) module instead.
- For Network targets, use the M(net_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: options:
data: data:
description: description:
- Data to return for the C(ping) return value. - Data to return for the C(ping) return value.
- If this parameter is set to C(crash), the module will cause an exception. - If this parameter is set to C(crash), the module will cause an exception.
type: str
default: pong default: pong
seealso: seealso:
- module: net_ping - module: net_ping

15
lib/ansible/modules/system/reboot.py
View file

@ -14,7 +14,8 @@ DOCUMENTATION = r'''
module: reboot module: reboot
short_description: Reboot a machine short_description: Reboot a machine
description: 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" version_added: "2.7"
options: options:
pre_reboot_delay: pre_reboot_delay:
@ -22,21 +23,21 @@ options:
- Seconds for shutdown to wait before requesting reboot. - 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 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. - On Solaris and FreeBSD, this will be seconds.
default: 0
type: int type: int
default: 0
post_reboot_delay: post_reboot_delay:
description: description:
- Seconds to wait after the reboot was successful and the connection was re-established. - 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. - This is useful if you want wait for something to settle despite your connection already working.
default: 0
type: int type: int
default: 0
reboot_timeout: reboot_timeout:
description: description:
- Maximum seconds to wait for machine to reboot and respond to a test command. - 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 - 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. maximum execution time for the module is twice this amount.
default: 600
type: int type: int
default: 600
connect_timeout: connect_timeout:
description: description:
- Maximum seconds to wait for a successful connection to the managed hosts before trying again. - Maximum seconds to wait for a successful connection to the managed hosts before trying again.
@ -46,15 +47,13 @@ options:
description: description:
- Command to run on the rebooted host and expect success from to determine the machine is ready for - Command to run on the rebooted host and expect success from to determine the machine is ready for
further tasks. further tasks.
default: whoami
type: str type: str
default: whoami
msg: msg:
description: description:
- Message to display to users before reboot. - Message to display to users before reboot.
default: Reboot initiated by Ansible
type: str type: str
notes: default: Reboot initiated by Ansible
- For Windows targets, use the M(win_reboot) module instead.
seealso: seealso:
- module: win_reboot - module: win_reboot
author: author:

44
lib/ansible/modules/system/service.py
View file

@ -11,7 +11,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['stableinterface'], 'status': ['stableinterface'],
'supported_by': 'core'} 'supported_by': 'core'}
DOCUMENTATION = ''' DOCUMENTATION = r'''
--- ---
module: service module: service
version_added: "0.1" version_added: "0.1"
@ -24,52 +24,60 @@ options:
name: name:
description: description:
- Name of the service. - Name of the service.
type: str
required: true required: true
state: state:
description: description:
- C(started)/C(stopped) are idempotent actions that will not run - C(started)/C(stopped) are idempotent actions that will not run
commands unless necessary. C(restarted) will always bounce the commands unless necessary.
service. C(reloaded) will always reload. B(At least one of state - C(restarted) will always bounce the service.
and enabled are required.) Note that reloaded will start the - C(reloaded) will always reload.
service if it is not already started, even if your chosen init - B(At least one of state and enabled are required.)
system wouldn't normally. - 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 ] choices: [ reloaded, restarted, started, stopped ]
sleep: sleep:
description: description:
- If the service is being C(restarted) then sleep this many seconds - If the service is being C(restarted) then sleep this many seconds
between the stop and start command. This helps to workaround badly between the stop and start command.
behaving init scripts that exit immediately after signaling a process - This helps to work around badly-behaving init scripts that exit immediately
to stop. after signaling a process to stop.
type: int
version_added: "1.3" version_added: "1.3"
pattern: pattern:
description: description:
- If the service does not respond to the status command, name a - 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) 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, command as a stand-in for a status result.
the service will be assumed to be started. - If the string is found, the service will be assumed to be started.
type: str
version_added: "0.7" version_added: "0.7"
enabled: enabled:
description: description:
- Whether the service should start on boot. B(At least one of state and - Whether the service should start on boot.
enabled are required.) - B(At least one of state and enabled are required.)
type: bool type: bool
runlevel: runlevel:
description: 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 default: default
arguments: arguments:
description: description:
- Additional arguments provided on the command line - Additional arguments provided on the command line.
type: str
aliases: [ args ] aliases: [ args ]
use: use:
description: description:
- The service module actually uses system specific modules, normally through auto detection, this setting can force a specific module. - 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. - 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 default: auto
version_added: 2.2 version_added: 2.2
notes: notes:
- For AIX group subsystem names can be used. - For AIX, group subsystem names can be used.
- For Windows targets, use the M(win_service) module instead.
seealso: seealso:
- module: win_service - module: win_service
author: author:
@ -77,7 +85,7 @@ author:
- Michael DeHaan - Michael DeHaan
''' '''
EXAMPLES = ''' EXAMPLES = r'''
- name: Start service httpd, if not started - name: Start service httpd, if not started
service: service:
name: httpd name: httpd

8
lib/ansible/modules/system/svc.py
View file

@ -24,6 +24,7 @@ options:
name: name:
description: description:
- Name of the service to manage. - Name of the service to manage.
type: str
required: true required: true
state: state:
description: description:
@ -33,13 +34,14 @@ options:
C(reloaded) will send a sigusr1 (svc -1). C(reloaded) will send a sigusr1 (svc -1).
C(once) will run a normally downed svc once (svc -o), not really C(once) will run a normally downed svc once (svc -o), not really
an idempotent operation. an idempotent operation.
type: str
choices: [ killed, once, reloaded, restarted, started, stopped ] choices: [ killed, once, reloaded, restarted, started, stopped ]
downed: downed:
description: description:
- Should a 'down' file exist or not, if it exists it disables auto startup. - Should a 'down' file exist or not, if it exists it disables auto startup.
Defaults to no. Downed does not imply stopped. Defaults to no. Downed does not imply stopped.
type: bool type: bool
default: 'no' default: no
enabled: enabled:
description: description:
- Whether the service is enabled or not, if disabled it also implies stopped. - Whether the service is enabled or not, if disabled it also implies stopped.
@ -48,10 +50,13 @@ options:
service_dir: service_dir:
description: description:
- Directory svscan watches for services - Directory svscan watches for services
type: path
default: /service default: /service
service_src: service_src:
description: description:
- Directory where services are defined, the source of symlinks to service_dir. - Directory where services are defined, the source of symlinks to service_dir.
type: path
default: /etc/service
''' '''
EXAMPLES = ''' EXAMPLES = '''
@ -247,7 +252,6 @@ def main():
state=dict(type='str', choices=['killed', 'once', 'reloaded', 'restarted', 'started', 'stopped']), state=dict(type='str', choices=['killed', 'once', 'reloaded', 'restarted', 'started', 'stopped']),
enabled=dict(type='bool'), enabled=dict(type='bool'),
downed=dict(type='bool'), downed=dict(type='bool'),
dist=dict(type='str', default='daemontools'),
service_dir=dict(type='str', default='/service'), service_dir=dict(type='str', default='/service'),
service_src=dict(type='str', default='/etc/service'), service_src=dict(type='str', default='/etc/service'),
), ),

28
lib/ansible/modules/system/timezone.py
View file

@ -11,7 +11,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'], 'status': ['preview'],
'supported_by': 'community'} 'supported_by': 'community'}
DOCUMENTATION = ''' DOCUMENTATION = r'''
--- ---
module: timezone module: timezone
short_description: Configure timezone setting short_description: Configure timezone setting
@ -21,26 +21,28 @@ description:
- Several different tools are used depending on the OS/Distribution involved. - 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). 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. 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 Ansible 2.3 support was added for SmartOS and BSDs.
- As of version 2.4 support was added for macOS. - 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. - 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" version_added: "2.2"
options: options:
name: name:
description: description:
- Name of the timezone for the system clock. - Name of the timezone for the system clock.
Default is to keep current setting. B(At least one of name and - Default is to keep current setting.
hwclock are required.) - B(At least one of name and hwclock are required.)
type: str
hwclock: hwclock:
description: description:
- Whether the hardware clock is in UTC or in local timezone. - Whether the hardware clock is in UTC or in local timezone.
Default is to keep current setting. - Default is to keep current setting.
Note that this option is recommended not to change and may fail - Note that this option is recommended not to change and may fail
to configure, especially on virtual environments such as AWS. to configure, especially on virtual environments such as AWS.
B(At least one of name and hwclock are required.) - B(At least one of name and hwclock are required.)
I(Only used on Linux.) - I(Only used on Linux.)
type: str
aliases: [ rtc ] aliases: [ rtc ]
choices: [ "UTC", "local" ] choices: [ local, UTC ]
notes: notes:
- On SmartOS the C(sm-set-timezone) utility (part of the smtools package) is required to set the zone timezone - On SmartOS the C(sm-set-timezone) utility (part of the smtools package) is required to set the zone timezone
author: author:
@ -49,7 +51,7 @@ author:
- Indrajit Raychaudhuri (@indrajitr) - Indrajit Raychaudhuri (@indrajitr)
''' '''
RETURN = ''' RETURN = r'''
diff: diff:
description: The differences about the given arguments. description: The differences about the given arguments.
returned: success returned: success
@ -63,8 +65,8 @@ diff:
type: dict type: dict
''' '''
EXAMPLES = ''' EXAMPLES = r'''
- name: set timezone to Asia/Tokyo - name: Set timezone to Asia/Tokyo
timezone: timezone:
name: Asia/Tokyo name: Asia/Tokyo
''' '''

434
lib/ansible/modules/system/user.py
View file

@ -13,15 +13,235 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
DOCUMENTATION = ''' DOCUMENTATION = '''
module: user module: user
author:
- Stephen Fromm (@sfromm)
version_added: "0.2" version_added: "0.2"
short_description: Manage user accounts 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: notes:
- There are specific requirements per platform on user management utilities. However - There are specific requirements per platform on user management utilities. However
they generally come pre-installed with the system and Ansible will require they 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. 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 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 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 - 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. 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 - On all other platforms, this module uses C(useradd) to create, C(usermod) to modify, and
C(userdel) to remove accounts. C(userdel) to remove accounts.
description: seealso:
- Manage user accounts and user attributes. - module: authorized_key
- For Windows targets, use the M(win_user) module instead. - module: group
options: - module: win_user
name: author:
description: - Stephen Fromm (@sfromm)
- 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"
''' '''
EXAMPLES = ''' EXAMPLES = '''
@ -268,7 +294,7 @@ EXAMPLES = '''
groups: developers groups: developers
expires: 1422403387 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: user:
name: james18 name: james18
expires: -1 expires: -1

118
lib/ansible/modules/system/vdo.py
View file

@ -16,10 +16,10 @@ ANSIBLE_METADATA = {
'supported_by': 'community' 'supported_by': 'community'
} }
DOCUMENTATION = ''' DOCUMENTATION = r'''
--- ---
author: author:
- "Bryan Gurney (@bgurney-rh)" - Bryan Gurney (@bgurney-rh)
module: vdo module: vdo
@ -29,7 +29,7 @@ version_added: "2.5"
description: description:
- This module controls the VDO dedupe and compression device. - 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 provides inline block-level deduplication, compression, and
thin provisioning capabilities to primary storage. thin provisioning capabilities to primary storage.
@ -37,9 +37,9 @@ options:
name: name:
description: description:
- The name of the VDO volume. - The name of the VDO volume.
type: str
required: true required: true
state: state:
choices: [ "present", "absent" ]
description: description:
- Whether this VDO volume should be "present" or "absent". - Whether this VDO volume should be "present" or "absent".
If a "present" VDO volume does not exist, it will be 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 parameters that can be modified after creation. If an
"absent" VDO volume does not exist, it will not be "absent" VDO volume does not exist, it will not be
removed. removed.
type: str
required: true required: true
choices: [ absent, present ]
default: present
activated: activated:
choices: [ "yes", "no" ]
description: description:
- The "activate" status for a VDO volume. If this is set - The "activate" status for a VDO volume. If this is set
to "no", the VDO volume cannot be started, and it will 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 (filesystem, LVM headers, etc.) to the VDO volume prior
to stopping the volume, and leaving it deactivated to stopping the volume, and leaving it deactivated
until ready to use. until ready to use.
type: bool
required: false
running: running:
choices: [ "yes", "no" ]
description: description:
- Whether this VDO volume is running. A VDO volume must - Whether this VDO volume is running.
be activated in order to be started. - A VDO volume must be activated in order to be started.
required: false type: bool
device: device:
description: description:
- The full path of the device to use for VDO storage. - The full path of the device to use for VDO storage.
This is required if "state" is "present". - This is required if "state" is "present".
required: false type: str
logicalsize: logicalsize:
description: description:
- The logical size of the VDO volume (in megabytes, or - 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 than or identical to the current size. If the specified
size is larger than the current size, a growlogical size is larger than the current size, a growlogical
operation will be performed. operation will be performed.
required: false type: str
deduplication: deduplication:
choices: [ "enabled", "disabled" ]
description: description:
- Configures whether deduplication is enabled. The - Configures whether deduplication is enabled. The
default for a created volume is 'enabled'. Existing default for a created volume is 'enabled'. Existing
volumes will maintain their previously configured volumes will maintain their previously configured
setting unless a different value is specified in the setting unless a different value is specified in the
playbook. playbook.
required: false type: str
choices: [ disabled, enabled ]
compression: compression:
choices: [ "enabled", "disabled" ]
description: description:
- Configures whether compression is enabled. The default - Configures whether compression is enabled. The default
for a created volume is 'enabled'. Existing volumes for a created volume is 'enabled'. Existing volumes
will maintain their previously configured setting unless will maintain their previously configured setting unless
a different value is specified in the playbook. a different value is specified in the playbook.
required: false type: str
choices: [ disabled, enabled ]
blockmapcachesize: blockmapcachesize:
description: description:
- The amount of memory allocated for caching block map - The amount of memory allocated for caching block map
@ -120,9 +120,8 @@ options:
volumes will maintain their previously configured volumes will maintain their previously configured
setting unless a different value is specified in the setting unless a different value is specified in the
playbook. playbook.
required: false type: str
readcache: readcache:
choices: [ "enabled", "disabled" ]
description: description:
- Enables or disables the read cache. The default is - Enables or disables the read cache. The default is
'disabled'. Choosing 'enabled' enables a read cache 'disabled'. Choosing 'enabled' enables a read cache
@ -132,7 +131,8 @@ options:
volumes will maintain their previously configured volumes will maintain their previously configured
setting unless a different value is specified in the setting unless a different value is specified in the
playbook. playbook.
required: false type: str
choices: [ disabled, enabled ]
readcachesize: readcachesize:
description: description:
- Specifies the extra VDO device read cache size in - Specifies the extra VDO device read cache size in
@ -146,9 +146,8 @@ options:
Existing volumes will maintain their previously Existing volumes will maintain their previously
configured setting unless a different value is specified configured setting unless a different value is specified
in the playbook. in the playbook.
required: false type: str
emulate512: emulate512:
type: bool
description: description:
- Enables 512-byte emulation mode, allowing drivers or - Enables 512-byte emulation mode, allowing drivers or
filesystems to access the VDO volume at 512-byte filesystems to access the VDO volume at 512-byte
@ -158,16 +157,15 @@ options:
a device. This option is only available when creating a device. This option is only available when creating
a new volume, and cannot be changed for an existing a new volume, and cannot be changed for an existing
volume. volume.
required: false
growphysical:
type: bool type: bool
growphysical:
description: description:
- Specifies whether to attempt to execute a growphysical - Specifies whether to attempt to execute a growphysical
operation, if there is enough unused space on the operation, if there is enough unused space on the
device. A growphysical operation will be executed if device. A growphysical operation will be executed if
there is at least 64 GB of free space, relative to the there is at least 64 GB of free space, relative to the
previous physical size of the affected VDO volume. previous physical size of the affected VDO volume.
required: false type: bool
default: false default: false
slabsize: slabsize:
description: description:
@ -179,9 +177,8 @@ options:
The maximum, 32G, supports a physical size of up to 256T. The maximum, 32G, supports a physical size of up to 256T.
This option is only available when creating a new This option is only available when creating a new
volume, and cannot be changed for an existing volume. volume, and cannot be changed for an existing volume.
required: false type: str
writepolicy: writepolicy:
choices: [ "auto", "sync", "async" ]
description: description:
- Specifies the write policy of the VDO volume. The - Specifies the write policy of the VDO volume. The
'sync' mode acknowledges writes only after data is on 'sync' mode acknowledges writes only after data is on
@ -195,7 +192,8 @@ options:
Existing volumes will maintain their previously Existing volumes will maintain their previously
configured setting unless a different value is configured setting unless a different value is
specified in the playbook. specified in the playbook.
required: false type: str
choices: [ async, auto, sync ]
indexmem: indexmem:
description: description:
- Specifies the amount of index memory in gigabytes. The - 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. and 0.75 can be used, as can any positive integer.
This option is only available when creating a new This option is only available when creating a new
volume, and cannot be changed for an existing volume. volume, and cannot be changed for an existing volume.
required: false type: str
indexmode: indexmode:
description: description:
- Specifies the index mode of the Albireo index. The - Specifies the index mode of the Albireo index. The
@ -215,7 +213,7 @@ options:
100 GB of index data on persistent storage. This option 100 GB of index data on persistent storage. This option
is only available when creating a new volume, and cannot is only available when creating a new volume, and cannot
be changed for an existing volume. be changed for an existing volume.
required: false type: str
ackthreads: ackthreads:
description: description:
- Specifies the number of threads to use for - Specifies the number of threads to use for
@ -225,7 +223,7 @@ options:
1. Existing volumes will maintain their previously 1. Existing volumes will maintain their previously
configured setting unless a different value is specified configured setting unless a different value is specified
in the playbook. in the playbook.
required: false type: str
biothreads: biothreads:
description: description:
- Specifies the number of threads to use for submitting I/O - Specifies the number of threads to use for submitting I/O
@ -235,7 +233,7 @@ options:
Existing volumes will maintain their previously Existing volumes will maintain their previously
configured setting unless a different value is specified configured setting unless a different value is specified
in the playbook. in the playbook.
required: false type: str
cputhreads: cputhreads:
description: description:
- Specifies the number of threads to use for CPU-intensive - Specifies the number of threads to use for CPU-intensive
@ -245,7 +243,7 @@ options:
Existing volumes will maintain their previously Existing volumes will maintain their previously
configured setting unless a different value is specified configured setting unless a different value is specified
in the playbook. in the playbook.
required: false type: str
logicalthreads: logicalthreads:
description: description:
- Specifies the number of threads across which to - Specifies the number of threads across which to
@ -255,7 +253,7 @@ options:
The default is 1. Existing volumes will maintain their The default is 1. Existing volumes will maintain their
previously configured setting unless a different value previously configured setting unless a different value
is specified in the playbook. is specified in the playbook.
required: false type: str
physicalthreads: physicalthreads:
description: description:
- Specifies the number of threads across which to - Specifies the number of threads across which to
@ -267,7 +265,7 @@ options:
is 1. Existing volumes will maintain their previously is 1. Existing volumes will maintain their previously
configured setting unless a different value is specified configured setting unless a different value is specified
in the playbook. in the playbook.
required: false type: str
notes: notes:
- In general, the default thread configuration should be used. - In general, the default thread configuration should be used.
requirements: requirements:
@ -276,8 +274,7 @@ requirements:
- vdo - vdo
''' '''
EXAMPLES = ''' EXAMPLES = r'''
# Create a VDO volume
- name: Create 2 TB VDO volume vdo1 on device /dev/md0 - name: Create 2 TB VDO volume vdo1 on device /dev/md0
vdo: vdo:
name: vdo1 name: vdo1
@ -285,14 +282,13 @@ EXAMPLES = '''
device: /dev/md0 device: /dev/md0
logicalsize: 2T logicalsize: 2T
# Remove a VDO volume
- name: Remove VDO volume vdo1 - name: Remove VDO volume vdo1
vdo: vdo:
name: vdo1 name: vdo1
state: absent state: absent
''' '''
RETURN = '''# ''' RETURN = r'''# '''
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule
import re import re
@ -453,35 +449,35 @@ def run_module():
# Creation param defaults are determined by the creation section. # Creation param defaults are determined by the creation section.
module_args = dict( module_args = dict(
name=dict(required=True), name=dict(type='str', required=True),
state=dict(choices=['absent', 'present'], default='present'), state=dict(type='str', default='present', choices=['absent', 'present']),
activated=dict(choices=['yes', 'no']), activated=dict(type='bool'),
running=dict(choices=['yes', 'no']), running=dict(type='bool'),
growphysical=dict(type='bool', default=False), growphysical=dict(type='bool', default=False),
device=dict(), device=dict(type='str'),
logicalsize=dict(), logicalsize=dict(type='str'),
deduplication=dict(choices=['enabled', 'disabled']), deduplication=dict(type='str', choices=['disabled', 'enabled']),
compression=dict(choices=['enabled', 'disabled']), compression=dict(type='str', choices=['disabled', 'enabled']),
blockmapcachesize=dict(type='str'), blockmapcachesize=dict(type='str'),
readcache=dict(choices=['enabled', 'disabled']), readcache=dict(type='str', choices=['disabled', 'enabled']),
readcachesize=dict(), readcachesize=dict(type='str'),
emulate512=dict(type='bool', default=False), emulate512=dict(type='bool', default=False),
slabsize=dict(), slabsize=dict(type='str'),
writepolicy=dict(choices=['auto', 'sync', 'async']), writepolicy=dict(type='str', choices=['async', 'auto', 'sync']),
indexmem=dict(), indexmem=dict(type='str'),
indexmode=dict(choices=['dense', 'sparse']), indexmode=dict(type='str', choices=['dense', 'sparse']),
ackthreads=dict(), ackthreads=dict(type='str'),
biothreads=dict(), biothreads=dict(type='str'),
cputhreads=dict(), cputhreads=dict(type='str'),
logicalthreads=dict(), logicalthreads=dict(type='str'),
physicalthreads=dict() physicalthreads=dict(type='str')
) )
# Seed the result dictionary in the object. There will be an # Seed the result dictionary in the object. There will be an
# 'invocation' dictionary added with 'module_args' (arguments # 'invocation' dictionary added with 'module_args' (arguments
# given). # given).
result = dict( result = dict(
changed=False changed=False,
) )
# the AnsibleModule object will be our abstraction working with Ansible # the AnsibleModule object will be our abstraction working with Ansible
@ -490,7 +486,7 @@ def run_module():
# supports check mode # supports check mode
module = AnsibleModule( module = AnsibleModule(
argument_spec=module_args, argument_spec=module_args,
supports_check_mode=False supports_check_mode=False,
) )
if not HAS_YAML: if not HAS_YAML:

9
test/sanity/validate-modules/ignore.txt
View file

@ -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_schema.py E322
lib/ansible/modules/database/vertica/vertica_user.py E322 lib/ansible/modules/database/vertica/vertica_user.py E322
lib/ansible/modules/files/assemble.py E323 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 E324
lib/ansible/modules/files/blockinfile.py E326 lib/ansible/modules/files/blockinfile.py E326
lib/ansible/modules/files/copy.py E322 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/storage/zfs/zpool_facts.py E323
lib/ansible/modules/system/aix_inittab.py E324 lib/ansible/modules/system/aix_inittab.py E324
lib/ansible/modules/system/aix_inittab.py E326 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/capabilities.py E322
lib/ansible/modules/system/cron.py E324 lib/ansible/modules/system/cron.py E324
lib/ansible/modules/system/cronvar.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/osx_defaults.py E324
lib/ansible/modules/system/pamd.py E324 lib/ansible/modules/system/pamd.py E324
lib/ansible/modules/system/pamd.py E326 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 E322
lib/ansible/modules/system/puppet.py E325 lib/ansible/modules/system/puppet.py E325
lib/ansible/modules/system/runit.py E322 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/service.py E210
lib/ansible/modules/system/systemd.py E324 lib/ansible/modules/system/systemd.py E324
lib/ansible/modules/system/solaris_zone.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 E322
lib/ansible/modules/system/ufw.py E326 lib/ansible/modules/system/ufw.py E326
lib/ansible/modules/system/user.py E210 lib/ansible/modules/system/user.py E210
lib/ansible/modules/system/user.py E324 lib/ansible/modules/system/user.py E324
lib/ansible/modules/system/user.py E327 lib/ansible/modules/system/user.py E327
lib/ansible/modules/system/vdo.py E324
lib/ansible/modules/system/vdo.py E326 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_credential.py E326
lib/ansible/modules/web_infrastructure/ansible_tower/tower_group.py E324 lib/ansible/modules/web_infrastructure/ansible_tower/tower_group.py E324