ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-08-22 14:01:42 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

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
commit 30227ace98
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
43 changed files with 1222 additions and 1065 deletions
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:
description:
- The full path of the file or object.
aliases: [ name ]
type: path
required: yes
aliases: [ name ]
state:
description:
- Define whether the ACL should be present or not.
@ -72,7 +73,7 @@ options:
version_added: '2.0'
use_nfsv4_acls:
description:
- Use NFSv4 ACLs instead of POSIX ACLs.
- Use NFSv4 ACLs instead of POSIX ACLs.
type: bool
default: no
version_added: '2.2'
@ -259,31 +260,28 @@ def run_acl(module, cmd, check_rc=True):
def main():
module = AnsibleModule(
argument_spec=dict(
path=dict(required=True, aliases=['name'], type='path'),
entry=dict(required=False, type='str'),
entity=dict(required=False, type='str', default=''),
path=dict(type='path', required=True, aliases=['name']),
entry=dict(type='str'),
entity=dict(type='str', default=''),
etype=dict(
required=False,
choices=['other', 'user', 'group', 'mask'],
type='str'
type='str',
choices=['group', 'mask', 'other', 'user'],
),
permissions=dict(required=False, type='str'),
permissions=dict(type='str'),
state=dict(
required=False,
type='str',
default='query',
choices=['query', 'present', 'absent'],
type='str'
choices=['absent', 'present', 'query'],
),
follow=dict(required=False, type='bool', default=True),
default=dict(required=False, type='bool', default=False),
recursive=dict(required=False, type='bool', default=False),
follow=dict(type='bool', default=True),
default=dict(type='bool', default=False),
recursive=dict(type='bool', default=False),
recalculate_mask=dict(
required=False,
type='str',
default='default',
choices=['default', 'mask', 'no_mask'],
type='str'
),
use_nfsv4_acls=dict(required=False, type='bool', default=False)
use_nfsv4_acls=dict(type='bool', default=False)
),
supports_check_mode=True,
)

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

@ -13,49 +13,57 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'community'}
DOCUMENTATION = '''
DOCUMENTATION = r'''
---
module: archive
version_added: '2.3'
short_description: Creates a compressed archive of one or more files or trees
extends_documentation_fragment: files
description:
- Packs an archive. It is the opposite of M(unarchive). By default, it assumes the compression source exists on the target. It will not copy the
source file from the local system to the target before archiving. Source files can be deleted after archival by specifying I(remove=True).
- Packs an archive.
- It is the opposite of M(unarchive).
- By default, it assumes the compression source exists on the target.
- It will not copy the source file from the local system to the target before archiving.
- Source files can be deleted after archival by specifying I(remove=True).
options:
path:
description:
- Remote absolute path, glob, or list of paths or globs for the file or files to compress or archive.
type: list
required: true
format:
description:
- The type of compression to use.
- Support for xz was added in version 2.5.
- Support for xz was added in Ansible 2.5.
type: str
choices: [ bz2, gz, tar, xz, zip ]
default: gz
dest:
description:
- The file name of the destination archive. This is required when C(path) refers to multiple files by either specifying a glob, a directory or
multiple paths in a list.
- The file name of the destination archive.
- This is required when C(path) refers to multiple files by either specifying a glob, a directory or multiple paths in a list.
type: path
exclude_path:
version_added: '2.4'
description:
- Remote absolute path, glob, or list of paths or globs for the file or files to exclude from the archive
- Remote absolute path, glob, or list of paths or globs for the file or files to exclude from the archive.
type: str
version_added: '2.4'
remove:
description:
- Remove any added source files and trees after adding to archive.
type: bool
default: 'no'
default: no
notes:
- Requires tarfile, zipfile, gzip and bzip2 packages on target host.
- Requires lzma or backports.lzma if using xz format.
- Can produce I(gzip), I(bzip2), I(lzma) and I(zip) compressed files or archives.
seealso:
- module: unarchive
author:
- Ben Doherty (@bendoh)
notes:
- requires tarfile, zipfile, gzip and bzip2 packages on target host
- requires lzma or backports.lzma if using xz format
- can produce I(gzip), I(bzip2), I(lzma) and I(zip) compressed files or archives
'''
EXAMPLES = '''
EXAMPLES = r'''
- name: Compress directory /path/to/foo/ into /path/to/foo.tgz
archive:
path: /path/to/foo
@ -99,7 +107,7 @@ EXAMPLES = '''
format: bz2
'''
RETURN = '''
RETURN = r'''
state:
description:
The current state of the archived file.

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

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

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

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

@ -19,8 +19,6 @@ version_added: historical
short_description: Copy files to remote locations
description:
- The C(copy) module copies a file from the local or remote machine to a location on the remote machine.
- Use the M(fetch) module to copy files from remote locations to the local box.
- If you need variable interpolation in copied files, use the M(template) module.
- For Windows targets, use the M(win_copy) module instead.
options:
src:
@ -31,10 +29,12 @@ options:
with "/", only inside contents of that directory are copied to destination.
Otherwise, if it does not end with "/", the directory itself with all contents
is copied. This behavior is similar to the C(rsync) command line tool.
type: path
content:
description:
- When used instead of I(src), sets the contents of a file directly to the specified value.
- For anything advanced or with formatting also look at the template module.
type: str
version_added: '1.1'
dest:
description:
@ -42,6 +42,7 @@ options:
- If I(src) is a directory, this must be a directory too.
- If I(dest) is a non-existent path and if either I(dest) ends with "/" or I(src) is a directory, I(dest) is created.
- If I(src) and I(dest) are files, the parent directory of I(dest) is not created and the task fails if it does not already exist.
type: path
required: yes
backup:
description:
@ -69,19 +70,21 @@ options:
- As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or C(u=rw,g=r,o=r)).
- As of Ansible 2.3, the mode may also be the special string C(preserve).
- C(preserve) means that the file will be given the same permissions as the source file.
type: path
directory_mode:
description:
- When doing a recursive copy set the mode for the directories.
- If this is not set we will use the system defaults.
- The mode is only set on directories which are newly created, and will not affect those that already existed.
type: raw
version_added: '1.5'
remote_src:
description:
- Influence whether I(src) needs to be transferred or already is present remotely.
- If C(no), it will search for I(src) at originating/master machine.
- If C(yes) it will go to the remote/target machine for the I(src).
- I(remote_src) supports recursive copying as of version 2.8.
- I(remote_src) only works with C(mode=preserve) as of version 2.6.
- I(remote_src) supports recursive copying as of Ansible 2.8.
- I(remote_src) only works with C(mode=preserve) as of Ansible 2.6.
type: bool
default: no
version_added: '2.0'
@ -102,6 +105,7 @@ options:
- SHA1 checksum of the file being transferred.
- Used to validate that the copy of the file was successful.
- If this is not provided, ansible will use the local calculated checksum of the src file.
type: str
version_added: '2.5'
extends_documentation_fragment:
- decrypt
@ -109,12 +113,11 @@ extends_documentation_fragment:
- validate
notes:
- The M(copy) module recursively copy facility does not scale to lots (>hundreds) of files.
- For alternative, see M(synchronize) module, which is a wrapper around the C(rsync) command line tool.
- For Windows targets, use the M(win_copy) module instead.
seealso:
- module: assemble
- module: fetch
- module: file
- module: synchronize
- module: template
- module: win_copy
author:
@ -129,7 +132,7 @@ EXAMPLES = r'''
dest: /etc/foo.conf
owner: foo
group: foo
mode: 0644
mode: '0644'
- name: Copy file with owner and permission, using symbolic representation
copy:
@ -153,7 +156,7 @@ EXAMPLES = r'''
dest: /etc/ntp.conf
owner: root
group: root
mode: 0644
mode: '0644'
backup: yes
- name: Copy a new "sudoers" file into place, after passing validation with visudo
@ -174,17 +177,17 @@ EXAMPLES = r'''
content: '# This file was moved to /etc/other.conf'
dest: /etc/mine.conf
- name: if follow is true, /path/to/file will be overwritten by contents of foo.conf
- name: If follow=yes, /path/to/file will be overwritten by contents of foo.conf
copy:
src: /etc/foo.conf
dest: /path/to/link # /path/to/link is link to /path/to/file
follow: True
dest: /path/to/link # link to /path/to/file
follow: yes
- name: if follow is False, /path/to/link will become a file and be overwritten by contents of foo.conf
- name: If follow=no, /path/to/link will become a file and be overwritten by contents of foo.conf
copy:
src: /etc/foo.conf
dest: /path/to/link # /path/to/link is link to /path/to/file
follow: False
dest: /path/to/link # link to /path/to/file
follow: no
'''
RETURN = r'''
@ -473,7 +476,7 @@ def main():
directory_mode=dict(type='raw'),
remote_src=dict(type='bool'),
local_follow=dict(type='bool'),
checksum=dict(),
checksum=dict(type='str'),
),
add_file_common_args=True,
supports_check_mode=True,

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@ -12,70 +12,82 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'core'}
DOCUMENTATION = '''
DOCUMENTATION = r'''
---
module: synchronize
version_added: "1.4"
short_description: A wrapper around rsync to make common tasks in your playbooks quick and easy.
short_description: A wrapper around rsync to make common tasks in your playbooks quick and easy
description:
- C(synchronize) is a wrapper around rsync to make common tasks in your playbooks quick and easy. It is run and originates on the local host where
Ansible is being run. Of course, you could just use the C(command) action to call rsync yourself, but you also have to add a fair number of
boilerplate options and host facts. C(synchronize) is not intended to provide access to the full power of rsync, but does make the most common
- C(synchronize) is a wrapper around rsync to make common tasks in your playbooks quick and easy.
- It is run and originates on the local host where Ansible is being run.
- Of course, you could just use the C(command) action to call rsync yourself, but you also have to add a fair number of
boilerplate options and host facts.
- This module is not intended to provide access to the full power of rsync, but does make the most common
invocations easier to implement. You `still` may need to call rsync directly via C(command) or C(shell) depending on your use case.
options:
src:
description:
- Path on the source host that will be synchronized to the destination; The path can be absolute or relative.
- Path on the source host that will be synchronized to the destination.
- The path can be absolute or relative.
type: str
required: true
dest:
description:
- Path on the destination host that will be synchronized from the source; The path can be absolute or relative.
- Path on the destination host that will be synchronized from the source.
- The path can be absolute or relative.
type: str
required: true
dest_port:
description:
- Port number for ssh on the destination host. Prior to ansible 2.0, the ansible_ssh_port inventory var took precedence over this value.
- Port number for ssh on the destination host.
- Prior to Ansible 2.0, the ansible_ssh_port inventory var took precedence over this value.
type: int
default: Value of ansible_ssh_port for this host, remote_port config setting, or the value from ssh client configuration if none of those are set
version_added: "1.5"
mode:
description:
- Specify the direction of the synchronization. In push mode the localhost or delegate is the source; In pull mode the remote host in context
is the source.
- Specify the direction of the synchronization.
- In push mode the localhost or delegate is the source.
- In pull mode the remote host in context is the source.
type: str
choices: [ pull, push ]
default: push
archive:
description:
- Mirrors the rsync archive flag, enables recursive, links, perms, times, owner, group flags and -D.
type: bool
default: 'yes'
default: yes
checksum:
description:
- Skip based on checksum, rather than mod-time & size; Note that that "archive" option is still enabled by default - the "checksum" option will
not disable it.
type: bool
default: 'no'
default: no
version_added: "1.6"
compress:
description:
- Compress file data during the transfer. In most cases, leave this enabled unless it causes problems.
- Compress file data during the transfer.
- In most cases, leave this enabled unless it causes problems.
type: bool
default: 'yes'
default: yes
version_added: "1.7"
existing_only:
description:
- Skip creating new files on receiver.
type: bool
default: 'no'
default: no
version_added: "1.5"
delete:
description:
- Delete files in C(dest) that don't exist (after transfer, not before) in the C(src) path. This option requires C(recursive=yes).
- Delete files in C(dest) that don't exist (after transfer, not before) in the C(src) path.
- This option requires C(recursive=yes).
type: bool
default: 'no'
default: no
dirs:
description:
- Transfer directories without recursing
- Transfer directories without recursing.
type: bool
default: 'no'
default: no
recursive:
description:
- Recurse into directories.
@ -90,7 +102,7 @@ options:
description:
- Copy symlinks as the item that they point to (the referent) is copied, rather than the symlink.
type: bool
default: 'no'
default: no
perms:
description:
- Preserve permissions.
@ -98,66 +110,72 @@ options:
default: the value of the archive option
times:
description:
- Preserve modification times
- Preserve modification times.
type: bool
default: the value of the archive option
owner:
description:
- Preserve owner (super user only)
- Preserve owner (super user only).
type: bool
default: the value of the archive option
group:
description:
- Preserve group
- Preserve group.
type: bool
default: the value of the archive option
rsync_path:
description:
- Specify the rsync command to run on the remote host. See C(--rsync-path) on the rsync man page.
- To specify the rsync command to run on the local host, you need to set this your task var C(ansible_rsync_path).
type: path
rsync_timeout:
description:
- Specify a C(--timeout) for the rsync command in seconds.
type: int
default: 0
set_remote_user:
description:
- put user@ for the remote paths. If you have a custom ssh config to define the remote user for a host
that does not match the inventory user, you should set this parameter to "no".
- Put user@ for the remote paths.
- If you have a custom ssh config to define the remote user for a host
that does not match the inventory user, you should set this parameter to C(no).
type: bool
default: yes
use_ssh_args:
description:
- Use the ssh_args specified in ansible.cfg
- Use the ssh_args specified in ansible.cfg.
type: bool
default: 'no'
default: no
version_added: "2.0"
rsync_opts:
description:
- Specify additional rsync options by passing in an array. Note that an empty string in
C(rsync_opts) will end up transfer the current working directory.
- Specify additional rsync options by passing in an array.
- Note that an empty string in C(rsync_opts) will end up transfer the current working directory.
type: str
default:
version_added: "1.6"
partial:
description:
- Tells rsync to keep the partial file which should make a subsequent transfer of the rest of the file much faster.
type: bool
default: 'no'
default: no
version_added: "2.0"
verify_host:
description:
- Verify destination host key.
type: bool
default: 'no'
default: no
version_added: "2.0"
private_key:
description:
- Specify the private key to use for SSH-based rsync connections (e.g. C(~/.ssh/id_rsa))
- Specify the private key to use for SSH-based rsync connections (e.g. C(~/.ssh/id_rsa)).
type: path
version_added: "1.6"
link_dest:
description:
- add a destination to hard link against during the rsync.
- Add a destination to hard link against during the rsync.
type: str
default:
version_added: "2.5"
notes:
- rsync must be installed on both the local and remote host.
- For the C(synchronize) module, the "local host" is the host `the synchronize task originates on`, and the "destination host" is the host
@ -168,19 +186,16 @@ notes:
The user and permissions for the synchronize `src` are those of the user running the Ansible task on the local host (or the remote_user for a
delegate_to host when delegate_to is used).
- The user and permissions for the synchronize `dest` are those of the `remote_user` on the destination host or the `become_user` if `become=yes` is active.
- In 2.0.0.0 a bug in the synchronize module made become occur on the "local host". This was fixed in 2.0.1.
- In Ansible 2.0 a bug in the synchronize module made become occur on the "local host". This was fixed in Ansible 2.0.1.
- Currently, synchronize is limited to elevating permissions via passwordless sudo. This is because rsync itself is connecting to the remote machine
and rsync doesn't give us a way to pass sudo credentials in.
- Currently there are only a few connection types which support synchronize (ssh, paramiko, local, and docker) because a sync strategy has been
determined for those connection types. Note that the connection for these must not need a password as rsync itself is making the connection and
rsync does not provide us a way to pass a password to the connection.
- Expect that dest=~/x will be ~<remote_user>/x even if using sudo.
- Inspect the verbose output to validate the destination user/host/path
are what was expected.
- To exclude files and directories from being synchronized, you may add
C(.rsync-filter) files to the source directory.
- rsync daemon must be up and running with correct permission when using
rsync protocol in source or destination path.
- Inspect the verbose output to validate the destination user/host/path are what was expected.
- To exclude files and directories from being synchronized, you may add C(.rsync-filter) files to the source directory.
- rsync daemon must be up and running with correct permission when using rsync protocol in source or destination path.
- The C(synchronize) module forces `--delay-updates` to avoid leaving a destination in a broken in-between state if the underlying rsync process
encounters an error. Those synchronizing large numbers of files that are willing to trade safety for performance should call rsync directly.
- link_destination is subject to the same limitations as the underlaying rsync daemon. Hard links are only preserved if the relative subtrees
@ -284,7 +299,7 @@ EXAMPLES = '''
synchronize:
src: some/relative/path
dest: /some/absolute/path
rsync_path: "su -c rsync"
rsync_path: su -c rsync
# Example .rsync-filter file in the source directory
# - var # exclude any path whose last part is 'var'
@ -309,15 +324,14 @@ EXAMPLES = '''
# Specify the rsync binary to use on remote host and on local host
- hosts: groupofhosts
vars:
ansible_rsync_path: "/usr/gnu/bin/rsync"
ansible_rsync_path: /usr/gnu/bin/rsync
tasks:
- name: copy /tmp/localpath/ to remote location /tmp/remotepath
synchronize:
src: "/tmp/localpath/"
dest: "/tmp/remotepath"
rsync_path: "/usr/gnu/bin/rsync"
src: /tmp/localpath/
dest: /tmp/remotepath
rsync_path: /usr/gnu/bin/rsync
'''
@ -370,7 +384,7 @@ def main():
private_key=dict(type='path'),
rsync_path=dict(type='str'),
_local_rsync_path=dict(type='path', default='rsync'),
_local_rsync_password=dict(default=None, no_log=True),
_local_rsync_password=dict(type='str', default=None, no_log=True),
_substitute_controller=dict(type='bool', default=False),
archive=dict(type='bool', default=True),
checksum=dict(type='bool', default=False),

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

@ -16,7 +16,7 @@ DOCUMENTATION = '''
---
module: tempfile
version_added: "2.3"
short_description: Creates temporary files and directories.
short_description: Creates temporary files and directories
description:
- The C(tempfile) module creates temporary files and directories. C(mktemp) command takes different parameters on various systems, this module helps
to avoid troubles related to that. Files/directories created by module are accessible only by creator. In case you need to make them world-accessible
@ -26,22 +26,26 @@ options:
state:
description:
- Whether to create file or directory.
type: str
choices: [ directory, file ]
default: file
path:
description:
- Location where temporary file or directory should be created. If path is not specified default system temporary directory will be used.
- Location where temporary file or directory should be created.
- If path is not specified, the default system temporary directory will be used.
type: path
prefix:
description:
- Prefix of file/directory name created by module.
type: str
default: ansible.
suffix:
description:
- Suffix of file/directory name created by module.
type: str
default: ""
notes:
- For Windows targets, use the M(win_tempfile) module instead.
seealso:
- module: file
- module: win_tempfile
author:
- Krzysztof Magosa (@krzysztof-magosa)

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

@ -35,10 +35,12 @@ options:
description:
- Path of a Jinja2 formatted template on the Ansible controller.
- This can be a relative or an absolute path.
type: path
required: yes
dest:
description:
- Location to render the template to on the remote machine.
type: path
required: yes
backup:
description:
@ -50,27 +52,32 @@ options:
newline_sequence:
description:
- Specify the newline sequence to use for templating files.
type: str
choices: [ '\n', '\r', '\r\n' ]
default: '\n'
version_added: '2.4'
block_start_string:
description:
- The string marking the beginning of a block.
type: str
default: '{%'
version_added: '2.4'
block_end_string:
description:
- The string marking the end of a block.
type: str
default: '%}'
version_added: '2.4'
variable_start_string:
description:
- The string marking the beginning of a print statement.
type: str
default: '{{'
version_added: '2.4'
variable_end_string:
description:
- The string marking the end of a print statement.
type: str
default: '}}'
version_added: '2.4'
trim_blocks:
@ -84,7 +91,7 @@ options:
description:
- Determine when leading spaces and tabs should be stripped.
- When set to C(yes) leading spaces and tabs are stripped from the start of a line to a block.
- This functionality requires Jinja v2.7 or newer.
- This functionality requires Jinja 2.7 or newer.
type: bool
default: no
version_added: '2.6'
@ -109,11 +116,12 @@ options:
- Overrides the encoding used to write the template file defined by C(dest).
- It defaults to C(utf-8), but any encoding supported by python can be used.
- The source template file must always be encoded using C(utf-8), for homogeneity.
type: str
default: utf-8
version_added: '2.7'
notes:
- Including a string that uses a date in the template will result in the template being marked 'changed' each time.
- Since Ansible version 0.9, templates are loaded with C(trim_blocks=True).
- Since Ansible 0.9, templates are loaded with C(trim_blocks=True).
- >
Also, you can override jinja2 settings by adding a special header to template file.
i.e. C(#jinja2:variable_start_string:'[%', variable_end_string:'%]', trim_blocks: False)
@ -151,7 +159,7 @@ EXAMPLES = r'''
dest: /etc/file.conf
owner: bin
group: wheel
mode: "u=rw,g=r,o=r"
mode: u=rw,g=r,o=r
- name: Create a DOS-style text file from a template
template:
@ -163,7 +171,7 @@ EXAMPLES = r'''
template:
src: /mine/sudoers
dest: /etc/sudoers
validate: '/usr/sbin/visudo -cf %s'
validate: /usr/sbin/visudo -cf %s
- name: Update sshd configuration safely, avoid locking yourself out
template:

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

@ -24,8 +24,8 @@ description:
- The C(unarchive) module unpacks an archive.
- By default, it will copy the source file from the local system to the target before unpacking.
- Set C(remote_src=yes) to unpack an archive which already exists on the target.
- For Windows targets, use the M(win_unzip) module instead.
- If checksum validation is desired, use M(get_url) or M(uri) instead to fetch the file and set C(remote_src=yes).
- For Windows targets, use the M(win_unzip) module instead.
options:
src:
description:
@ -33,57 +33,62 @@ options:
target server to existing archive file to unpack.
- If C(remote_src=yes) and C(src) contains C(://), the remote machine will download the file from the URL first. (version_added 2.0). This is only for
simple cases, for full download support use the M(get_url) module.
type: path
required: true
dest:
description:
- Remote absolute path where the archive should be unpacked.
type: path
required: true
copy:
description:
- If true, the file is copied from local 'master' to the target machine, otherwise, the plugin will look for src archive at the target machine.
- This option has been deprecated in favor of C(remote_src).
- This option is mutually exclusive with C(remote_src).
type: 'bool'
default: 'yes'
type: bool
default: yes
creates:
description:
- If the specified absolute path (file or directory) already exists, this step will B(not) be run.
type: path
version_added: "1.6"
list_files:
description:
- If set to True, return the list of files that are contained in the tarball.
type: 'bool'
default: 'no'
type: bool
default: no
version_added: "2.0"
exclude:
description:
- List the directory and file entries that you would like to exclude from the unarchive action.
type: list
version_added: "2.1"
keep_newer:
description:
- Do not replace existing files that are newer than files from the archive.
type: 'bool'
default: 'no'
type: bool
default: no
version_added: "2.1"
extra_opts:
description:
- Specify additional options by passing in an array.
type: list
default: ""
version_added: "2.1"
remote_src:
description:
- Set to C(yes) to indicate the archived file is already on the remote system and not local to the Ansible controller.
- This option is mutually exclusive with C(copy).
type: 'bool'
default: 'no'
type: bool
default: no
version_added: "2.2"
validate_certs:
description:
- This only applies if using a https URL as the source of the file.
- This should only set to C(no) used on personally controlled sites using self-signed certificate.
- Prior to 2.2 the code worked as if this was set to C(yes).
type: 'bool'
default: 'yes'
type: bool
default: yes
version_added: "2.2"
extends_documentation_fragment:
- decrypt
@ -100,8 +105,9 @@ notes:
are not touched. This is the same behavior as a normal archive extraction.
- Existing files/directories in the destination which are not in the archive
are ignored for purposes of deciding if the archive should be unpacked or not.
- For Windows targets, use the M(win_unzip) module instead.
seealso:
- module: archive
- module: iso_extract
- module: win_unzip
author: Michael DeHaan
'''

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

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