archive
/
ansible
mirror of https://github.com/ansible/ansible.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Use semantic markup for modules. (#81190)

Browse Source
pull/81246/head^2
Felix Fontein 12 months ago committed by GitHub
parent f2ade88334
commit 3e3fb26b35
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
61 changed files with 676 additions and 670 deletions
Show Stats Download Patch File Download Diff File

4
lib/ansible/modules/add_host.py
Unescape Escape View File

@ -59,8 +59,8 @@ attributes:
platform:
platforms: all
notes:
- The alias C(host) of the parameter C(name) is only available on Ansible 2.4 and newer.
- Since Ansible 2.4, the C(inventory_dir) variable is now set to C(None) instead of the 'global inventory source',
- The alias O(host) of the parameter O(name) is only available on Ansible 2.4 and newer.
- Since Ansible 2.4, the C(inventory_dir) variable is now set to V(None) instead of the 'global inventory source',
because you can now have multiple sources. An example was added that shows how to partially restore the previous behaviour.
- Though this module does not change the remote host, we do provide 'changed' status as it can be useful for those trying to track inventory changes.
- The hosts added will not bypass the C(--limit) from the command line, so both of those need to be in agreement to make them available as play targets.

42
lib/ansible/modules/apt.py
Unescape Escape View File

@ -20,15 +20,15 @@ version_added: "0.0.2"
options:
name:
description:
- A list of package names, like C(foo), or package specifier with version, like C(foo=1.0) or C(foo>=1.0).
Name wildcards (fnmatch) like C(apt*) and version wildcards like C(foo=1.0*) are also supported.
- A list of package names, like V(foo), or package specifier with version, like V(foo=1.0) or V(foo>=1.0).
Name wildcards (fnmatch) like V(apt*) and version wildcards like V(foo=1.0*) are also supported.
aliases: [ package, pkg ]
type: list
elements: str
state:
description:
- Indicates the desired package state. C(latest) ensures that the latest version is installed. C(build-dep) ensures the package build dependencies
are installed. C(fixed) attempt to correct a system with broken dependencies in place.
- Indicates the desired package state. V(latest) ensures that the latest version is installed. V(build-dep) ensures the package build dependencies
are installed. V(fixed) attempt to correct a system with broken dependencies in place.
type: str
default: present
choices: [ absent, build-dep, latest, present, fixed ]
@ -40,25 +40,25 @@ options:
type: bool
update_cache_retries:
description:
- Amount of retries if the cache update fails. Also see I(update_cache_retry_max_delay).
- Amount of retries if the cache update fails. Also see O(update_cache_retry_max_delay).
type: int
default: 5
version_added: '2.10'
update_cache_retry_max_delay:
description:
- Use an exponential backoff delay for each retry (see I(update_cache_retries)) up to this max delay in seconds.
- Use an exponential backoff delay for each retry (see O(update_cache_retries)) up to this max delay in seconds.
type: int
default: 12
version_added: '2.10'
cache_valid_time:
description:
- Update the apt cache if it is older than the I(cache_valid_time). This option is set in seconds.
- As of Ansible 2.4, if explicitly set, this sets I(update_cache=yes).
- Update the apt cache if it is older than the O(cache_valid_time). This option is set in seconds.
- As of Ansible 2.4, if explicitly set, this sets O(update_cache=yes).
type: int
default: 0
purge:
description:
- Will force purging of configuration files if the module state is set to I(absent).
- Will force purging of configuration files if the module O(state) is set to V(absent).
type: bool
default: 'no'
default_release:
@ -68,13 +68,13 @@ options:
type: str
install_recommends:
description:
- Corresponds to the C(--no-install-recommends) option for I(apt). C(true) installs recommended packages. C(false) does not install
- Corresponds to the C(--no-install-recommends) option for I(apt). V(true) installs recommended packages. V(false) does not install
recommended packages. By default, Ansible will use the same defaults as the operating system. Suggested packages are never installed.
aliases: [ install-recommends ]
type: bool
force:
description:
- 'Corresponds to the C(--force-yes) to I(apt-get) and implies C(allow_unauthenticated: yes) and C(allow_downgrade: yes)'
- 'Corresponds to the C(--force-yes) to I(apt-get) and implies O(allow_unauthenticated=yes) and O(allow_downgrade=yes)'
- "This option will disable checking both the packages' signatures and the certificates of the
web servers they are downloaded from."
- 'This option *is not* the equivalent of passing the C(-f) flag to I(apt-get) on the command line'
@ -93,7 +93,7 @@ options:
allow_unauthenticated:
description:
- Ignore if packages cannot be authenticated. This is useful for bootstrapping environments that manage their own apt-key setup.
- 'C(allow_unauthenticated) is only supported with state: I(install)/I(present)'
- 'O(allow_unauthenticated) is only supported with O(state): V(install)/V(present)'
aliases: [ allow-unauthenticated ]
type: bool
default: 'no'
@ -102,7 +102,7 @@ options:
description:
- Corresponds to the C(--allow-downgrades) option for I(apt).
- This option enables the named package and version to replace an already installed higher version of that package.
- Note that setting I(allow_downgrade=true) can make this module behave in a non-idempotent way.
- Note that setting O(allow_downgrade=true) can make this module behave in a non-idempotent way.
- (The task could end up with a set of packages that does not match the complete list of specified packages to install).
aliases: [ allow-downgrade, allow_downgrades, allow-downgrades ]
type: bool
@ -141,14 +141,14 @@ options:
version_added: "1.6"
autoremove:
description:
- If C(true), remove unused dependency packages for all module states except I(build-dep). It can also be used as the only option.
- If V(true), remove unused dependency packages for all module states except V(build-dep). It can also be used as the only option.
- Previous to version 2.4, autoclean was also an alias for autoremove, now it is its own separate command. See documentation for further information.
type: bool
default: 'no'
version_added: "2.1"
autoclean:
description:
- If C(true), cleans the local repository of retrieved package files that can no longer be downloaded.
- If V(true), cleans the local repository of retrieved package files that can no longer be downloaded.
type: bool
default: 'no'
version_added: "2.4"
@ -157,7 +157,7 @@ options:
- Force the exit code of /usr/sbin/policy-rc.d.
- For example, if I(policy_rc_d=101) the installed package will not trigger a service start.
- If /usr/sbin/policy-rc.d already exists, it is backed up and restored after the package installation.
- If C(null), the /usr/sbin/policy-rc.d isn't created/changed.
- If V(null), the /usr/sbin/policy-rc.d isn't created/changed.
type: int
default: null
version_added: "2.8"
@ -170,8 +170,8 @@ options:
fail_on_autoremove:
description:
- 'Corresponds to the C(--no-remove) option for C(apt).'
- 'If C(true), it is ensured that no packages will be removed or the task will fail.'
- 'C(fail_on_autoremove) is only supported with state except C(absent)'
- 'If V(true), it is ensured that no packages will be removed or the task will fail.'
- 'O(fail_on_autoremove) is only supported with O(state) except V(absent)'
type: bool
default: 'no'
version_added: "2.11"
@ -202,15 +202,15 @@ attributes:
platform:
platforms: debian
notes:
- Three of the upgrade modes (C(full), C(safe) and its alias C(true)) required C(aptitude) up to 2.3, since 2.4 C(apt-get) is used as a fall-back.
- Three of the upgrade modes (V(full), V(safe) and its alias V(true)) required C(aptitude) up to 2.3, since 2.4 C(apt-get) is used as a fall-back.
- In most cases, packages installed with apt will start newly installed services by default. Most distributions have mechanisms to avoid this.
For example when installing Postgresql-9.5 in Debian 9, creating an excutable shell script (/usr/sbin/policy-rc.d) that throws
a return code of 101 will stop Postgresql 9.5 starting up after install. Remove the file or remove its execute permission afterwards.
- The apt-get commandline supports implicit regex matches here but we do not because it can let typos through easier
(If you typo C(foo) as C(fo) apt-get would install packages that have "fo" in their name with a warning and a prompt for the user.
Since we don't have warnings and prompts before installing we disallow this.Use an explicit fnmatch pattern if you want wildcarding)
- When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly to the I(name) option.
- When C(default_release) is used, an implicit priority of 990 is used. This is the same behavior as C(apt-get -t).
- When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly to the O(name) option.
- When O(default_release) is used, an implicit priority of 990 is used. This is the same behavior as C(apt-get -t).
- When an exact version is specified, an implicit priority of 1001 is used.
'''

6
lib/ansible/modules/apt_key.py
Unescape Escape View File

@ -32,7 +32,7 @@ notes:
- As a sanity check, downloaded key id must match the one specified.
- "Use full fingerprint (40 characters) key ids to avoid key collisions.
To generate a full-fingerprint imported key: C(apt-key adv --list-public-keys --with-fingerprint --with-colons)."
- If you specify both the key id and the URL with C(state=present), the task can verify or add the key as needed.
- If you specify both the key id and the URL with O(state=present), the task can verify or add the key as needed.
- Adding a new key requires an apt cache update (e.g. using the M(ansible.builtin.apt) module's update_cache option).
requirements:
- gpg
@ -44,7 +44,7 @@ options:
- The identifier of the key.
- Including this allows check mode to correctly report the changed state.
- If specifying a subkey's id be aware that apt-key does not understand how to remove keys via a subkey id. Specify the primary key's id instead.
- This parameter is required when C(state) is set to C(absent).
- This parameter is required when O(state) is set to V(absent).
type: str
data:
description:
@ -76,7 +76,7 @@ options:
default: present
validate_certs:
description:
- If C(false), SSL certificates for the target url will not be validated. This should only be used
- If V(false), SSL certificates for the target url will not be validated. This should only be used
on personally controlled sites using self-signed certificates.
type: bool
default: 'yes'

8
lib/ansible/modules/apt_repository.py
Unescape Escape View File

@ -54,19 +54,19 @@ options:
aliases: [ update-cache ]
update_cache_retries:
description:
- Amount of retries if the cache update fails. Also see I(update_cache_retry_max_delay).
- Amount of retries if the cache update fails. Also see O(update_cache_retry_max_delay).
type: int
default: 5
version_added: '2.10'
update_cache_retry_max_delay:
description:
- Use an exponential backoff delay for each retry (see I(update_cache_retries)) up to this max delay in seconds.
- Use an exponential backoff delay for each retry (see O(update_cache_retries)) up to this max delay in seconds.
type: int
default: 12
version_added: '2.10'
validate_certs:
description:
- If C(false), SSL certificates for the target repo will not be validated. This should only be used
- If V(false), SSL certificates for the target repo will not be validated. This should only be used
on personally controlled sites using self-signed certificates.
type: bool
default: 'yes'
@ -91,7 +91,7 @@ options:
Without this library, the module does not work.
- Runs C(apt-get install python-apt) for Python 2, and C(apt-get install python3-apt) for Python 3.
- Only works with the system Python 2 or Python 3. If you are using a Python on the remote that is not
the system Python, set I(install_python_apt=false) and ensure that the Python apt library
the system Python, set O(install_python_apt=false) and ensure that the Python apt library
for your Python version is installed some other way.
type: bool
default: true

12
lib/ansible/modules/assemble.py
Unescape Escape View File

@ -17,7 +17,7 @@ description:
- Assembles a configuration file from fragments.
- Often a particular program will take a single configuration file and does not support a
C(conf.d) style structure where it is easy to build up the configuration
from multiple sources. C(assemble) will take a directory of files that can be
from multiple sources. M(ansible.builtin.assemble) will take a directory of files that can be
local or have already been transferred to the system, and concatenate them
together to produce a destination file.
- Files are assembled in string sorting order.
@ -36,7 +36,7 @@ options:
required: true
backup:
description:
- Create a backup file (if C(true)), including the timestamp information so
- Create a backup file (if V(true)), including the timestamp information so
you can get the original file back if you somehow clobbered it
incorrectly.
type: bool
@ -48,16 +48,16 @@ options:
version_added: '1.4'
remote_src:
description:
- If C(false), it will search for src at originating/master machine.
- If C(true), it will go to the remote/target machine for the src.
- If V(false), it will search for src at originating/master machine.
- If V(true), it will go to the remote/target machine for the src.
type: bool
default: yes
version_added: '1.4'
regexp:
description:
- Assemble files only if C(regex) matches the filename.
- Assemble files only if the given regular expression matches the filename.
- If not set, all files are assembled.
- Every C(\) (backslash) must be escaped as C(\\) to comply to YAML syntax.
- Every V(\\) (backslash) must be escaped as V(\\\\) to comply to YAML syntax.
- Uses L(Python regular expressions,https://docs.python.org/3/library/re.html).
type: str
ignore_hidden:

2
lib/ansible/modules/assert.py
Unescape Escape View File

@ -36,7 +36,7 @@ options:
version_added: "2.7"
quiet:
description:
- Set this to C(true) to avoid verbose output.
- Set this to V(true) to avoid verbose output.
type: bool
default: no
version_added: "2.8"

8
lib/ansible/modules/async_status.py
Unescape Escape View File

@ -23,8 +23,8 @@ options:
required: true
mode:
description:
- If C(status), obtain the status.
- If C(cleanup), clean up the async job cache (by default in C(~/.ansible_async/)) for the specified job I(jid).
- If V(status), obtain the status.
- If V(cleanup), clean up the async job cache (by default in C(~/.ansible_async/)) for the specified job O(jid).
type: str
choices: [ cleanup, status ]
default: status
@ -79,12 +79,12 @@ ansible_job_id:
type: str
sample: '360874038559.4169'
finished:
description: Whether the asynchronous job has finished (C(1)) or not (C(0))
description: Whether the asynchronous job has finished (V(1)) or not (V(0))
returned: always
type: int
sample: 1
started:
description: Whether the asynchronous job has started (C(1)) or not (C(0))
description: Whether the asynchronous job has started (V(1)) or not (V(0))
returned: always
type: int
sample: 1

29
lib/ansible/modules/blockinfile.py
Unescape Escape View File

@ -21,7 +21,7 @@ options:
path:
description:
- 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 O(dest), O(destfile) and O(name).
type: path
required: yes
aliases: [ dest, destfile, name ]
@ -34,24 +34,24 @@ options:
marker:
description:
- The marker line template.
- C({mark}) will be replaced with the values in C(marker_begin) (default="BEGIN") and C(marker_end) (default="END").
- C({mark}) will be replaced with the values in O(marker_begin) (default="BEGIN") and O(marker_end) (default="END").
- Using a custom marker without the C({mark}) variable may result in the block being repeatedly inserted on subsequent playbook runs.
- Multi-line markers are not supported and will result in the block being repeatedly inserted on subsequent playbook runs.
- A newline is automatically appended by the module to C(marker_begin) and C(marker_end).
- A newline is automatically appended by the module to O(marker_begin) and O(marker_end).
type: str
default: '# {mark} ANSIBLE MANAGED BLOCK'
block:
description:
- 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 O(state) were specified to V(absent).
type: str
default: ''
aliases: [ content ]
insertafter:
description:
- If specified and no begin/ending C(marker) lines are found, 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.
- If specified and no begin/ending O(marker) lines are found, the block will be inserted after the last match of specified regular expression.
- A special value is available; V(EOF) for inserting the block at the end of the file.
- If specified regular expression has no matches, V(EOF) will be used instead.
- The presence of the multiline flag (?m) in the regular expression controls whether the match is done line by line or with multiple lines.
This behaviour was added in ansible-core 2.14.
type: str
@ -59,8 +59,8 @@ options:
default: EOF
insertbefore:
description:
- If specified and no begin/ending C(marker) lines are found, the block will be inserted before the last match of specified regular expression.
- A special value is available; C(BOF) for inserting the block at the beginning of the file.
- If specified and no begin/ending O(marker) lines are found, the block will be inserted before the last match of specified regular expression.
- A special value is available; V(BOF) for inserting the block at the beginning of the file.
- If specified regular expression has no matches, the block will be inserted at the end of the file.
- The presence of the multiline flag (?m) in the regular expression controls whether the match is done line by line or with multiple lines.
This behaviour was added in ansible-core 2.14.
@ -79,22 +79,23 @@ options:
default: no
marker_begin:
description:
- This will be inserted at C({mark}) in the opening ansible block marker.
- This will be inserted at C({mark}) in the opening ansible block O(marker).
type: str
default: BEGIN
version_added: '2.5'
marker_end:
required: false
description:
- This will be inserted at C({mark}) in the closing ansible block marker.
- This will be inserted at C({mark}) in the closing ansible block O(marker).
type: str
default: END
version_added: '2.5'
notes:
- When using 'with_*' loops be aware that if you do not set a unique mark the block will be overwritten on each iteration.
- As of Ansible 2.3, the I(dest) option has been changed to I(path) as default, but I(dest) still works as well.
- 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.
- When more then one block should be handled in one file you must change the I(marker) per task.
- As of Ansible 2.3, the O(dest) option has been changed to O(path) as default, but O(dest) still works as well.
- Option O(ignore:follow) has been removed in Ansible 2.5, because this module modifies the contents of the file
so O(ignore:follow=no) does not make sense.
- When more then one block should be handled in one file you must change the O(marker) per task.
extends_documentation_fragment:
- action_common_attributes
- action_common_attributes.files

26
lib/ansible/modules/command.py
Unescape Escape View File

@ -14,7 +14,7 @@ module: command
short_description: Execute commands on targets
version_added: historical
description:
- The C(command) module takes the command name followed by a list of space-delimited arguments.
- The M(ansible.builtin.command) module takes the command name followed by a list of space-delimited arguments.
- The given command will be executed on all selected nodes.
- The command(s) will not be
processed through the shell, so variables like C($HOSTNAME) and operations
@ -22,15 +22,15 @@ description:
Use the M(ansible.builtin.shell) module if you need these features.
- To create C(command) tasks that are easier to read than the ones using space-delimited
arguments, pass parameters using the C(args) L(task keyword,https://docs.ansible.com/ansible/latest/reference_appendices/playbooks_keywords.html#task)
or use C(cmd) parameter.
- Either a free form command or C(cmd) parameter is required, see the examples.
or use O(cmd) parameter.
- Either a free form command or O(cmd) parameter is required, see the examples.
- For Windows targets, use the M(ansible.windows.win_command) module instead.
extends_documentation_fragment:
- action_common_attributes
- action_common_attributes.raw
attributes:
check_mode:
details: while the command itself is arbitrary and cannot be subject to the check mode semantics it adds C(creates)/C(removes) options as a workaround
details: while the command itself is arbitrary and cannot be subject to the check mode semantics it adds O(creates)/O(removes) options as a workaround
support: partial
diff_mode:
support: none
@ -44,7 +44,7 @@ options:
description:
- Expands the arguments that are variables, for example C($HOME) will be expanded before being passed to the
command to run.
- Set to C(false) to disable expansion and treat the value as a literal argument.
- Set to V(false) to disable expansion and treat the value as a literal argument.
type: bool
default: true
version_added: "2.16"
@ -61,19 +61,19 @@ options:
elements: str
description:
- Passes the command as a list rather than a string.
- Use C(argv) to avoid quoting values that would otherwise be interpreted incorrectly (for example "user name").
- Use O(argv) to avoid quoting values that would otherwise be interpreted incorrectly (for example "user name").
- Only the string (free form) or the list (argv) form can be provided, not both. One or the other must be provided.
version_added: "2.6"
creates:
type: path
description:
- A filename or (since 2.0) glob pattern. If a matching file already exists, this step B(will not) be run.
- This is checked before I(removes) is checked.
- This is checked before O(removes) is checked.
removes:
type: path
description:
- A filename or (since 2.0) glob pattern. If a matching file exists, this step B(will) be run.
- This is checked after I(creates) is checked.
- This is checked after O(creates) is checked.
version_added: "0.8"
chdir:
type: path
@ -89,7 +89,7 @@ options:
type: bool
default: yes
description:
- If set to C(true), append a newline to stdin data.
- If set to V(true), append a newline to stdin data.
version_added: "2.8"
strip_empty_ends:
description:
@ -101,12 +101,12 @@ notes:
- If you want to run a command through the shell (say you are using C(<), C(>), C(|), and so on),
you actually want the M(ansible.builtin.shell) module instead.
Parsing shell metacharacters can lead to unexpected commands being executed if quoting is not done correctly so it is more secure to
use the C(command) module when possible.
- C(creates), C(removes), and C(chdir) can be specified after the command.
use the M(ansible.builtin.command) module when possible.
- O(creates), O(removes), and O(chdir) can be specified after the command.
For instance, if you only want to run a command if a certain file does not exist, use this.
- Check mode is supported when passing C(creates) or C(removes). If running in check mode and either of these are specified, the module will
- Check mode is supported when passing O(creates) or O(removes). If running in check mode and either of these are specified, the module will
check for the existence of the file and report the correct changed status. If these are not supplied, the task will be skipped.
- The C(executable) parameter is removed since version 2.4. If you have a need for this parameter, use the M(ansible.builtin.shell) module instead.
- The O(ignore:executable) parameter is removed since version 2.4. If you have a need for this parameter, use the M(ansible.builtin.shell) module instead.
- For Windows targets, use the M(ansible.windows.win_command) module instead.
- For rebooting systems, use the M(ansible.builtin.reboot) or M(ansible.windows.win_reboot) module.
- If the command returns non UTF-8 data, it must be encoded to avoid issues. This may necessitate using M(ansible.builtin.shell) so the output

50
lib/ansible/modules/copy.py
Unescape Escape View File

@ -14,10 +14,10 @@ module: copy
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.
- The M(ansible.builtin.copy) module copies a file from the local or remote machine to a location on the remote machine.
- Use the M(ansible.builtin.fetch) module to copy files from remote locations to the local box.
- If you need variable interpolation in copied files, use the M(ansible.builtin.template) module.
Using a variable in the C(content) field will result in unpredictable output.
Using a variable in the O(content) field will result in unpredictable output.
- For Windows targets, use the M(ansible.windows.win_copy) module instead.
options:
src:
@ -31,19 +31,19 @@ options:
type: path
content:
description:
- When used instead of C(src), sets the contents of a file directly to the specified value.
- Works only when C(dest) is a file. Creates the file if it does not exist.
- For advanced formatting or if C(content) contains a variable, use the
- When used instead of O(src), sets the contents of a file directly to the specified value.
- Works only when O(dest) is a file. Creates the file if it does not exist.
- For advanced formatting or if O(content) contains a variable, use the
M(ansible.builtin.template) module.
type: str
version_added: '1.1'
dest:
description:
- Remote absolute path where the file should be copied to.
- If C(src) is a directory, this must be a directory too.
- If C(dest) is a non-existent path and if either C(dest) ends with "/" or C(src) is a directory, C(dest) is created.
- If I(dest) is a relative path, the starting directory is determined by the remote host.
- If C(src) and C(dest) are files, the parent directory of C(dest) is not created and the task fails if it does not already exist.
- If O(src) is a directory, this must be a directory too.
- If O(dest) is a non-existent path and if either O(dest) ends with "/" or O(src) is a directory, O(dest) is created.
- If O(dest) is a relative path, the starting directory is determined by the remote host.
- If O(src) and O(dest) are files, the parent directory of O(dest) is not created and the task fails if it does not already exist.
type: path
required: yes
backup:
@ -55,8 +55,8 @@ options:
force:
description:
- Influence whether the remote file must always be replaced.
- If C(true), the remote file will be replaced when contents are different than the source.
- If C(false), the file will only be transferred if the destination does not exist.
- If V(true), the remote file will be replaced when contents are different than the source.
- If V(false), the file will only be transferred if the destination does not exist.
type: bool
default: yes
version_added: '1.1'
@ -65,17 +65,17 @@ options:
- The permissions of the destination file or directory.
- For those used to C(/usr/bin/chmod) remember that modes are actually octal numbers.
You must either add a leading zero so that Ansible's YAML parser knows it is an octal number
(like C(0644) or C(01777)) or quote it (like C('644') or C('1777')) so Ansible receives a string
(like V(0644) or V(01777)) or quote it (like V('644') or V('1777')) so Ansible receives a string
and can do its own conversion from string into number. Giving Ansible a number without following
one of these rules will end up with a decimal number which will have unexpected results.
- 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.
- When doing a recursive copy, see also C(directory_mode).
- If C(mode) is not specified and the destination file B(does not) exist, the default C(umask) on the system will be used
- As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, V(u+rwx) or V(u=rw,g=r,o=r)).
- As of Ansible 2.3, the mode may also be the special string V(preserve).
- V(preserve) means that the file will be given the same permissions as the source file.
- When doing a recursive copy, see also O(directory_mode).
- If O(mode) is not specified and the destination file B(does not) exist, the default C(umask) on the system will be used
when setting the mode for the newly created file.
- If C(mode) is not specified and the destination file B(does) exist, the mode of the existing file will be used.
- Specifying C(mode) is the best way to ensure files are created with the correct permissions.
- If O(mode) is not specified and the destination file B(does) exist, the mode of the existing file will be used.
- Specifying O(mode) is the best way to ensure files are created with the correct permissions.
See CVE-2020-1736 for further details.
directory_mode:
description:
@ -86,12 +86,12 @@ options:
version_added: '1.5'
remote_src:
description:
- Influence whether C(src) needs to be transferred or already is present remotely.
- If C(false), it will search for C(src) on the controller node.
- If C(true) it will search for C(src) on the managed (remote) node.
- C(remote_src) supports recursive copying as of version 2.8.
- C(remote_src) only works with C(mode=preserve) as of version 2.6.
- Autodecryption of files does not work when C(remote_src=yes).
- Influence whether O(src) needs to be transferred or already is present remotely.
- If V(false), it will search for O(src) on the controller node.
- If V(true) it will search for O(src) on the managed (remote) node.
- O(remote_src) supports recursive copying as of version 2.8.
- O(remote_src) only works with O(mode=preserve) as of version 2.6.
- Autodecryption of files does not work when O(remote_src=yes).
type: bool
default: no
version_added: '2.0'

28
lib/ansible/modules/cron.py
Unescape Escape View File

@ -44,7 +44,7 @@ options:
description:
- The command to execute or, if env is set, the value of environment variable.
- The command should not contain line breaks.
- Required if I(state=present).
- Required if O(state=present).
type: str
aliases: [ value ]
state:
@ -58,42 +58,42 @@ options:
- If specified, uses this file instead of an individual user's crontab.
The assumption is that this file is exclusively managed by the module,
do not use if the file contains multiple entries, NEVER use for /etc/crontab.
- If this is a relative path, it is interpreted with respect to I(/etc/cron.d).
- If this is a relative path, it is interpreted with respect to C(/etc/cron.d).
- Many linux distros expect (and some require) the filename portion to consist solely
of upper- and lower-case letters, digits, underscores, and hyphens.
- Using this parameter requires you to specify the I(user) as well, unless I(state) is not I(present).
- Either this parameter or I(name) is required
- Using this parameter requires you to specify the O(user) as well, unless O(state) is not V(present).
- Either this parameter or O(name) is required
type: path
backup:
description:
- If set, create a backup of the crontab before it is modified.
The location of the backup is returned in the C(backup_file) variable by this module.
The location of the backup is returned in the RV(ignore:backup_file) variable by this module.
type: bool
default: no
minute:
description:
- Minute when the job should run (C(0-59), C(*), C(*/2), and so on).
- Minute when the job should run (V(0-59), V(*), V(*/2), and so on).
type: str
default: "*"
hour:
description:
- Hour when the job should run (C(0-23), C(*), C(*/2), and so on).
- Hour when the job should run (V(0-23), V(*), V(*/2), and so on).
type: str
default: "*"
day:
description:
- Day of the month the job should run (C(1-31), C(*), C(*/2), and so on).
- Day of the month the job should run (V(1-31), V(*), V(*/2), and so on).
type: str
default: "*"
aliases: [ dom ]
month:
description:
- Month of the year the job should run (C(1-12), C(*), C(*/2), and so on).
- Month of the year the job should run (V(1-12), V(*), V(*/2), and so on).
type: str
default: "*"
weekday:
description:
- Day of the week that the job should run (C(0-6) for Sunday-Saturday, C(*), and so on).
- Day of the week that the job should run (V(0-6) for Sunday-Saturday, V(*), and so on).
type: str
default: "*"
aliases: [ dow ]
@ -106,7 +106,7 @@ options:
disabled:
description:
- If the job should be disabled (commented out) in the crontab.
- Only has effect if I(state=present).
- Only has effect if O(state=present).
type: bool
default: no
version_added: "2.0"
@ -114,19 +114,19 @@ options:
description:
- If set, manages a crontab's environment variable.
- New variables are added on top of crontab.
- I(name) and I(value) parameters are the name and the value of environment variable.
- O(name) and O(value) parameters are the name and the value of environment variable.
type: bool
default: false
version_added: "2.1"
insertafter:
description:
- Used with I(state=present) and I(env).
- Used with O(state=present) and O(env).
- If specified, the environment variable will be inserted after the declaration of specified environment variable.
type: str
version_added: "2.1"
insertbefore:
description:
- Used with I(state=present) and I(env).
- Used with O(state=present) and O(env).
- If specified, the environment variable will be inserted before the declaration of specified environment variable.
type: str
version_added: "2.1"

4
lib/ansible/modules/deb822_repository.py
Unescape Escape View File

@ -97,7 +97,7 @@ options:
- >-
Suite can specify an exact path in relation to the URI(s) provided,
in which case the Components: must be omitted and suite must end
with a slash C( / ). Alternatively, it may take the form of a
with a slash (C(/)). Alternatively, it may take the form of a
distribution version (e.g. a version codename like disco or artful).
If the suite does not specify a path, at least one component must
be present.
@ -124,7 +124,7 @@ options:
elements: str
description:
- Which types of packages to look for from a given source; either
binary C(deb) or source code C(deb-src)
binary V(deb) or source code V(deb-src)
uris:
description:
- The URIs must specify the base of the Debian distribution archive,

8
lib/ansible/modules/debconf.py
Unescape Escape View File

@ -31,9 +31,9 @@ notes:
Use 'debconf-show <package>' on any Debian or derivative with the package
installed to see questions/settings available.
- Some distros will always record tasks involving the setting of passwords as changed. This is due to debconf-get-selections masking passwords.
- It is highly recommended to add I(no_log=True) to task while handling sensitive information using this module.
- It is highly recommended to add C(no_log=True) to task while handling sensitive information using this module.
- The debconf module does not reconfigure packages, it just updates the debconf database.
An additional step is needed (typically with I(notify) if debconf makes a change)
An additional step is needed (typically with C(notify) if debconf makes a change)
to reconfigure the package and apply the changes.
debconf is extensively used for pre-seeding configuration prior to installation
rather than modifying configurations.
@ -69,8 +69,8 @@ options:
vtype:
description:
- The type of the value supplied.
- It is highly recommended to add I(no_log=True) to task while specifying I(vtype=password).
- C(seen) was added in Ansible 2.2.
- It is highly recommended to add C(no_log=True) to task while specifying O(vtype=password).
- V(seen) was added in Ansible 2.2.
type: str
choices: [ boolean, error, multiselect, note, password, seen, select, string, text, title ]
value:

2
lib/ansible/modules/debug.py
Unescape Escape View File

@ -27,7 +27,7 @@ options:
var:
description:
- A variable name to debug.
- Mutually exclusive with the C(msg) option.
- Mutually exclusive with the O(msg) option.
- Be aware that this option already runs in Jinja2 context and has an implicit C({{ }}) wrapping,
so you should not be using Jinja2 delimiters unless you are looking for double interpolation.
type: str

40
lib/ansible/modules/dnf.py
Unescape Escape View File

@ -44,14 +44,14 @@ options:
list:
description:
- Various (non-idempotent) commands for usage with C(/usr/bin/ansible) and I(not) playbooks.
Use M(ansible.builtin.package_facts) instead of the C(list) argument as a best practice.
Use M(ansible.builtin.package_facts) instead of the O(list) argument as a best practice.
type: str
state:
description:
- Whether to install (C(present), C(latest)), or remove (C(absent)) a package.
- Default is C(None), however in effect the default action is C(present) unless the C(autoremove) option is
enabled for this module, then C(absent) is inferred.
- Whether to install (V(present), V(latest)), or remove (V(absent)) a package.
- Default is V(None), however in effect the default action is V(present) unless the O(autoremove) option is
enabled for this module, then V(absent) is inferred.
choices: ['absent', 'present', 'installed', 'removed', 'latest']
type: str
@ -81,7 +81,7 @@ options:
disable_gpg_check:
description:
- Whether to disable the GPG checking of signatures of packages being
installed. Has an effect only if state is I(present) or I(latest).
installed. Has an effect only if O(state) is V(present) or V(latest).
- This setting affects packages installed from a repository as well as
"local" packages installed from the filesystem or a URL.
type: bool
@ -104,9 +104,9 @@ options:
autoremove:
description:
- If C(true), removes all "leaf" packages from the system that were originally
- If V(true), removes all "leaf" packages from the system that were originally
installed as dependencies of user-installed packages but which are no longer
required by any such package. Should be used alone or when state is I(absent)
required by any such package. Should be used alone or when O(state) is V(absent)
type: bool
default: "no"
version_added: "2.4"
@ -128,7 +128,7 @@ options:
update_cache:
description:
- Force dnf to check if cache is out of date and redownload if needed.
Has an effect only if state is I(present) or I(latest).
Has an effect only if O(state) is V(present) or V(latest).
type: bool
default: "no"
aliases: [ expire-cache ]
@ -136,20 +136,20 @@ options:
update_only:
description:
- When using latest, only update installed packages. Do not install packages.
- Has an effect only if state is I(latest)
- Has an effect only if O(state) is V(latest)
default: "no"
type: bool
version_added: "2.7"
security:
description:
- If set to C(true), and C(state=latest) then only installs updates that have been marked security related.
- If set to V(true), and O(state=latest) then only installs updates that have been marked security related.
- Note that, similar to C(dnf upgrade-minimal), this filter applies to dependencies as well.
type: bool
default: "no"
version_added: "2.7"
bugfix:
description:
- If set to C(true), and C(state=latest) then only installs updates that have been marked bugfix related.
- If set to V(true), and O(state=latest) then only installs updates that have been marked bugfix related.
- Note that, similar to C(dnf upgrade-minimal), this filter applies to dependencies as well.
default: "no"
type: bool
@ -173,22 +173,22 @@ options:
disable_excludes:
description:
- Disable the excludes defined in DNF config files.
- If set to C(all), disables all excludes.
- If set to C(main), disable excludes defined in [main] in dnf.conf.
- If set to C(repoid), disable excludes defined for given repo id.
- If set to V(all), disables all excludes.
- If set to V(main), disable excludes defined in [main] in dnf.conf.
- If set to V(repoid), disable excludes defined for given repo id.
version_added: "2.7"
type: str
validate_certs:
description:
- This only applies if using a https url as the source of the rpm. e.g. for localinstall. If set to C(false), the SSL certificates will not be validated.
- This should only set to C(false) used on personally controlled sites using self-signed certificates as it avoids verifying the source site.
- This only applies if using a https url as the source of the rpm. e.g. for localinstall. If set to V(false), the SSL certificates will not be validated.
- This should only set to V(false) used on personally controlled sites using self-signed certificates as it avoids verifying the source site.
type: bool
default: "yes"
version_added: "2.7"
sslverify:
description:
- Disables SSL validation of the repository server for this transaction.
- This should be set to C(false) if one of the configured repositories is using an untrusted or self-signed certificate.
- This should be set to V(false) if one of the configured repositories is using an untrusted or self-signed certificate.
type: bool
default: "yes"
version_added: "2.13"
@ -208,7 +208,7 @@ options:
install_repoquery:
description:
- This is effectively a no-op in DNF as it is not needed with DNF, but is an accepted parameter for feature
parity/compatibility with the I(yum) module.
parity/compatibility with the M(ansible.builtin.yum) module.
type: bool
default: "yes"
version_added: "2.7"
@ -234,12 +234,12 @@ options:
download_dir:
description:
- Specifies an alternate directory to store packages.
- Has an effect only if I(download_only) is specified.
- Has an effect only if O(download_only) is specified.
type: str
version_added: "2.8"
allowerasing:
description:
- If C(true) it allows erasing of installed packages to resolve dependencies.
- If V(true) it allows erasing of installed packages to resolve dependencies.
required: false
type: bool
default: "no"

42
lib/ansible/modules/dnf5.py
Unescape Escape View File

@ -11,8 +11,8 @@ module: dnf5
author: Ansible Core Team
description:
- Installs, upgrade, removes, and lists packages and groups with the I(dnf5) package manager.
- "WARNING: The I(dnf5) package manager is still under development and not all features that the existing I(dnf) module
provides are implemented in I(dnf5), please consult specific options for more information."
- "WARNING: The I(dnf5) package manager is still under development and not all features that the existing M(ansible.builtin.dnf) module
provides are implemented in M(ansible.builtin.dnf5), please consult specific options for more information."
short_description: Manages packages with the I(dnf5) package manager
options:
name:
@ -33,13 +33,13 @@ options:
list:
description:
- Various (non-idempotent) commands for usage with C(/usr/bin/ansible) and I(not) playbooks.
Use M(ansible.builtin.package_facts) instead of the C(list) argument as a best practice.
Use M(ansible.builtin.package_facts) instead of the O(list) argument as a best practice.
type: str
state:
description:
- Whether to install (C(present), C(latest)), or remove (C(absent)) a package.
- Default is C(None), however in effect the default action is C(present) unless the C(autoremove) option is
enabled for this module, then C(absent) is inferred.
- Whether to install (V(present), V(latest)), or remove (V(absent)) a package.
- Default is V(None), however in effect the default action is V(present) unless the V(autoremove) option is
enabled for this module, then V(absent) is inferred.
choices: ['absent', 'present', 'installed', 'removed', 'latest']
type: str
enablerepo:
@ -65,7 +65,7 @@ options:
disable_gpg_check:
description:
- Whether to disable the GPG checking of signatures of packages being
installed. Has an effect only if state is I(present) or I(latest).
installed. Has an effect only if O(state) is V(present) or V(latest).
- This setting affects packages installed from a repository as well as
"local" packages installed from the filesystem or a URL.
type: bool
@ -83,9 +83,9 @@ options:
type: str
autoremove:
description:
- If C(true), removes all "leaf" packages from the system that were originally
- If V(true), removes all "leaf" packages from the system that were originally
installed as dependencies of user-installed packages but which are no longer
required by any such package. Should be used alone or when state is I(absent)
required by any such package. Should be used alone or when O(state) is V(absent)
type: bool
default: "no"
exclude:
@ -104,25 +104,25 @@ options:
update_cache:
description:
- Force dnf to check if cache is out of date and redownload if needed.
Has an effect only if state is I(present) or I(latest).
Has an effect only if O(state) is V(present) or V(latest).
type: bool
default: "no"
aliases: [ expire-cache ]
update_only:
description:
- When using latest, only update installed packages. Do not install packages.
- Has an effect only if state is I(latest)
- Has an effect only if O(state) is V(latest)
default: "no"
type: bool
security:
description:
- If set to C(true), and C(state=latest) then only installs updates that have been marked security related.
- If set to V(true), and O(state=latest) then only installs updates that have been marked security related.
- Note that, similar to C(dnf upgrade-minimal), this filter applies to dependencies as well.
type: bool
default: "no"
bugfix:
description:
- If set to C(true), and C(state=latest) then only installs updates that have been marked bugfix related.
- If set to V(true), and O(state=latest) then only installs updates that have been marked bugfix related.
- Note that, similar to C(dnf upgrade-minimal), this filter applies to dependencies as well.
default: "no"
type: bool
@ -145,20 +145,20 @@ options:
disable_excludes:
description:
- Disable the excludes defined in DNF config files.
- If set to C(all), disables all excludes.
- If set to C(main), disable excludes defined in [main] in dnf.conf.
- If set to C(repoid), disable excludes defined for given repo id.
- If set to V(all), disables all excludes.
- If set to V(main), disable excludes defined in [main] in dnf.conf.
- If set to V(repoid), disable excludes defined for given repo id.
type: str
validate_certs:
description:
- This is effectively a no-op in the dnf5 module as dnf5 itself handles downloading a https url as the source of the rpm,
but is an accepted parameter for feature parity/compatibility with the I(yum) module.
but is an accepted parameter for feature parity/compatibility with the M(ansible.builtin.yum) module.
type: bool
default: "yes"
sslverify:
description:
- Disables SSL validation of the repository server for this transaction.
- This should be set to C(false) if one of the configured repositories is using an untrusted or self-signed certificate.
- This should be set to V(false) if one of the configured repositories is using an untrusted or self-signed certificate.
type: bool
default: "yes"
allow_downgrade:
@ -176,7 +176,7 @@ options:
install_repoquery:
description:
- This is effectively a no-op in DNF as it is not needed with DNF, but is an accepted parameter for feature
parity/compatibility with the I(yum) module.
parity/compatibility with the M(ansible.builtin.yum) module.
type: bool
default: "yes"
download_only:
@ -199,11 +199,11 @@ options:
download_dir:
description:
- Specifies an alternate directory to store packages.
- Has an effect only if I(download_only) is specified.
- Has an effect only if O(download_only) is specified.
type: str
allowerasing:
description:
- If C(true) it allows erasing of installed packages to resolve dependencies.
- If V(true) it allows erasing of installed packages to resolve dependencies.
required: false
type: bool
default: "no"

2
lib/ansible/modules/dpkg_selections.py
Unescape Escape View File

@ -39,7 +39,7 @@ attributes:
support: full
platforms: debian
notes:
- This module won't cause any packages to be installed/removed/purged, use the C(apt) module for that.
- This module will not cause any packages to be installed/removed/purged, use the M(ansible.builtin.apt) module for that.
'''
EXAMPLES = '''
- name: Prevent python from being upgraded

6
lib/ansible/modules/expect.py
Unescape Escape View File

@ -13,7 +13,7 @@ module: expect
version_added: '2.0'
short_description: Executes a command and responds to prompts
description:
- The C(expect) module executes a command and responds to prompts.
- The M(ansible.builtin.expect) module executes a command and responds to prompts.
- The given command will be executed on all selected nodes. It will not be
processed through the shell, so variables like C($HOME) and operations
like C("<"), C(">"), C("|"), and C("&") will not work.
@ -46,7 +46,7 @@ options:
type: int
description:
- Amount of time in seconds to wait for the expected strings. Use
C(null) to disable timeout.
V(null) to disable timeout.
default: 30
echo:
description:
@ -69,7 +69,7 @@ notes:
- If you want to run a command through the shell (say you are using C(<),
C(>), C(|), and so on), you must specify a shell in the command such as
C(/bin/bash -c "/path/to/something | grep else").
- The question, or key, under I(responses) is a python regex match. Case
- The question, or key, under O(responses) is a python regex match. Case
insensitive searches are indicated with a prefix of C(?i).
- The C(pexpect) library used by this module operates with a search window
of 2000 bytes, and does not use a multiline regex match. To perform a

14
lib/ansible/modules/fetch.py
Unescape Escape View File

@ -16,7 +16,7 @@ short_description: Fetch files from remote nodes
description:
- This module works like M(ansible.builtin.copy), but in reverse.
- It is used for fetching files from remote machines and storing them locally in a file tree, organized by hostname.
- Files that already exist at I(dest) will be overwritten if they are different than the I(src).
- Files that already exist at O(dest) will be overwritten if they are different than the O(src).
- This module is also supported for Windows targets.
version_added: '0.2'
options:
@ -29,16 +29,16 @@ options:
dest:
description:
- A directory to save the file into.
- For example, if the I(dest) directory is C(/backup) a I(src) file named C(/etc/profile) on host
- For example, if the O(dest) directory is C(/backup) a O(src) file named C(/etc/profile) on host
C(host.example.com), would be saved into C(/backup/host.example.com/etc/profile).
The host name is based on the inventory name.
required: yes
fail_on_missing:
version_added: '1.1'
description:
- When set to C(true), the task will fail if the remote file cannot be read for any reason.
- When set to V(true), the task will fail if the remote file cannot be read for any reason.
- Prior to Ansible 2.5, setting this would only fail if the source file was missing.
- The default was changed to C(true) in Ansible 2.5.
- The default was changed to V(true) in Ansible 2.5.
type: bool
default: yes
validate_checksum:
@ -51,7 +51,7 @@ options:
version_added: '1.2'
description:
- Allows you to override the default behavior of appending hostname/path/to/file to the destination.
- If C(dest) ends with '/', it will use the basename of the source file, similar to the copy module.
- If O(dest) ends with '/', it will use the basename of the source file, similar to the copy module.
- This can be useful if working with a single host, or if retrieving files that are uniquely named per host.
- If using multiple hosts with the same filename, the file will be overwritten for each host.
type: bool
@ -85,10 +85,10 @@ notes:
remote or local hosts causing a C(MemoryError). Due to this it is
advisable to run this module without C(become) whenever possible.
- Prior to Ansible 2.5 this module would not fail if reading the remote
file was impossible unless C(fail_on_missing) was set.
file was impossible unless O(fail_on_missing) was set.
- In Ansible 2.5 or later, playbook authors are encouraged to use
C(fail_when) or C(ignore_errors) to get this ability. They may
also explicitly set C(fail_on_missing) to C(false) to get the
also explicitly set O(fail_on_missing) to V(false) to get the
non-failing behaviour.
seealso:
- module: ansible.builtin.copy

58
lib/ansible/modules/file.py
Unescape Escape View File

@ -17,7 +17,7 @@ extends_documentation_fragment: [files, action_common_attributes]
description:
- Set attributes of files, directories, or symlinks and their targets.
- Alternatively, remove files, symlinks or directories.
- Many other modules support the same options as the C(file) module - including M(ansible.builtin.copy),
- Many other modules support the same options as the M(ansible.builtin.file) module - including M(ansible.builtin.copy),
M(ansible.builtin.template), and M(ansible.builtin.assemble).
- For Windows targets, use the M(ansible.windows.win_file) module instead.
options:
@ -29,35 +29,35 @@ options:
aliases: [ dest, name ]
state:
description:
- If C(absent), directories will be recursively deleted, and files or symlinks will
- If V(absent), directories will be recursively deleted, and files or symlinks will
be unlinked. In the case of a directory, if C(diff) is declared, you will see the files and folders deleted listed
under C(path_contents). Note that C(absent) will not cause C(file) to fail if the C(path) does
under C(path_contents). Note that V(absent) will not cause M(ansible.builtin.file) to fail if the O(path) does
not exist as the state did not change.
- If C(directory), all intermediate subdirectories will be created if they
- If V(directory), all intermediate subdirectories will be created if they
do not exist. Since Ansible 1.7 they will be created with the supplied permissions.
- If C(file), with no other options, returns the current state of C(path).
- If C(file), even with other options (such as C(mode)), the file will be modified if it exists but will NOT be created if it does not exist.
Set to C(touch) or use the M(ansible.builtin.copy) or M(ansible.builtin.template) module if you want to create the file if it does not exist.
- If C(hard), the hard link will be created or changed.
- If C(link), the symbolic link will be created or changed.
- If C(touch) (new in 1.4), an empty file will be created if the file does not
- If V(file), with no other options, returns the current state of C(path).
- If V(file), even with other options (such as O(mode)), the file will be modified if it exists but will NOT be created if it does not exist.
Set to V(touch) or use the M(ansible.builtin.copy) or M(ansible.builtin.template) module if you want to create the file if it does not exist.
- If V(hard), the hard link will be created or changed.
- If V(link), the symbolic link will be created or changed.
- If V(touch) (new in 1.4), an empty file will be created if the file 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).
- Default is the current state of the file if it exists, C(directory) if C(recurse=yes), or C(file) otherwise.
modification times (similar to the way V(touch) works from the command line).
- Default is the current state of the file if it exists, V(directory) if O(recurse=yes), or V(file) otherwise.
type: str
choices: [ absent, directory, file, hard, link, touch ]
src:
description:
- Path of the file to link to.
- This applies only to C(state=link) and C(state=hard).
- For C(state=link), this will also accept a non-existing path.
- Relative paths are relative to the file being created (C(path)) which is how
- This applies only to O(state=link) and O(state=hard).
- For O(state=link), this will also accept a non-existing path.
- Relative paths are relative to the file being created (O(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.
- This applies only when C(state) is set to C(directory).
- This applies only when O(state) is set to V(directory).
type: bool
default: no
version_added: '1.1'
@ -66,27 +66,27 @@ options:
- >
Force the creation of the symlinks in two cases: the source file does
not exist (but will appear later); the destination exists and is a file (so, we need to unlink the
C(path) file and create symlink to the C(src) file in place of it).
O(path) file and create symlink to the O(src) file in place of it).
type: bool
default: no
follow:
description:
- This flag indicates that filesystem links, if they exist, should be followed.
- I(follow=yes) and I(state=link) can modify I(src) when combined with parameters such as I(mode).
- Previous to Ansible 2.5, this was C(false) by default.
- O(follow=yes) and O(state=link) can modify O(src) when combined with parameters such as O(mode).
- Previous to Ansible 2.5, this was V(false) by default.
type: bool
default: yes
version_added: '1.8'
modification_time:
description:
- 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).
- Should be V(preserve) when no modification is required, C(YYYYMMDDHHMM.SS) when using default time format, or V(now).
- Default is None meaning that V(preserve) is the default for O(state=[file,directory,link,hard]) and V(now) is default for O(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.
- When used with O(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"
@ -94,13 +94,13 @@ options:
access_time:
description:
- 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).
- Should be V(preserve) when no modification is required, C(YYYYMMDDHHMM.SS) when using default time format, or V(now).
- Default is V(None) meaning that V(preserve) is the default for O(state=[file,directory,link,hard]) and V(now) is default for O(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.
- When used with O(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"
@ -216,13 +216,13 @@ EXAMPLES = r'''
'''
RETURN = r'''
dest:
description: Destination file/path, equal to the value passed to I(path).
returned: state=touch, state=hard, state=link
description: Destination file/path, equal to the value passed to O(path).
returned: O(state=touch), O(state=hard), O(state=link)
type: str
sample: /path/to/file.txt
path:
description: Destination file/path, equal to the value passed to I(path).
returned: state=absent, state=directory, state=file
description: Destination file/path, equal to the value passed to O(path).
returned: O(state=absent), O(state=directory), O(state=file)
type: str
sample: /path/to/file.txt
'''

30
lib/ansible/modules/find.py
Unescape Escape View File

@ -30,7 +30,7 @@ options:
patterns:
default: []
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 O(use_regex) option.
- The patterns restrict the list of files to be returned to those whose basenames match at
least one of the patterns specified. Multiple patterns can be specified using a list.
- The pattern is matched against the file base name, excluding the directory.
@ -40,14 +40,14 @@ options:
- This parameter expects a list, which can be either comma separated or YAML. If any of the
patterns contain a comma, make sure to put them in a list to avoid splitting the patterns
in undesirable ways.
- Defaults to C(*) when I(use_regex=False), or C(.*) when I(use_regex=True).
- Defaults to V(*) when O(use_regex=False), or V(.*) when O(use_regex=True).
type: list
aliases: [ pattern ]
elements: str
excludes:
description:
- One or more (shell or regex) patterns, which type is controlled by I(use_regex) option.
- Items whose basenames match an I(excludes) pattern are culled from I(patterns) matches.
- One or more (shell or regex) patterns, which type is controlled by O(use_regex) option.
- Items whose basenames match an O(excludes) pattern are culled from O(patterns) matches.
Multiple patterns can be specified using a list.
type: list
aliases: [ exclude ]
@ -56,17 +56,17 @@ options:
contains:
description:
- A regular expression or pattern which should be matched against the file content.
- If I(read_whole_file) is C(true) it matches against the beginning of the line (uses
C(re.match())). If I(read_whole_file) is C(false), it searches anywhere for that pattern
(uses C(re.search())).
- Works only when I(file_type) is C(file).
- If O(read_whole_file) is V(true) it matches against the beginning of the line (uses
V(re.match(\))). If O(read_whole_file) is V(false), it searches anywhere for that pattern
(uses V(re.search(\))).
- Works only when O(file_type) is V(file).
type: str
read_whole_file:
description:
- When doing a C(contains) search, determines whether the whole file should be read into
memory or if the regex should be applied to the file line-by-line.
- Setting this to C(true) can have performance and memory implications for large files.
- This uses C(re.search()) instead of C(re.match()).
- This uses V(re.search(\)) instead of V(re.match(\)).
type: bool
default: false
version_added: "2.11"
@ -105,29 +105,29 @@ options:
default: mtime
hidden:
description:
- Set this to C(true) to include hidden files, otherwise they will be ignored.
- Set this to V(true) to include hidden files, otherwise they will be ignored.
type: bool
default: no
follow:
description:
- Set this to C(true) to follow symlinks in path for systems with python 2.6+.
- Set this to V(true) to follow symlinks in path for systems with python 2.6+.
type: bool
default: no
get_checksum:
description:
- Set this to C(true) to retrieve a file's SHA1 checksum.
- Set this to V(true) to retrieve a file's SHA1 checksum.
type: bool
default: no
use_regex:
description:
- If C(false), the patterns are file globs (shell).
- If C(true), they are python regexes.
- If V(false), the patterns are file globs (shell).
- If V(true), they are python regexes.
type: bool
default: no
depth:
description:
- Set the maximum number of levels to descend into.
- Setting recurse to C(false) will override this value, which is effectively depth 1.
- Setting recurse to V(false) will override this value, which is effectively depth 1.
- Default is unlimited depth.
type: int
version_added: "2.6"

2
lib/ansible/modules/gather_facts.py
Unescape Escape View File

@ -33,7 +33,7 @@ attributes:
action:
support: full
async:
details: while this action does not support the task 'async' keywords it can do its own parallel processing using the C(parallel) option.
details: while this action does not support the task 'async' keywords it can do its own parallel processing using the O(parallel) option.
support: none
bypass_host_loop:
support: none

44
lib/ansible/modules/get_url.py
Unescape Escape View File

@ -29,7 +29,7 @@ options:
ciphers:
description:
- SSL/TLS Ciphers to use for the request
- 'When a list is provided, all ciphers are joined in order with C(:)'
- 'When a list is provided, all ciphers are joined in order with V(:)'
- See the L(OpenSSL Cipher List Format,https://www.openssl.org/docs/manmaster/man1/openssl-ciphers.html#CIPHER-LIST-FORMAT)
for more details.
- The available ciphers is dependent on the Python and OpenSSL/LibreSSL versions
@ -50,11 +50,11 @@ options:
dest:
description:
- Absolute path of where to download the file to.
- If C(dest) is a directory, either the server provided filename or, if
- If O(dest) is a directory, either the server provided filename or, if
none provided, the base name of the URL on the remote server will be
used. If a directory, C(force) has no effect.
- If C(dest) is a directory, the file will always be downloaded
(regardless of the C(force) and C(checksum) option), but
used. If a directory, O(force) has no effect.
- If O(dest) is a directory, the file will always be downloaded
(regardless of the O(force) and O(checksum) option), but
replaced only if the contents changed.
type: path
required: true
@ -62,17 +62,17 @@ options:
description:
- Absolute path of where temporary file is downloaded to.
- 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 E(TMPDIR), E(TEMP) or E(TMP) env variables or a platform specific value.
- U(https://docs.python.org/3/library/tempfile.html#tempfile.tempdir)
type: path
version_added: '2.1'
force:
description:
- If C(true) and C(dest) is not a directory, will download the file every
time and replace the file if the contents change. If C(false), the file
- If V(true) and O(dest) is not a directory, will download the file every
time and replace the file if the contents change. If V(false), the file
will only be downloaded if the destination does not exist. Generally
should be C(true) only for small local files.
- Prior to 0.6, this module behaved as if C(true) was the default.
should be V(true) only for small local files.
- Prior to 0.6, this module behaved as if V(true) was the default.
type: bool
default: no
version_added: '0.7'
@ -96,22 +96,22 @@ options:
The choices vary based on Python version and OpenSSL version.
- On systems running in FIPS compliant mode, the ``md5`` algorithm may be unavailable.
- Additionally, if a checksum is passed to this parameter, and the file exist under
the C(dest) location, the I(destination_checksum) would be calculated, and if
checksum equals I(destination_checksum), the file download would be skipped
(unless C(force) is true). If the checksum does not equal I(destination_checksum),
the O(dest) location, the C(destination_checksum) would be calculated, and if
checksum equals C(destination_checksum), the file download would be skipped
(unless O(force) is V(true)). If the checksum does not equal C(destination_checksum),
the destination file is deleted.
type: str
default: ''
version_added: "2.0"
use_proxy:
description:
- if C(false), it will not use a proxy, even if one is defined in
- if V(false), it will not use a proxy, even if one is defined in
an environment variable on the target hosts.
type: bool
default: yes
validate_certs:
description:
- If C(false), SSL certificates will not be validated.
- If V(false), SSL certificates will not be validated.
- This should only be used on personally controlled sites using self-signed certificates.
type: bool
default: yes
@ -132,16 +132,16 @@ options:
url_username:
description:
- The username for use in HTTP basic authentication.
- This parameter can be used without C(url_password) for sites that allow empty passwords.
- Since version 2.8 you can also use the C(username) alias for this option.
- This parameter can be used without O(url_password) for sites that allow empty passwords.
- Since version 2.8 you can also use the O(username) alias for this option.
type: str
aliases: ['username']
version_added: '1.6'
url_password:
description:
- The password for use in HTTP basic authentication.
- If the C(url_username) parameter is not specified, the C(url_password) parameter will not be used.
- Since version 2.8 you can also use the 'password' alias for this option.
- If the O(url_username) parameter is not specified, the O(url_password) parameter will not be used.
- Since version 2.8 you can also use the O(password) alias for this option.
type: str
aliases: ['password']
version_added: '1.6'
@ -157,13 +157,13 @@ options:
client_cert:
description:
- PEM formatted certificate chain file to be used for SSL client authentication.
- This file can also include the key as well, and if the key is included, C(client_key) is not required.
- This file can also include the key as well, and if the key is included, O(client_key) is not required.
type: path
version_added: '2.4'
client_key:
description:
- PEM formatted file that contains your private key to be used for SSL client authentication.
- If C(client_cert) contains both the certificate and key, this option is not required.
- If O(client_cert) contains both the certificate and key, this option is not required.
type: path
version_added: '2.4'
http_agent:
@ -185,7 +185,7 @@ options:
- Use GSSAPI to perform the authentication, typically this is for Kerberos or Kerberos through Negotiate
authentication.
- Requires the Python library L(gssapi,https://github.com/pythongssapi/python-gssapi) to be installed.
- Credentials for GSSAPI can be specified with I(url_username)/I(url_password) or with the GSSAPI env var
- Credentials for GSSAPI can be specified with O(url_username)/O(url_password) or with the GSSAPI env var
C(KRB5CCNAME) that specified a custom Kerberos credential cache.
- NTLM authentication is I(not) supported even if the GSSAPI mech for NTLM has been installed.
type: bool

6
lib/ansible/modules/getent.py
Unescape Escape View File

@ -13,7 +13,7 @@ module: getent
short_description: A wrapper to the unix getent utility
description:
- Runs getent against one of its various databases and returns information into
the host's facts, in a getent_<database> prefixed variable.
the host's facts, in a C(getent_<database>) prefixed variable.
version_added: "1.8"
options:
database:
@ -35,12 +35,12 @@ options:
version_added: "2.9"
split:
description:
- Character used to split the database values into lists/arrays such as C(:) or C(\t),
- Character used to split the database values into lists/arrays such as V(:) or V(\\t),
otherwise it will try to pick one depending on the database.
type: str
fail_key:
description:
- If a supplied key is missing this will make the task fail if C(true).
- If a supplied key is missing this will make the task fail if V(true).
type: bool
default: 'yes'
extends_documentation_fragment:

50
lib/ansible/modules/git.py
Unescape Escape View File

@ -29,15 +29,15 @@ options:
description:
- The path of where the repository should be checked out. This
is equivalent to C(git clone [repo_url] [directory]). The repository
named in I(repo) is not appended to this path and the destination directory must be empty. This
parameter is required, unless I(clone) is set to C(false).
named in O(repo) is not appended to this path and the destination directory must be empty. This
parameter is required, unless O(clone) is set to V(false).
type: path
required: true
version:
description:
- What version of the repository to check out. This can be
the literal string C(HEAD), a branch name, a tag name.
It can also be a I(SHA-1) hash, in which case I(refspec) needs
the literal string V(HEAD), a branch name, a tag name.
It can also be a I(SHA-1) hash, in which case O(refspec) needs
to be specified if the given revision is not already available.
type: str
default: "HEAD"
@ -45,7 +45,7 @@ options:
description:
- Will ensure or not that "-o StrictHostKeyChecking=no" is present as an ssh option.
- Be aware that this disables a protection against MITM attacks.
- Those using OpenSSH >= 7.5 might want to set I(ssh_opts) to 'StrictHostKeyChecking=accept-new'
- Those using OpenSSH >= 7.5 might want to set O(ssh_opts) to V(StrictHostKeyChecking=accept-new)
instead, it does not remove the MITM issue but it does restrict it to the first attempt.
type: bool
default: 'no'
@ -54,7 +54,7 @@ options:
description:
- As of OpenSSH 7.5, "-o StrictHostKeyChecking=accept-new" can be
used which is safer and will only accepts host keys which are
not present or are the same. if C(true), ensure that
not present or are the same. if V(true), ensure that
"-o StrictHostKeyChecking=accept-new" is present as an ssh option.
type: bool
default: 'no'
@ -62,12 +62,12 @@ options:
ssh_opts:
description:
- Options git will pass to ssh when used as protocol, it works via C(git)'s
GIT_SSH/GIT_SSH_COMMAND environment variables.
- For older versions it appends GIT_SSH_OPTS (specific to this module) to the
E(GIT_SSH)/E(GIT_SSH_COMMAND) environment variables.
- For older versions it appends E(GIT_SSH_OPTS) (specific to this module) to the
variables above or via a wrapper script.
- Other options can add to this list, like I(key_file) and I(accept_hostkey).
- Other options can add to this list, like O(key_file) and O(accept_hostkey).
- An example value could be "-o StrictHostKeyChecking=no" (although this particular
option is better set by I(accept_hostkey)).
option is better set by O(accept_hostkey)).
- The module ensures that 'BatchMode=yes' is always present to avoid prompts.
type: str
version_added: "1.5"
@ -75,7 +75,7 @@ options:
key_file:
description:
- Specify an optional private key file path, on the target host, to use for the checkout.
- This ensures 'IdentitiesOnly=yes' is present in ssh_opts.
- This ensures 'IdentitiesOnly=yes' is present in O(ssh_opts).
type: path
version_added: "1.5"
reference:
@ -100,29 +100,29 @@ options:
version_added: "1.9"
force:
description:
- If C(true), any modified files in the working
- If V(true), any modified files in the working
repository will be discarded. Prior to 0.7, this was always
C(true) and could not be disabled. Prior to 1.9, the default was
C(true).
V(true) and could not be disabled. Prior to 1.9, the default was
V(true).
type: bool
default: 'no'
version_added: "0.7"
depth:
description:
- Create a shallow clone with a history truncated to the specified
number or revisions. The minimum possible value is C(1), otherwise
number or revisions. The minimum possible value is V(1), otherwise
ignored. Needs I(git>=1.9.1) to work correctly.
type: int
version_added: "1.2"
clone:
description:
- If C(false), do not clone the repository even if it does not exist locally.
- If V(false), do not clone the repository even if it does not exist locally.
type: bool
default: 'yes'
version_added: "1.9"
update:
description:
- If C(false), do not retrieve new revisions from the origin repository.
- If V(false), do not retrieve new revisions from the origin repository.
- Operations like archive will work on the existing (old) repository and might
not respond to changes to the options version or remote.
type: bool
@ -136,7 +136,7 @@ options:
version_added: "1.4"
bare:
description:
- If C(true), repository will be created as a bare repo, otherwise
- If V(true), repository will be created as a bare repo, otherwise
it will be a standard repo with a workspace.
type: bool
default: 'no'
@ -150,7 +150,7 @@ options:
recursive:
description:
- If C(false), repository will be cloned without the --recursive
- If V(false), repository will be cloned without the C(--recursive)
option, skipping sub-modules.
type: bool
default: 'yes'
@ -165,10 +165,10 @@ options:
track_submodules:
description:
- If C(true), submodules will track the latest commit on their
- If V(true), submodules will track the latest commit on their
master branch (or other branch specified in .gitmodules). If
C(false), submodules will be kept at the revision specified by the
main project. This is equivalent to specifying the --remote flag
V(false), submodules will be kept at the revision specified by the
main project. This is equivalent to specifying the C(--remote) flag
to git submodule update.
type: bool
default: 'no'
@ -176,7 +176,7 @@ options:
verify_commit:
description:
- If C(true), when cloning or checking out a I(version) verify the
- If V(true), when cloning or checking out a O(version) verify the
signature of a GPG signed commit. This requires git version>=2.1.0
to be installed. The commit MUST be signed and the public key MUST
be present in the GPG keyring.
@ -197,7 +197,7 @@ options:
archive_prefix:
description:
- Specify a prefix to add to each file path in archive. Requires I(archive) to be specified.
- Specify a prefix to add to each file path in archive. Requires O(archive) to be specified.
version_added: "2.10"
type: str
@ -212,7 +212,7 @@ options:
description:
- A list of trusted GPG fingerprints to compare to the fingerprint of the
GPG-signed commit.
- Only used when I(verify_commit=yes).
- Only used when O(verify_commit=yes).
- Use of this feature requires Git 2.6+ due to its reliance on git's C(--raw) flag to C(verify-commit) and C(verify-tag).
type: list
elements: str

8
lib/ansible/modules/group.py
Unescape Escape View File

@ -44,7 +44,7 @@ options:
version_added: "2.15"
system:
description:
- If I(yes), indicates that the group created is a system group.
- If V(yes), indicates that the group created is a system group.
type: bool
default: no
local:
@ -58,7 +58,7 @@ options:
version_added: "2.6"
non_unique:
description:
- This option allows to change the group ID to a non-unique value. Requires C(gid).
- This option allows to change the group ID to a non-unique value. Requires O(gid).
- Not supported on macOS or BusyBox distributions.
type: bool
default: no
@ -94,7 +94,7 @@ EXAMPLES = '''
RETURN = r'''
gid:
description: Group ID of the group.
returned: When C(state) is 'present'
returned: When O(state) is C(present)
type: int
sample: 1001
name:
@ -109,7 +109,7 @@ state:
sample: 'absent'
system:
description: Whether the group is a system group or not.
returned: When C(state) is 'present'
returned: When O(state) is C(present)
type: bool
sample: False
'''

10
lib/ansible/modules/include_role.py
Unescape Escape View File

@ -16,7 +16,7 @@ description:
- Dynamically loads and executes a specified role as a task.
- May be used only where Ansible tasks are allowed - inside C(pre_tasks), C(tasks), or C(post_tasks) play objects, or as a task inside a role.
- Task-level keywords, loops, and conditionals apply only to the C(include_role) statement itself.
- To apply keywords to the tasks within the role, pass them using the C(apply) option or use M(ansible.builtin.import_role) instead.
- To apply keywords to the tasks within the role, pass them using the O(apply) option or use M(ansible.builtin.import_role) instead.
- Ignores some keywords, like C(until) and C(retries).
- This module is also supported for Windows targets.
- Does not work in handlers.
@ -24,7 +24,7 @@ version_added: "2.2"
options:
apply:
description:
- Accepts a hash of task keywords (e.g. C(tags), C(become)) that will be applied to all tasks within the included role.
- Accepts a hash of task keywords (for example C(tags), C(become)) that will be applied to all tasks within the included role.
version_added: '2.7'
name:
description:
@ -53,9 +53,9 @@ options:
default: yes
public:
description:
- This option dictates whether the role's C(vars) and C(defaults) are exposed to the play. If set to C(true)
- This option dictates whether the role's C(vars) and C(defaults) are exposed to the play. If set to V(true)
the variables will be available to tasks following the C(include_role) task. This functionality differs from
standard variable exposure for roles listed under the C(roles) header or C(import_role) as they are exposed
standard variable exposure for roles listed under the C(roles) header or M(ansible.builtin.import_role) as they are exposed
to the play at playbook parsing time, and available to earlier roles and tasks as well.
type: bool
default: no
@ -85,7 +85,7 @@ attributes:
support: none
notes:
- Handlers and are made available to the whole play.
- After Ansible 2.4, you can use M(ansible.builtin.import_role) for C(static) behaviour and this action for C(dynamic) one.
- After Ansible 2.4, you can use M(ansible.builtin.import_role) for B(static) behaviour and this action for B(dynamic) one.
seealso:
- module: ansible.builtin.import_playbook
- module: ansible.builtin.import_role

4
lib/ansible/modules/include_tasks.py
Unescape Escape View File

@ -23,14 +23,14 @@ options:
version_added: '2.7'
apply:
description:
- Accepts a hash of task keywords (e.g. C(tags), C(become)) that will be applied to the tasks within the include.
- Accepts a hash of task keywords (for example C(tags), C(become)) that will be applied to the tasks within the include.
type: str
version_added: '2.7'
free-form:
description:
- |
Specifies the name of the imported file directly without any other option C(- include_tasks: file.yml).
- Is the equivalent of specifying an argument for the I(file) parameter.
- Is the equivalent of specifying an argument for the O(file) parameter.
- Most keywords, including loop, with_items, and conditionals, apply to this statement unlike M(ansible.builtin.import_tasks).
- The do-until loop is not supported.
extends_documentation_fragment:

10
lib/ansible/modules/include_vars.py
Unescape Escape View File

@ -40,7 +40,7 @@ options:
version_added: "2.2"
depth:
description:
- When using C(dir), this module will, by default, recursively go through each sub directory and load up the
- When using O(dir), this module will, by default, recursively go through each sub directory and load up the
variables. By explicitly setting the depth, this module will only go as deep as the depth.
type: int
default: 0
@ -58,7 +58,7 @@ options:
version_added: "2.2"
extensions:
description:
- List of file extensions to read when using C(dir).
- List of file extensions to read when using O(dir).
type: list
elements: str
default: [ json, yaml, yml ]
@ -73,9 +73,9 @@ options:
version_added: "2.7"
hash_behaviour:
description:
- If set to C(merge), merges existing hash variables instead of overwriting them.
- If omitted C(null), the behavior falls back to the global I(hash_behaviour) configuration.
- This option is self-contained and does not apply to individual files in C(dir). You can use a loop to apply C(hash_behaviour) per file.
- If set to V(merge), merges existing hash variables instead of overwriting them.
- If omitted (V(null)), the behavior falls back to the global C(hash_behaviour) configuration.
- This option is self-contained and does not apply to individual files in O(dir). You can use a loop to apply O(hash_behaviour) per file.
default: null
type: str
choices: ["replace", "merge"]

70
lib/ansible/modules/iptables.py
Unescape Escape View File

@ -17,7 +17,7 @@ author:
- Linus Unnebäck (@LinusU) <linus@folkdatorn.se>
- Sébastien DA ROCHA (@sebastiendarocha)
description:
- C(iptables) is used to set up, maintain, and inspect the tables of IP packet
- M(ansible.builtin.iptables) is used to set up, maintain, and inspect the tables of IP packet
filter rules in the Linux kernel.
- This module does not handle the saving and/or loading of rules, but rather
only manipulates the current rules that are present in memory. This is the
@ -61,7 +61,7 @@ options:
rule_num:
description:
- Insert the rule as the given rule number.
- This works only with C(action=insert).
- This works only with O(action=insert).
type: str
version_added: "2.5"
ip_version:
@ -74,18 +74,18 @@ options:
description:
- Specify the iptables chain to modify.
- This could be a user-defined chain or one of the standard iptables chains, like
C(INPUT), C(FORWARD), C(OUTPUT), C(PREROUTING), C(POSTROUTING), C(SECMARK) or C(CONNSECMARK).
V(INPUT), V(FORWARD), V(OUTPUT), V(PREROUTING), V(POSTROUTING), V(SECMARK) or V(CONNSECMARK).
type: str
protocol:
description:
- The protocol of the rule or of the packet to check.
- The specified protocol can be one of C(tcp), C(udp), C(udplite), C(icmp), C(ipv6-icmp) or C(icmpv6),
C(esp), C(ah), C(sctp) or the special keyword C(all), or it can be a numeric value,
- The specified protocol can be one of V(tcp), V(udp), V(udplite), V(icmp), V(ipv6-icmp) or V(icmpv6),
V(esp), V(ah), V(sctp) or the special keyword V(all), or it can be a numeric value,
representing one of these protocols or a different one.
- A protocol name from I(/etc/protocols) is also allowed.
- A C(!) argument before the protocol inverts the test.
- A protocol name from C(/etc/protocols) is also allowed.
- A V(!) argument before the protocol inverts the test.
- The number zero is equivalent to all.
- C(all) will match with all protocols and is taken as default when this option is omitted.
- V(all) will match with all protocols and is taken as default when this option is omitted.
type: str
source:
description:
@ -97,7 +97,7 @@ options:
a remote query such as DNS is a really bad idea.
- The mask can be either a network mask or a plain number, specifying
the number of 1's at the left side of the network mask. Thus, a mask
of 24 is equivalent to 255.255.255.0. A C(!) argument before the
of 24 is equivalent to 255.255.255.0. A V(!) argument before the
address specification inverts the sense of the address.
type: str
destination:
@ -110,13 +110,13 @@ options:
a remote query such as DNS is a really bad idea.
- The mask can be either a network mask or a plain number, specifying
the number of 1's at the left side of the network mask. Thus, a mask
of 24 is equivalent to 255.255.255.0. A C(!) argument before the
of 24 is equivalent to 255.255.255.0. A V(!) argument before the
address specification inverts the sense of the address.
type: str
tcp_flags:
description:
- TCP flags specification.
- C(tcp_flags) expects a dict with the two keys C(flags) and C(flags_set).
- O(tcp_flags) expects a dict with the two keys C(flags) and C(flags_set).
type: dict
version_added: "2.4"
suboptions:
@ -154,7 +154,7 @@ options:
gateway:
description:
- This specifies the IP address of host to send the cloned packets.
- This option is only valid when C(jump) is set to C(TEE).
- This option is only valid when O(jump) is set to V(TEE).
type: str
version_added: "2.8"
log_prefix:
@ -166,7 +166,7 @@ options:
description:
- Logging level according to the syslogd-defined priorities.
- The value can be strings or numbers from 1-8.
- This parameter is only applicable if C(jump) is set to C(LOG).
- This parameter is only applicable if O(jump) is set to V(LOG).
type: str
version_added: "2.8"
choices: [ '0', '1', '2', '3', '4', '5', '6', '7', 'emerg', 'alert', 'crit', 'error', 'warning', 'notice', 'info', 'debug' ]
@ -179,18 +179,18 @@ options:
in_interface:
description:
- Name of an interface via which a packet was received (only for packets
entering the C(INPUT), C(FORWARD) and C(PREROUTING) chains).
- When the C(!) argument is used before the interface name, the sense is inverted.
- If the interface name ends in a C(+), then any interface which begins with
entering the V(INPUT), V(FORWARD) and V(PREROUTING) chains).
- When the V(!) argument is used before the interface name, the sense is inverted.
- If the interface name ends in a V(+), then any interface which begins with
this name will match.
- If this option is omitted, any interface name will match.
type: str
out_interface:
description:
- Name of an interface via which a packet is going to be sent (for
packets entering the C(FORWARD), C(OUTPUT) and C(POSTROUTING) chains).
- When the C(!) argument is used before the interface name, the sense is inverted.
- If the interface name ends in a C(+), then any interface which begins
packets entering the V(FORWARD), V(OUTPUT) and V(POSTROUTING) chains).
- When the V(!) argument is used before the interface name, the sense is inverted.
- If the interface name ends in a V(+), then any interface which begins
with this name will match.
- If this option is omitted, any interface name will match.
type: str
@ -206,14 +206,14 @@ options:
set_counters:
description:
- This enables the administrator to initialize the packet and byte
counters of a rule (during C(INSERT), C(APPEND), C(REPLACE) operations).
counters of a rule (during V(INSERT), V(APPEND), V(REPLACE) operations).
type: str
source_port:
description:
- Source port or port range specification.
- This can either be a service name or a port number.
- An inclusive range can also be specified, using the format C(first:last).
- If the first port is omitted, C(0) is assumed; if the last is omitted, C(65535) is assumed.
- If the first port is omitted, V(0) is assumed; if the last is omitted, V(65535) is assumed.
- If the first port is greater than the second one they will be swapped.
type: str
destination_port:
@ -239,7 +239,7 @@ options:
- This specifies a destination port or range of ports to use, without
this, the destination port is never altered.
- This is only valid if the rule also specifies one of the protocol
C(tcp), C(udp), C(dccp) or C(sctp).
V(tcp), V(udp), V(dccp) or V(sctp).
type: str
to_destination:
description:
@ -266,14 +266,14 @@ options:
description:
- This allows specifying a DSCP mark to be added to packets.
It takes either an integer or hex value.
- Mutually exclusive with C(set_dscp_mark_class).
- Mutually exclusive with O(set_dscp_mark_class).
type: str
version_added: "2.1"
set_dscp_mark_class:
description:
- This allows specifying a predefined DiffServ class which will be
translated to the corresponding DSCP mark.
- Mutually exclusive with C(set_dscp_mark).
- Mutually exclusive with O(set_dscp_mark).
type: str
version_added: "2.1"
comment:
@ -283,7 +283,7 @@ options:
ctstate:
description:
- A list of the connection states to match in the conntrack module.
- Possible values are C(INVALID), C(NEW), C(ESTABLISHED), C(RELATED), C(UNTRACKED), C(SNAT), C(DNAT).
- Possible values are V(INVALID), V(NEW), V(ESTABLISHED), V(RELATED), V(UNTRACKED), V(SNAT), V(DNAT).
type: list
elements: str
default: []
@ -301,7 +301,7 @@ options:
description:
- Specifies a set name which can be defined by ipset.
- Must be used together with the match_set_flags parameter.
- When the C(!) argument is prepended then it inverts the rule.
- When the V(!) argument is prepended then it inverts the rule.
- Uses the iptables set extension.
type: str
version_added: "2.11"
@ -317,8 +317,8 @@ options:
description:
- Specifies the maximum average number of matches to allow per second.
- The number can specify units explicitly, using C(/second), C(/minute),
C(/hour) or C(/day), or parts of them (so C(5/second) is the same as
C(5/s)).
C(/hour) or C(/day), or parts of them (so V(5/second) is the same as
V(5/s)).
type: str
limit_burst:
description:
@ -362,10 +362,10 @@ options:
description:
- Set the policy for the chain to the given target.
- Only built-in chains can have policies.
- This parameter requires the C(chain) parameter.
- This parameter requires the O(chain) parameter.
- If you specify this parameter, all other parameters will be ignored.
- This parameter is used to set default policy for the given C(chain).
Do not confuse this with C(jump) parameter.
- This parameter is used to set default policy for the given O(chain).
Do not confuse this with O(jump) parameter.
type: str
choices: [ ACCEPT, DROP, QUEUE, RETURN ]
version_added: "2.2"
@ -377,9 +377,9 @@ options:
version_added: "2.10"
chain_management:
description:
- If C(true) and C(state) is C(present), the chain will be created if needed.
- If C(true) and C(state) is C(absent), the chain will be deleted if the only
other parameter passed are C(chain) and optionally C(table).
- If V(true) and O(state) is V(present), the chain will be created if needed.
- If V(true) and O(state) is V(absent), the chain will be deleted if the only
other parameter passed are O(chain) and optionally O(table).
type: bool
default: false
version_added: "2.13"
@ -387,7 +387,7 @@ options:
description:
- This parameter controls the running of the list -action of iptables, which is used internally by the module
- Does not affect the actual functionality. Use this if iptables hangs when creating chain or altering policy
- If C(true), then iptables skips the DNS-lookup of the IP addresses in a chain when it uses the list -action
- If V(true), then iptables skips the DNS-lookup of the IP addresses in a chain when it uses the list -action
- Listing is used internally for example when setting a policy or creting of a chain
type: bool
default: false

12
lib/ansible/modules/known_hosts.py
Unescape Escape View File

@ -11,7 +11,7 @@ DOCUMENTATION = r'''
module: known_hosts
short_description: Add or remove a host from the C(known_hosts) file
description:
- The C(known_hosts) module lets you add or remove a host keys from the C(known_hosts) file.
- The M(ansible.builtin.known_hosts) module lets you add or remove a host keys from the C(known_hosts) file.
- Starting at Ansible 2.2, multiple entries per host are allowed, but only one for each key type supported by ssh.
This is useful if you're going to want to use the M(ansible.builtin.git) module over ssh, for example.
- If you have a very large number of host keys to manage, you will find the M(ansible.builtin.template) module more useful.
@ -22,19 +22,19 @@ options:
description:
- The host to add or remove (must match a host specified in key). It will be converted to lowercase so that ssh-keygen can find it.
- Must match with <hostname> or <ip> present in key attribute.
- For custom SSH port, C(name) needs to specify port as well. See example section.
- For custom SSH port, O(name) needs to specify port as well. See example section.
type: str
required: true
key:
description:
- The SSH public host key, as a string.
- Required if C(state=present), optional when C(state=absent), in which case all keys for the host are removed.
- Required if O(state=present), optional when O(state=absent), in which case all keys for the host are removed.
- The key must be in the right format for SSH (see sshd(8), section "SSH_KNOWN_HOSTS FILE FORMAT").
- Specifically, the key should not match the format that is found in an SSH pubkey file, but should rather have the hostname prepended to a
line that includes the pubkey, the same way that it would appear in the known_hosts file. The value prepended to the line must also match
the value of the name parameter.
- Should be of format C(<hostname[,IP]> ssh-rsa <pubkey>).
- For custom SSH port, C(key) needs to specify port as well. See example section.
- For custom SSH port, O(key) needs to specify port as well. See example section.
type: str
path:
description:
@ -50,8 +50,8 @@ options:
version_added: "2.3"
state:
description:
- I(present) to add the host key.
- I(absent) to remove it.
- V(present) to add the host key.
- V(absent) to remove it.
choices: [ "absent", "present" ]
default: "present"
type: str

64
lib/ansible/modules/lineinfile.py
Unescape Escape View File

@ -25,20 +25,20 @@ options:
path:
description:
- 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 O(dest), O(destfile) and O(name).
type: path
required: true
aliases: [ dest, destfile, name ]
regexp:
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.
- For O(state=present), the pattern to replace if found. Only the last line found will be replaced.
- For O(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 C(insertbefore) or C(insertafter)
added to the file in keeping with O(insertbefore) or O(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.
the line as well as its state after replacement by O(line) to ensure idempotence.
- Uses Python regular expressions. See U(https://docs.python.org/3/library/re.html).
type: str
aliases: [ regex ]
@ -46,12 +46,12 @@ options:
search_string:
description:
- The literal string to look for in every line of the file. This does not have to match the entire line.
- For C(state=present), the line to replace if the string is found in the file. Only the last line found will be replaced.
- For C(state=absent), the line(s) to remove if the string is in the line.
- For O(state=present), the line to replace if the string is found in the file. Only the last line found will be replaced.
- For O(state=absent), the line(s) to remove if the string is in the line.
- If the literal expression is not matched, the line will be
added to the file in keeping with C(insertbefore) or C(insertafter)
added to the file in keeping with O(insertbefore) or O(insertafter)
settings.
- Mutually exclusive with C(backrefs) and C(regexp).
- Mutually exclusive with O(backrefs) and O(regexp).
type: str
version_added: '2.11'
state:
@ -63,53 +63,53 @@ options:
line:
description:
- 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.
- Required for O(state=present).
- If O(backrefs) is set, may contain backreferences that will get
expanded with the O(regexp) capture groups if the regexp matches.
type: str
aliases: [ value ]
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.
- Used with O(state=present).
- If set, O(line) can contain backreferences (both positional and named)
that will get populated if the O(regexp) matches.
- This parameter changes the operation of the module slightly;
C(insertbefore) and C(insertafter) will be ignored, and if the C(regexp)
O(insertbefore) and O(insertafter) will be ignored, and if the O(regexp)
does not 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 O(regexp) does match, the last matching line will be replaced by
the expanded line parameter.
- Mutually exclusive with C(search_string).
- Mutually exclusive with O(search_string).
type: bool
default: no
version_added: "1.1"
insertafter:
description:
- Used with C(state=present).
- Used with O(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.
- A special value is available; V(EOF) for inserting the line at the end of the file.
- If specified regular expression has no matches, EOF will be used instead.
- If C(insertbefore) is set, default value C(EOF) will be ignored.
- 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) or C(insertbefore).
- If O(insertbefore) is set, default value V(EOF) will be ignored.
- If regular expressions are passed to both O(regexp) and O(insertafter), O(insertafter) is only honored if no match for O(regexp) is found.
- May not be used with O(backrefs) or O(insertbefore).
type: str
choices: [ EOF, '*regex*' ]
default: EOF
insertbefore:
description:
- Used with C(state=present).
- Used with O(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 the first match is required, use O(firstmatch=yes).
- A value is available; V(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) or C(insertafter).
- If regular expressions are passed to both O(regexp) and O(insertbefore), O(insertbefore) is only honored if no match for O(regexp) is found.
- May not be used with O(backrefs) or O(insertafter).
type: str
choices: [ BOF, '*regex*' ]
version_added: "1.1"
create:
description:
- Used with C(state=present).
- Used with O(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
@ -122,8 +122,8 @@ options:
default: no
firstmatch:
description:
- Used with C(insertafter) or C(insertbefore).
- If set, C(insertafter) and C(insertbefore) will work with the first line that matches the given regular expression.
- Used with O(insertafter) or O(insertbefore).
- If set, O(insertafter) and O(insertbefore) will work with the first line that matches the given regular expression.
type: bool
default: no
version_added: "2.5"
@ -148,7 +148,7 @@ attributes:
vault:
support: none
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 O(dest) option has been changed to O(path) as default, but O(dest) still works as well.
seealso:
- module: ansible.builtin.blockinfile
- module: ansible.builtin.copy

26
lib/ansible/modules/meta.py
Unescape Escape View File

@ -19,21 +19,21 @@ options:
free_form:
description:
- This module takes a free form command, as a string. There is not an actual option named "free form". See the examples!
- C(flush_handlers) makes Ansible run any handler tasks which have thus far been notified. Ansible inserts these tasks internally at certain
- V(flush_handlers) makes Ansible run any handler tasks which have thus far been notified. Ansible inserts these tasks internally at certain
points to implicitly trigger handler runs (after pre/post tasks, the final role execution, and the main tasks section of your plays).
- C(refresh_inventory) (added in Ansible 2.0) forces the reload of the inventory, which in the case of dynamic inventory scripts means they will be
- V(refresh_inventory) (added in Ansible 2.0) forces the reload of the inventory, which in the case of dynamic inventory scripts means they will be
re-executed. If the dynamic inventory script is using a cache, Ansible cannot know this and has no way of refreshing it (you can disable the cache
or, if available for your specific inventory datasource (e.g. aws), you can use the an inventory plugin instead of an inventory script).
This is mainly useful when additional hosts are created and users wish to use them instead of using the M(ansible.builtin.add_host) module.
- C(noop) (added in Ansible 2.0) This literally does 'nothing'. It is mainly used internally and not recommended for general use.
- C(clear_facts) (added in Ansible 2.1) causes the gathered facts for the hosts specified in the play's list of hosts to be cleared,
- V(noop) (added in Ansible 2.0) This literally does 'nothing'. It is mainly used internally and not recommended for general use.
- V(clear_facts) (added in Ansible 2.1) causes the gathered facts for the hosts specified in the play's list of hosts to be cleared,
including the fact cache.
- C(clear_host_errors) (added in Ansible 2.1) clears the failed state (if any) from hosts specified in the play's list of hosts.
- C(end_play) (added in Ansible 2.2) causes the play to end without failing the host(s). Note that this affects all hosts.
- C(reset_connection) (added in Ansible 2.3) interrupts a persistent connection (i.e. ssh + control persist)
- C(end_host) (added in Ansible 2.8) is a per-host variation of C(end_play). Causes the play to end for the current host without failing it.
- C(end_batch) (added in Ansible 2.12) causes the current batch (see C(serial)) to end without failing the host(s).
Note that with C(serial=0) or undefined this behaves the same as C(end_play).
- V(clear_host_errors) (added in Ansible 2.1) clears the failed state (if any) from hosts specified in the play's list of hosts.
- V(end_play) (added in Ansible 2.2) causes the play to end without failing the host(s). Note that this affects all hosts.
- V(reset_connection) (added in Ansible 2.3) interrupts a persistent connection (i.e. ssh + control persist)
- V(end_host) (added in Ansible 2.8) is a per-host variation of V(end_play). Causes the play to end for the current host without failing it.
- V(end_batch) (added in Ansible 2.12) causes the current batch (see C(serial)) to end without failing the host(s).
Note that with C(serial=0) or undefined this behaves the same as V(end_play).
choices: [ clear_facts, clear_host_errors, end_host, end_play, flush_handlers, noop, refresh_inventory, reset_connection, end_batch ]
required: true
extends_documentation_fragment:
@ -61,12 +61,12 @@ attributes:
details: Only some options support conditionals and when they do they act 'bypassing the host loop', taking the values from first available host
support: partial
connection:
details: Most options in this action do not use a connection, except C(reset_connection) which still does not connect to the remote
details: Most options in this action do not use a connection, except V(reset_connection) which still does not connect to the remote
support: partial
notes:
- C(clear_facts) will remove the persistent facts from M(ansible.builtin.set_fact) using C(cacheable=True),
- V(clear_facts) will remove the persistent facts from M(ansible.builtin.set_fact) using O(ansible.builtin.set_fact#module:cacheable=True),
but not the current host variable it creates for the current run.
- Skipping C(meta) tasks with tags is not supported before Ansible 2.11.
- Skipping M(ansible.builtin.meta) tasks with tags is not supported before Ansible 2.11.
seealso:
- module: ansible.builtin.assert
- module: ansible.builtin.fail

16
lib/ansible/modules/package.py
Unescape Escape View File

@ -18,8 +18,8 @@ short_description: Generic OS package manager
description:
- This modules manages packages on a target without specifying a package manager module (like M(ansible.builtin.yum), M(ansible.builtin.apt), ...).
It is convenient to use in an heterogeneous environment of machines without having to create a specific task for
each package manager. C(package) calls behind the module for the package manager used by the operating system
discovered by the module M(ansible.builtin.setup). If C(setup) was not yet run, C(package) will run it.
each package manager. M(ansible.builtin.package) calls behind the module for the package manager used by the operating system
discovered by the module M(ansible.builtin.setup). If M(ansible.builtin.setup) was not yet run, M(ansible.builtin.package) will run it.
- This module acts as a proxy to the underlying package manager module. While all arguments will be passed to the
underlying module, not all modules support the same arguments. This documentation only covers the minimum intersection
of module arguments that all packaging modules support.
@ -28,17 +28,17 @@ options:
name:
description:
- Package name, or package specifier with version.
- Syntax varies with package manager. For example C(name-1.0) or C(name=1.0).
- Package names also vary with package manager; this module will not "translate" them per distro. For example C(libyaml-dev), C(libyaml-devel).
- Syntax varies with package manager. For example V(name-1.0) or V(name=1.0).
- Package names also vary with package manager; this module will not "translate" them per distro. For example V(libyaml-dev), V(libyaml-devel).
required: true
state:
description:
- Whether to install (C(present)), or remove (C(absent)) a package.
- You can use other states like C(latest) ONLY if they are supported by the underlying package module(s) executed.
- Whether to install (V(present)), or remove (V(absent)) a package.
- You can use other states like V(latest) ONLY if they are supported by the underlying package module(s) executed.
required: true
use:
description:
- The required package manager module to use (C(yum), C(apt), and so on). The default 'auto' will use existing facts or try to autodetect it.
- The required package manager module to use (V(yum), V(apt), and so on). The default V(auto) will use existing facts or try to autodetect it.
- You should only use this field if the automatic selection is not working for some reason.
default: auto
requirements:
@ -63,7 +63,7 @@ attributes:
details: The support depends on the availability for the specific plugin for each platform and if fact gathering is able to detect it
platforms: all
notes:
- While C(package) abstracts package managers to ease dealing with multiple distributions, package name often differs for the same software.
- While M(ansible.builtin.package) abstracts package managers to ease dealing with multiple distributions, package name often differs for the same software.
'''
EXAMPLES = '''

4
lib/ansible/modules/package_facts.py
Unescape Escape View File

@ -27,8 +27,8 @@ options:
strategy:
description:
- This option controls how the module queries the package managers on the system.
C(first) means it will return only information for the first supported package manager available.
C(all) will return information for all supported and available package managers on the system.
V(first) means it will return only information for the first supported package manager available.
V(all) will return information for all supported and available package managers on the system.
choices: ['first', 'all']
default: 'first'
type: str

4
lib/ansible/modules/pause.py
Unescape Escape View File

@ -30,11 +30,11 @@ options:
prompt:
description:
- Optional text to use for the prompt message.
- User input is only returned if I(seconds=None) and I(minutes=None), otherwise this is just a custom message before playbook execution is paused.
- User input is only returned if O(seconds=None) and O(minutes=None), otherwise this is just a custom message before playbook execution is paused.
echo:
description:
- Controls whether or not keyboard input is shown when typing.
- Only has effect if I(seconds=None) and I(minutes=None).
- Only has effect if O(seconds=None) and O(minutes=None).
type: bool
default: 'yes'
version_added: 2.5

10
lib/ansible/modules/ping.py
Unescape Escape View File

@ -12,9 +12,9 @@ DOCUMENTATION = '''
---
module: ping
version_added: historical
short_description: Try to connect to host, verify a usable python and return C(pong) on success
short_description: Try to connect to host, verify a usable python and return V(pong) on success
description:
- A trivial test module, this module always returns C(pong) on successful
- A trivial test module, this module always returns V(pong) on successful
contact. It does not make sense in playbooks, but it is useful from
C(/usr/bin/ansible) to verify the ability to login and that a usable Python is configured.
- This is NOT ICMP ping, this is just a trivial test module that requires Python on the remote-node.
@ -23,8 +23,8 @@ description:
options:
data:
description:
- Data to return for the C(ping) return value.
- If this parameter is set to C(crash), the module will cause an exception.
- Data to return for the RV(ping) return value.
- If this parameter is set to V(crash), the module will cause an exception.
type: str
default: pong
extends_documentation_fragment:
@ -58,7 +58,7 @@ EXAMPLES = '''
RETURN = '''
ping:
description: Value provided with the data parameter.
description: Value provided with the O(data) parameter.
returned: success
type: str
sample: pong

22
lib/ansible/modules/pip.py
Unescape Escape View File

@ -12,8 +12,8 @@ DOCUMENTATION = '''
module: pip
short_description: Manages Python library dependencies
description:
- "Manage Python library dependencies. To use this module, one of the following keys is required: C(name)
or C(requirements)."
- "Manage Python library dependencies. To use this module, one of the following keys is required: O(name)
or O(requirements)."
version_added: "0.7"
options:
name:
@ -24,7 +24,7 @@ options:
elements: str
version:
description:
- The version number to install of the Python library specified in the I(name) parameter.
- The version number to install of the Python library specified in the O(name) parameter.
type: str
requirements:
description:
@ -53,17 +53,17 @@ options:
virtualenv_command:
description:
- The command or a pathname to the command to create the virtual
environment with. For example C(pyvenv), C(virtualenv),
C(virtualenv2), C(~/bin/virtualenv), C(/usr/local/bin/virtualenv).
environment with. For example V(pyvenv), V(virtualenv),
V(virtualenv2), V(~/bin/virtualenv), V(/usr/local/bin/virtualenv).
type: path
default: virtualenv
version_added: "1.1"
virtualenv_python:
description:
- The Python executable used for creating the virtual environment.
For example C(python3.12), C(python2.7). When not specified, the
For example V(python3.12), V(python2.7). When not specified, the
Python version used to run the ansible module is used. This parameter
should not be used when C(virtualenv_command) is using C(pyvenv) or
should not be used when O(virtualenv_command) is using V(pyvenv) or
the C(-m venv) module.
type: str
version_added: "2.0"
@ -94,9 +94,9 @@ options:
description:
- The explicit executable or pathname for the pip executable,
if different from the Ansible Python interpreter. For
example C(pip3.3), if there are both Python 2.7 and 3.3 installations
example V(pip3.3), if there are both Python 2.7 and 3.3 installations
in the system and you want to run pip for the Python 3.3 installation.
- Mutually exclusive with I(virtualenv) (added in 2.1).
- Mutually exclusive with O(virtualenv) (added in 2.1).
- Does not affect the Ansible Python interpreter.
- The setuptools package must be installed for both the Ansible Python interpreter
and for the version of Python specified by this option.
@ -125,12 +125,12 @@ notes:
installed on the remote host if the virtualenv parameter is specified and
the virtualenv needs to be created.
- Although it executes using the Ansible Python interpreter, the pip module shells out to
run the actual pip command, so it can use any pip version you specify with I(executable).
run the actual pip command, so it can use any pip version you specify with O(executable).
By default, it uses the pip version for the Ansible Python interpreter. For example, pip3 on python 3, and pip2 or pip on python 2.
- The interpreter used by Ansible
(see R(ansible_python_interpreter, ansible_python_interpreter))
requires the setuptools package, regardless of the version of pip set with
the I(executable) option.
the O(executable) option.
requirements:
- pip
- virtualenv

8
lib/ansible/modules/reboot.py
Unescape Escape View File

@ -10,7 +10,7 @@ DOCUMENTATION = r'''
module: reboot
short_description: Reboot a machine
notes:
- C(PATH) is ignored on the remote node when searching for the C(shutdown) command. Use C(search_paths)
- E(PATH) is ignored on the remote node when searching for the C(shutdown) command. Use O(search_paths)
to specify locations to search if the default paths do not work.
description:
- Reboot a machine, wait for it to go down, come back up, and respond to commands.
@ -57,7 +57,7 @@ options:
search_paths:
description:
- Paths to search on the remote machine for the C(shutdown) command.
- I(Only) these paths will be searched for the C(shutdown) command. C(PATH) is ignored in the remote node when searching for the C(shutdown) command.
- I(Only) these paths will be searched for the C(shutdown) command. E(PATH) is ignored in the remote node when searching for the C(shutdown) command.
type: list
elements: str
default: ['/sbin', '/bin', '/usr/sbin', '/usr/bin', '/usr/local/sbin']
@ -75,8 +75,8 @@ options:
description:
- Command to run that reboots the system, including any parameters passed to the command.
- Can be an absolute path to the command or just the command name. If an absolute path to the
command is not given, C(search_paths) on the target system will be searched to find the absolute path.
- This will cause C(pre_reboot_delay), C(post_reboot_delay), and C(msg) to be ignored.
command is not given, O(search_paths) on the target system will be searched to find the absolute path.
- This will cause O(pre_reboot_delay), O(post_reboot_delay), and O(msg) to be ignored.
type: str
default: '[determined based on target OS]'
version_added: '2.11'

27
lib/ansible/modules/replace.py
Unescape Escape View File

@ -39,7 +39,7 @@ options:
path:
description:
- 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 O(dest), O(destfile) and O(name).
type: path
required: true
aliases: [ dest, destfile, name ]
@ -48,13 +48,13 @@ options:
- The regular expression to look for in the contents of the file.
- Uses Python regular expressions; see
U(https://docs.python.org/3/library/re.html).
- Uses MULTILINE mode, which means C(^) and C($) match the beginning
- Uses MULTILINE mode, which means V(^) and V($) 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
- Does not use DOTALL, which means the V(.) 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]).
a negated character set like V([^#]) will also not match newlines.
- In order to exclude newlines, they must be added to the set like V([^#\\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.
@ -65,25 +65,25 @@ options:
- 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.
- Backreferences can be used ambiguously like C(\1), or explicitly like C(\g<1>).
- Backreferences can be used ambiguously like V(\\1), or explicitly like V(\\g<1>).
type: str
default: ''
after:
description:
- If specified, only content after this match will be replaced/removed.
- Can be used in combination with C(before).
- Can be used in combination with O(before).
- Uses Python regular expressions; see
U(https://docs.python.org/3/library/re.html).
- Uses DOTALL, which means the C(.) special character I(can match newlines).
- Uses DOTALL, which means the V(.) special character I(can match newlines).
type: str
version_added: "2.4"
before:
description:
- If specified, only content before this match will be replaced/removed.
- Can be used in combination with C(after).
- Can be used in combination with O(after).
- Uses Python regular expressions; see
U(https://docs.python.org/3/library/re.html).
- Uses DOTALL, which means the C(.) special character I(can match newlines).
- Uses DOTALL, which means the V(.) special character I(can match newlines).
type: str
version_added: "2.4"
backup:
@ -103,11 +103,12 @@ options:
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.
- As of Ansible 2.7.10, the combined use of I(before) and I(after) works properly. If you were relying on the
- As of Ansible 2.3, the O(dest) option has been changed to O(path) as default, but O(dest) still works as well.
- As of Ansible 2.7.10, the combined use of O(before) and O(after) works properly. If you were relying on the
previous incorrect behavior, you may be need to adjust your tasks.
See U(https://github.com/ansible/ansible/issues/31354) for details.
- 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.
- Option O(ignore:follow) has been removed in Ansible 2.5, because this module modifies the contents of the file
so O(ignore:follow=no) does not make sense.
'''
EXAMPLES = r'''

2
lib/ansible/modules/rpm_key.py
Unescape Escape View File

@ -33,7 +33,7 @@ options:
choices: [ absent, present ]
validate_certs:
description:
- If C(false) and the C(key) is a url starting with https, SSL certificates will not be validated.
- If V(false) and the O(key) is a url starting with V(https), SSL certificates will not be validated.
- This should only be used on personally controlled sites using self-signed certificates.
type: bool
default: 'yes'

11
lib/ansible/modules/script.py
Unescape Escape View File

@ -11,8 +11,8 @@ module: script
version_added: "0.9"
short_description: Runs a local script on a remote node after transferring it
description:
- The C(script) module takes the script name followed by a list of space-delimited arguments.
- Either a free form command or C(cmd) parameter is required, see the examples.
- The M(ansible.builtin.script) module takes the script name followed by a list of space-delimited arguments.
- Either a free form command or O(cmd) parameter is required, see the examples.
- The local script at path will be transferred to the remote node and then executed.
- The given script will be processed through the shell environment on the remote node.
- This module does not require python on the remote system, much like the M(ansible.builtin.raw) module.
@ -43,8 +43,9 @@ options:
version_added: "2.6"
notes:
- It is usually preferable to write Ansible modules rather than pushing scripts. Convert your script to an Ansible module for bonus points!
- The C(ssh) connection plugin will force pseudo-tty allocation via C(-tt) when scripts are executed. Pseudo-ttys do not have a stderr channel and all
stderr is sent to stdout. If you depend on separated stdout and stderr result keys, please switch to a copy+command set of tasks instead of using script.
- The P(ansible.builtin.ssh#connection) connection plugin will force pseudo-tty allocation via C(-tt) when scripts are executed.
Pseudo-ttys do not have a stderr channel and all stderr is sent to stdout. If you depend on separated stdout and stderr result keys,
please switch to a copy+command set of tasks instead of using script.
- If the path to the local script contains spaces, it needs to be quoted.
- This module is also supported for Windows targets.
- If the script returns non UTF-8 data, it must be encoded to avoid issues. One option is to pipe
@ -63,7 +64,7 @@ extends_documentation_fragment:
attributes:
check_mode:
support: partial
details: while the script itself is arbitrary and cannot be subject to the check mode semantics it adds C(creates)/C(removes) options as a workaround
details: while the script itself is arbitrary and cannot be subject to the check mode semantics it adds O(creates)/O(removes) options as a workaround
diff_mode:
support: none
platform:

12
lib/ansible/modules/service.py
Unescape Escape View File

@ -21,8 +21,8 @@ description:
- This module is a proxy for multiple more specific service manager modules
(such as M(ansible.builtin.systemd) and M(ansible.builtin.sysvinit)).
This allows management of a heterogeneous environment of machines without creating a specific task for
each service manager. The module to be executed is determined by the I(use) option, which defaults to the
service manager discovered by M(ansible.builtin.setup). If C(setup) was not yet run, this module may run it.
each service manager. The module to be executed is determined by the O(use) option, which defaults to the
service manager discovered by M(ansible.builtin.setup). If M(ansible.builtin.setup) was not yet run, this module may run it.
- For Windows targets, use the M(ansible.windows.win_service) module instead.
options:
name:
@ -32,10 +32,10 @@ options:
required: true
state:
description:
- C(started)/C(stopped) are idempotent actions that will not run
- V(started)/V(stopped) are idempotent actions that will not run
commands unless necessary.
- C(restarted) will always bounce the service.
- C(reloaded) will always reload.
- V(restarted) will always bounce the service.
- V(reloaded) will always reload.
- B(At least one of state and enabled are required.)
- Note that reloaded will start the service if it is not already started,
even if your chosen init system wouldn't normally.
@ -43,7 +43,7 @@ options:
choices: [ reloaded, restarted, started, stopped ]
sleep:
description:
- If the service is being C(restarted) then sleep this many seconds
- If the service is being V(restarted) then sleep this many seconds
between the stop and start command.
- This helps to work around badly-behaving init scripts that exit immediately
after signaling a process to stop.

11
lib/ansible/modules/service_facts.py
Unescape Escape View File

@ -28,7 +28,7 @@ attributes:
platform:
platforms: posix
notes:
- When accessing the C(ansible_facts.services) facts collected by this module,
- When accessing the RV(ansible_facts.services) facts collected by this module,
it is recommended to not use "dot notation" because services can have a C(-)
character in their name which would result in invalid "dot notation", such as
C(ansible_facts.services.zuul-gateway). It is instead recommended to
@ -57,19 +57,20 @@ ansible_facts:
services:
description: States of the services with service name as key.
returned: always
type: complex
type: list
elements: dict
contains:
source:
description:
- Init system of the service.
- One of C(rcctl), C(systemd), C(sysv), C(upstart), C(src).
- One of V(rcctl), V(systemd), V(sysv), V(upstart), V(src).
returned: always
type: str
sample: sysv
state:
description:
- State of the service.
- 'This commonly includes (but is not limited to) the following: C(failed), C(running), C(stopped) or C(unknown).'
- 'This commonly includes (but is not limited to) the following: V(failed), V(running), V(stopped) or V(unknown).'
- Depending on the used init system additional states might be returned.
returned: always
type: str
@ -77,7 +78,7 @@ ansible_facts:
status:
description:
- State of the service.
- Either C(enabled), C(disabled), C(static), C(indirect) or C(unknown).
- Either V(enabled), V(disabled), V(static), V(indirect) or V(unknown).
returned: systemd systems or RedHat/SUSE flavored sysvinit/upstart or OpenBSD
type: str
sample: enabled

4
lib/ansible/modules/set_fact.py
Unescape Escape View File

@ -15,13 +15,13 @@ version_added: "1.2"
description:
- This action allows setting variables associated to the current host.
- These variables will be available to subsequent plays during an ansible-playbook run via the host they were set on.
- Set C(cacheable) to C(true) to save variables across executions using a fact cache.
- Set O(cacheable) to V(true) to save variables across executions using a fact cache.
Variables will keep the set_fact precedence for the current run, but will used 'cached fact' precedence for subsequent ones.
- Per the standard Ansible variable precedence rules, other types of variables have a higher priority, so this value may be overridden.
options:
key_value:
description:
- "The C(set_fact) module takes C(key=value) pairs or C(key: value) (YAML notation) as variables to set in the playbook scope.
- "The M(ansible.builtin.set_fact) module takes C(key=value) pairs or C(key: value) (YAML notation) as variables to set in the playbook scope.
The 'key' is the resulting variable name and the value is, of course, the value of said variable."
- You can create multiple variables at once, by supplying multiple pairs, but do NOT mix notations.
required: true

4
lib/ansible/modules/set_stats.py
Unescape Escape View File

@ -28,7 +28,7 @@ options:
default: no
aggregate:
description:
- Whether the provided value is aggregated to the existing stat C(true) or will replace it C(false).
- Whether the provided value is aggregated to the existing stat V(true) or will replace it V(false).
type: bool
default: yes
extends_documentation_fragment:
@ -55,7 +55,7 @@ attributes:
support: none
notes:
- In order for custom stats to be displayed, you must set C(show_custom_stats) in section C([defaults]) in C(ansible.cfg)
or by defining environment variable C(ANSIBLE_SHOW_CUSTOM_STATS) to C(true). See the C(default) callback plugin for details.
or by defining environment variable C(ANSIBLE_SHOW_CUSTOM_STATS) to V(true). See the P(ansible.builtin.default#callback) callback plugin for details.
version_added: "2.3"
'''

34
lib/ansible/modules/setup.py
Unescape Escape View File

@ -17,24 +17,24 @@ options:
version_added: "2.1"
description:
- "If supplied, restrict the additional facts collected to the given subset.
Possible values: C(all), C(all_ipv4_addresses), C(all_ipv6_addresses), C(apparmor), C(architecture),
C(caps), C(chroot),C(cmdline), C(date_time), C(default_ipv4), C(default_ipv6), C(devices),
C(distribution), C(distribution_major_version), C(distribution_release), C(distribution_version),
C(dns), C(effective_group_ids), C(effective_user_id), C(env), C(facter), C(fips), C(hardware),
C(interfaces), C(is_chroot), C(iscsi), C(kernel), C(local), C(lsb), C(machine), C(machine_id),
C(mounts), C(network), C(ohai), C(os_family), C(pkg_mgr), C(platform), C(processor), C(processor_cores),
C(processor_count), C(python), C(python_version), C(real_user_id), C(selinux), C(service_mgr),
C(ssh_host_key_dsa_public), C(ssh_host_key_ecdsa_public), C(ssh_host_key_ed25519_public),
C(ssh_host_key_rsa_public), C(ssh_host_pub_keys), C(ssh_pub_keys), C(system), C(system_capabilities),
C(system_capabilities_enforced), C(user), C(user_dir), C(user_gecos), C(user_gid), C(user_id),
C(user_shell), C(user_uid), C(virtual), C(virtualization_role), C(virtualization_type).
Possible values: V(all), V(all_ipv4_addresses), V(all_ipv6_addresses), V(apparmor), V(architecture),
V(caps), V(chroot),V(cmdline), V(date_time), V(default_ipv4), V(default_ipv6), V(devices),
V(distribution), V(distribution_major_version), V(distribution_release), V(distribution_version),
V(dns), V(effective_group_ids), V(effective_user_id), V(env), V(facter), V(fips), V(hardware),
V(interfaces), V(is_chroot), V(iscsi), V(kernel), V(local), V(lsb), V(machine), V(machine_id),
V(mounts), V(network), V(ohai), V(os_family), V(pkg_mgr), V(platform), V(processor), V(processor_cores),
V(processor_count), V(python), V(python_version), V(real_user_id), V(selinux), V(service_mgr),
V(ssh_host_key_dsa_public), V(ssh_host_key_ecdsa_public), V(ssh_host_key_ed25519_public),
V(ssh_host_key_rsa_public), V(ssh_host_pub_keys), V(ssh_pub_keys), V(system), V(system_capabilities),
V(system_capabilities_enforced), V(user), V(user_dir), V(user_gecos), V(user_gid), V(user_id),
V(user_shell), V(user_uid), V(virtual), V(virtualization_role), V(virtualization_type).
Can specify a list of values to specify a larger subset.
Values can also be used with an initial C(!) to specify that
that specific subset should not be collected. For instance:
C(!hardware,!network,!virtual,!ohai,!facter). If C(!all) is specified
V(!hardware,!network,!virtual,!ohai,!facter). If V(!all) is specified
then only the min subset is collected. To avoid collecting even the
min subset, specify C(!all,!min). To collect only specific facts,
use C(!all,!min), and specify the particular fact subsets.
min subset, specify V(!all,!min). To collect only specific facts,
use V(!all,!min), and specify the particular fact subsets.
Use the filter parameter if you do not want to display some collected
facts."
type: list
@ -64,12 +64,12 @@ options:
- Path used for local ansible facts (C(*.fact)) - files in this dir
will be run (if executable) and their results be added to C(ansible_local) facts.
If a file is not executable it is read instead.
File/results format can be JSON or INI-format. The default C(fact_path) can be
File/results format can be JSON or INI-format. The default O(fact_path) can be
specified in C(ansible.cfg) for when setup is automatically called as part of
C(gather_facts).
NOTE - For windows clients, the results will be added to a variable named after the
local file (without extension suffix), rather than C(ansible_local).
- Since Ansible 2.1, Windows hosts can use C(fact_path). Make sure that this path
- Since Ansible 2.1, Windows hosts can use O(fact_path). Make sure that this path
exists on the target host. Files in this path MUST be PowerShell scripts C(.ps1)
which outputs an object. This object will be formatted by Ansible as json so the
script should be outputting a raw hashtable, array, or other primitive object.
@ -104,7 +104,7 @@ notes:
remote systems. (See also M(community.general.facter) and M(community.general.ohai).)
- The filter option filters only the first level subkey below ansible_facts.
- If the target host is Windows, you will not currently have the ability to use
C(filter) as this is provided by a simpler implementation of the module.
O(filter) as this is provided by a simpler implementation of the module.
- This module should be run with elevated privileges on BSD systems to gather facts like ansible_product_version.
- For more information about delegated facts,
please check U(https://docs.ansible.com/ansible/latest/user_guide/playbooks_delegation.html#delegating-facts).

6
lib/ansible/modules/shell.py
Unescape Escape View File

@ -16,8 +16,8 @@ DOCUMENTATION = r'''
module: shell
short_description: Execute shell commands on targets
description:
- The C(shell) module takes the command name followed by a list of space-delimited arguments.
- Either a free form command or C(cmd) parameter is required, see the examples.
- The M(ansible.builtin.shell) module takes the command name followed by a list of space-delimited arguments.
- Either a free form command or O(cmd) parameter is required, see the examples.
- It is almost exactly like the M(ansible.builtin.command) module but runs
the command through a shell (C(/bin/sh)) on the remote node.
- For Windows targets, use the M(ansible.windows.win_shell) module instead.
@ -69,7 +69,7 @@ extends_documentation_fragment:
- action_common_attributes.raw
attributes:
check_mode:
details: while the command itself is arbitrary and cannot be subject to the check mode semantics it adds C(creates)/C(removes) options as a workaround
details: while the command itself is arbitrary and cannot be subject to the check mode semantics it adds O(creates)/O(removes) options as a workaround
support: partial
diff_mode:
support: none

16
lib/ansible/modules/stat.py
Unescape Escape View File

@ -36,7 +36,7 @@ options:
description:
- 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)
- The remote host has to support the hashing method specified, V(md5)
can be unavailable if the host is FIPS-140 compliant.
type: str
choices: [ md5, sha1, sha224, sha256, sha384, sha512 ]
@ -47,8 +47,8 @@ options:
description:
- 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 C(mimetype) and C(charset) fields to the return, if possible.
- In Ansible 2.3 this option changed from I(mime) to I(get_mime) and the default changed to C(true).
- This will add both RV(stat.mimetype) and RV(stat.charset) fields to the return, if possible.
- In Ansible 2.3 this option changed from O(mime) to O(get_mime) and the default changed to V(true).
type: bool
default: yes
aliases: [ mime, mime_type, mime-type ]
@ -144,7 +144,7 @@ RETURN = r'''
stat:
description: Dictionary containing all the stat data, some platforms might add additional fields.
returned: success
type: complex
type: dict
contains:
exists:
description: If the destination path actually exists or not
@ -326,15 +326,15 @@ stat:
mimetype:
description: file magic data or mime-type
returned: success, path exists and user can read stats and
installed python supports it and the I(get_mime) option was true, will
return C(unknown) on error.
installed python supports it and the O(get_mime) option was V(true), will
return V(unknown) on error.
type: str
sample: application/pdf; charset=binary
charset:
description: file character set or encoding
returned: success, path exists and user can read stats and
installed python supports it and the I(get_mime) option was true, will
return C(unknown) on error.
installed python supports it and the O(get_mime) option was V(true), will
return V(unknown) on error.
type: str
sample: us-ascii
readable:

18
lib/ansible/modules/subversion.py
Unescape Escape View File

@ -26,7 +26,7 @@ options:
dest:
description:
- Absolute path where the repository should be deployed.
- The destination directory must be specified unless I(checkout=no), I(update=no), and I(export=no).
- The destination directory must be specified unless O(checkout=no), O(update=no), and O(export=no).
type: path
revision:
description:
@ -36,8 +36,8 @@ options:
aliases: [ rev, version ]
force:
description:
- If C(true), modified files will be discarded. If C(false), module will fail if it encounters modified files.
Prior to 1.9 the default was C(true).
- If V(true), modified files will be discarded. If V(false), module will fail if it encounters modified files.
Prior to 1.9 the default was V(true).
type: bool
default: "no"
in_place:
@ -65,32 +65,32 @@ options:
version_added: "1.4"
checkout:
description:
- If C(false), do not check out the repository if it does not exist locally.
- If V(false), do not check out the repository if it does not exist locally.
type: bool
default: "yes"
version_added: "2.3"
update:
description:
- If C(false), do not retrieve new revisions from the origin repository.
- If V(false), do not retrieve new revisions from the origin repository.
type: bool
default: "yes"
version_added: "2.3"
export:
description:
- If C(true), do export instead of checkout/update.
- If V(true), do export instead of checkout/update.
type: bool
default: "no"
version_added: "1.6"
switch:
description:
- If C(false), do not call svn switch before update.
- If V(false), do not call svn switch before update.
default: "yes"
version_added: "2.0"
type: bool
validate_certs:
description:
- If C(false), passes the C(--trust-server-cert) flag to svn.
- If C(true), does not pass the flag.
- If V(false), passes the C(--trust-server-cert) flag to svn.
- If V(true), does not pass the flag.
default: "no"
version_added: "2.11"
type: bool

16
lib/ansible/modules/systemd_service.py
Unescape Escape View File

@ -25,8 +25,8 @@ options:
aliases: [ service, unit ]
state:
description:
- C(started)/C(stopped) are idempotent actions that will not run commands unless necessary.
C(restarted) will always bounce the unit. C(reloaded) will always reload.
- V(started)/V(stopped) are idempotent actions that will not run commands unless necessary.
V(restarted) will always bounce the unit. V(reloaded) will always reload.
type: str
choices: [ reloaded, restarted, started, stopped ]
enabled:
@ -45,7 +45,7 @@ options:
daemon_reload:
description:
- Run daemon-reload before doing any other operations, to make sure systemd has read any changes.
- When set to C(true), runs daemon-reload even if the module does not start or stop anything.
- When set to V(true), runs daemon-reload even if the module does not start or stop anything.
type: bool
default: no
aliases: [ daemon-reload ]
@ -58,8 +58,8 @@ options:
version_added: "2.8"
scope:
description:
- Run systemctl within a given service manager scope, either as the default system scope C(system),
the current user's scope C(user), or the scope of all users C(global).
- Run systemctl within a given service manager scope, either as the default system scope V(system),
the current user's scope V(user), or the scope of all users V(global).
- "For systemd to work with 'user', the executing user must have its own instance of dbus started and accessible (systemd requirement)."
- "The user dbus process is normally started during normal login, but not during the run of Ansible tasks.
Otherwise you will probably get a 'Failed to connect to bus: no such file or directory' error."
@ -85,9 +85,9 @@ attributes:
platform:
platforms: posix
notes:
- Since 2.4, one of the following options is required C(state), C(enabled), C(masked), C(daemon_reload), (C(daemon_reexec) since 2.8),
and all except C(daemon_reload) and (C(daemon_reexec) since 2.8) also require C(name).
- Before 2.4 you always required C(name).
- Since 2.4, one of the following options is required O(state), O(enabled), O(masked), O(daemon_reload), (O(daemon_reexec) since 2.8),
and all except O(daemon_reload) and (O(daemon_reexec) since 2.8) also require O(name).
- Before 2.4 you always required O(name).
- Globs are not supported in name, i.e C(postgres*.service).
- The service names might vary by specific OS/distribution
- The order of execution when having multiple properties is to first enable/disable, then mask/unmask and then deal with service state.

6
lib/ansible/modules/sysvinit.py
Unescape Escape View File

@ -26,8 +26,8 @@ options:
state:
choices: [ 'started', 'stopped', 'restarted', 'reloaded' ]
description:
- C(started)/C(stopped) are idempotent actions that will not run commands unless necessary.
Not all init scripts support C(restarted) nor C(reloaded) natively, so these will both trigger a stop and start as needed.
- V(started)/V(stopped) are idempotent actions that will not run commands unless necessary.
Not all init scripts support V(restarted) nor V(reloaded) natively, so these will both trigger a stop and start as needed.
type: str
enabled:
type: bool
@ -36,7 +36,7 @@ options:
sleep:
default: 1
description:
- If the service is being C(restarted) or C(reloaded) then sleep this many seconds between the stop and start command.
- If the service is being V(restarted) or V(reloaded) then sleep this many seconds between the stop and start command.
This helps to workaround badly behaving services.
type: int
pattern:

7
lib/ansible/modules/tempfile.py
Unescape Escape View File

@ -14,9 +14,10 @@ module: tempfile
version_added: "2.3"
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
you need to use M(ansible.builtin.file) module.
- The M(ansible.builtin.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 you need to use M(ansible.builtin.file) module.
- For Windows targets, use the M(ansible.windows.win_tempfile) module instead.
options:
state:

13
lib/ansible/modules/template.py
Unescape Escape View File

@ -18,16 +18,17 @@ options:
follow:
description:
- Determine whether symbolic links should be followed.
- When set to C(true) symbolic links will be followed, if they exist.
- When set to C(false) symbolic links will not be followed.
- Previous to Ansible 2.4, this was hardcoded as C(true).
- When set to V(true) symbolic links will be followed, if they exist.
- When set to V(false) symbolic links will not be followed.
- Previous to Ansible 2.4, this was hardcoded as V(true).
type: bool
default: no
version_added: '2.4'
notes:
- For Windows you can use M(ansible.windows.win_template) which uses C(\r\n) as C(newline_sequence) by default.
- The C(jinja2_native) setting has no effect. Native types are never used in the C(template) module which is by design used for generating text files.
For working with templates and utilizing Jinja2 native types see the C(jinja2_native) parameter of the C(template lookup).
- For Windows you can use M(ansible.windows.win_template) which uses V(\\r\\n) as O(newline_sequence) by default.
- The C(jinja2_native) setting has no effect. Native types are never used in the M(ansible.builtin.template) module
which is by design used for generating text files. For working with templates and utilizing Jinja2 native types see
the O(ansible.builtin.template#lookup:jinja2_native) parameter of the P(ansible.builtin.template#lookup) lookup.
seealso:
- module: ansible.builtin.copy
- module: ansible.windows.win_copy

34
lib/ansible/modules/unarchive.py
Unescape Escape View File

@ -17,17 +17,17 @@ module: unarchive
version_added: '1.4'
short_description: Unpacks an archive after (optionally) copying it from the local machine
description:
- The C(unarchive) module unpacks an archive. It will not unpack a compressed file that does not contain an archive.
- The M(ansible.builtin.unarchive) module unpacks an archive. It will not unpack a compressed file that does not contain 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.
- If checksum validation is desired, use M(ansible.builtin.get_url) or M(ansible.builtin.uri) instead to fetch the file and set C(remote_src=yes).
- Set O(remote_src=yes) to unpack an archive which already exists on the target.
- If checksum validation is desired, use M(ansible.builtin.get_url) or M(ansible.builtin.uri) instead to fetch the file and set O(remote_src=yes).
- For Windows targets, use the M(community.windows.win_unzip) module instead.
options:
src:
description:
- If C(remote_src=no) (default), local path to archive file to copy to the target server; can be absolute or relative. If C(remote_src=yes), path on the
- If O(remote_src=no) (default), local path to archive file to copy to the target server; can be absolute or relative. If O(remote_src=yes), path on the
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 O(remote_src=yes) and O(src) contains V(://), 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(ansible.builtin.get_url) module.
type: path
required: true
@ -40,14 +40,14 @@ options:
copy:
description:
- If true, the file is copied from local controller to the managed (remote) node, otherwise, the plugin will look for src archive on the managed machine.
- This option has been deprecated in favor of C(remote_src).
- This option is mutually exclusive with C(remote_src).
- This option has been deprecated in favor of O(remote_src).
- This option is mutually exclusive with O(remote_src).
type: bool
default: yes
creates:
description:
- If the specified absolute path (file or directory) already exists, this step will B(not) be run.
- The specified absolute path (file or directory) must be below the base path given with C(dest:).
- The specified absolute path (file or directory) must be below the base path given with O(dest).
type: path
version_added: "1.6"
io_buffer_size:
@ -65,16 +65,16 @@ options:
exclude:
description:
- List the directory and file entries that you would like to exclude from the unarchive action.
- Mutually exclusive with C(include).
- Mutually exclusive with O(include).
type: list
default: []
elements: str
version_added: "2.1"
include:
description:
- List of directory and file entries that you would like to extract from the archive. If C(include)
- List of directory and file entries that you would like to extract from the archive. If O(include)
is not empty, only files listed here will be extracted.
- Mutually exclusive with C(exclude).
- Mutually exclusive with O(exclude).
type: list
default: []
elements: str
@ -96,16 +96,16 @@ options:
version_added: "2.1"
remote_src:
description:
- Set to C(true) 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).
- Set to V(true) to indicate the archived file is already on the remote system and not local to the Ansible controller.
- This option is mutually exclusive with O(copy).
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(false) used on personally controlled sites using self-signed certificate.
- Prior to 2.2 the code worked as if this was set to C(true).
- This should only set to V(false) used on personally controlled sites using self-signed certificate.
- Prior to 2.2 the code worked as if this was set to V(true).
type: bool
default: yes
version_added: "2.2"
@ -188,7 +188,7 @@ dest:
sample: /opt/software
files:
description: List of all the files in the archive.
returned: When I(list_files) is True
returned: When O(list_files) is V(True)
type: list
sample: '["file1", "file2"]'
gid:
@ -224,7 +224,7 @@ size:
src:
description:
- The source archive's path.
- If I(src) was a remote web URL, or from the local ansible controller, this shows the temporary location where the download was stored.
- If O(src) was a remote web URL, or from the local ansible controller, this shows the temporary location where the download was stored.
returned: always
type: str
sample: "/home/paul/test.tar.gz"

68
lib/ansible/modules/uri.py
Unescape Escape View File

@ -20,7 +20,7 @@ options:
ciphers:
description:
- SSL/TLS Ciphers to use for the request.
- 'When a list is provided, all ciphers are joined in order with C(:)'
- 'When a list is provided, all ciphers are joined in order with V(:)'
- See the L(OpenSSL Cipher List Format,https://www.openssl.org/docs/manmaster/man1/openssl-ciphers.html#CIPHER-LIST-FORMAT)
for more details.
- The available ciphers is dependent on the Python and OpenSSL/LibreSSL versions
@ -40,7 +40,7 @@ options:
required: true
dest:
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 O(dest) is a
directory, the basename of the file on the remote server will be used.
type: path
url_username:
@ -55,23 +55,23 @@ options:
aliases: [ password ]
body:
description:
- The body of the http request/response to the web service. If C(body_format) is set
to 'json' it will take an already formatted JSON string or convert a data structure
- The body of the http request/response to the web service. If O(body_format) is set
to V(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
- If O(body_format) is set to V(form-urlencoded) it will convert a dictionary
or list of tuples into an 'application/x-www-form-urlencoded' string. (Added in v2.7)
- If C(body_format) is set to 'form-multipart' it will convert a dictionary
- If O(body_format) is set to V(form-multipart) it will convert a dictionary
into 'multipart/form-multipart' body. (Added in v2.10)
type: raw
body_format:
description:
- The serialization format of the body. When set to C(json), C(form-multipart), or C(form-urlencoded), encodes
- The serialization format of the body. When set to V(json), V(form-multipart), or V(form-urlencoded), encodes
the body argument, if needed, and automatically sets the Content-Type header accordingly.
- As of v2.3 it is possible to override the C(Content-Type) header, when
set to C(json) or C(form-urlencoded) via the I(headers) option.
- The 'Content-Type' header cannot be overridden when using C(form-multipart)
- C(form-urlencoded) was added in v2.7.
- C(form-multipart) was added in v2.10.
set to V(json) or V(form-urlencoded) via the O(headers) option.
- The 'Content-Type' header cannot be overridden when using V(form-multipart)
- V(form-urlencoded) was added in v2.7.
- V(form-multipart) was added in v2.10.
type: str
choices: [ form-urlencoded, json, raw, form-multipart ]
default: raw
@ -88,15 +88,15 @@ options:
- Whether or not to return the body of the response as a "content" key in
the dictionary result no matter it succeeded or failed.
- Independently of this option, if the reported Content-type is "application/json", then the JSON is
always loaded into a key called C(json) in the dictionary results.
always loaded into a key called RV(ignore:json) in the dictionary results.
type: bool
default: no
force_basic_auth:
description:
- Force the sending of the Basic authentication header upon initial request.
- When this setting is C(false), this module will first try an unauthenticated request, and when the server replies
- When this setting is V(false), this module will first try an unauthenticated request, and when the server replies
with an C(HTTP 401) error, it will submit the Basic authentication header.
- When this setting is C(true), this module will immediately send a Basic authentication header on the first
- When this setting is V(true), this module will immediately send a Basic authentication header on the first
request.
- "Use this setting in any of the following scenarios:"
- You know the webservice endpoint always requires HTTP Basic authentication, and you want to speed up your
@ -108,11 +108,11 @@ options:
default: no
follow_redirects:
description:
- Whether or not the URI module should follow redirects. C(all) will follow all redirects.
C(safe) will follow only "safe" redirects, where "safe" means that the client is only
doing a GET or HEAD on the URI to which it is being redirected. C(none) will not follow
any redirects. Note that C(true) and C(false) choices are accepted for backwards compatibility,
where C(true) is the equivalent of C(all) and C(false) is the equivalent of C(safe). C(true) and C(false)
- Whether or not the URI module should follow redirects. V(all) will follow all redirects.
V(safe) will follow only "safe" redirects, where "safe" means that the client is only
doing a GET or HEAD on the URI to which it is being redirected. V(none) will not follow
any redirects. Note that V(true) and V(false) choices are accepted for backwards compatibility,
where V(true) is the equivalent of V(all) and V(false) is the equivalent of V(safe). V(true) and V(false)
are deprecated and will be removed in some future version of Ansible.
type: str
choices: ['all', 'no', 'none', 'safe', 'urllib2', 'yes']
@ -139,29 +139,29 @@ options:
headers:
description:
- Add custom HTTP headers to a request in the format of a YAML hash. As
of C(2.3) supplying C(Content-Type) here will override the header
generated by supplying C(json) or C(form-urlencoded) for I(body_format).
of Ansible 2.3 supplying C(Content-Type) here will override the header
generated by supplying V(json) or V(form-urlencoded) for O(body_format).
type: dict
default: {}
version_added: '2.1'
validate_certs:
description:
- If C(false), SSL certificates will not be validated.
- This should only set to C(false) used on personally controlled sites using self-signed certificates.
- Prior to 1.9.2 the code defaulted to C(false).
- If V(false), SSL certificates will not be validated.
- This should only set to V(false) used on personally controlled sites using self-signed certificates.
- Prior to 1.9.2 the code defaulted to V(false).
type: bool
default: true
version_added: '1.9.2'
client_cert:
description:
- PEM formatted certificate chain file to be used for SSL client authentication.
- This file can also include the key as well, and if the key is included, I(client_key) is not required
- This file can also include the key as well, and if the key is included, O(client_key) is not required
type: path
version_added: '2.4'
client_key:
description:
- PEM formatted file that contains your private key to be used for SSL client authentication.
- If I(client_cert) contains both the certificate and key, this option is not required.
- If O(client_cert) contains both the certificate and key, this option is not required.
type: path
version_added: '2.4'
ca_path:
@ -172,25 +172,25 @@ options:
src:
description:
- Path to file to be submitted to the remote server.
- Cannot be used with I(body).
- Should be used with I(force_basic_auth) to ensure success when the remote end sends a 401.
- Cannot be used with O(body).
- Should be used with O(force_basic_auth) to ensure success when the remote end sends a 401.
type: path
version_added: '2.7'
remote_src:
description:
- If C(false), the module will search for the C(src) on the controller node.
- If C(true), the module will search for the C(src) on the managed (remote) node.
- If V(false), the module will search for the O(src) on the controller node.
- If V(true), the module will search for the O(src) on the managed (remote) node.
type: bool
default: no
version_added: '2.7'
force:
description:
- If C(true) do not get a cached copy.
- If V(true) do not get a cached copy.
type: bool
default: no
use_proxy:
description:
- If C(false), it will not use a proxy, even if one is defined in an environment variable on the target hosts.
- If V(false), it will not use a proxy, even if one is defined in an environment variable on the target hosts.
type: bool
default: true
unix_socket:
@ -217,9 +217,9 @@ options:
- Use GSSAPI to perform the authentication, typically this is for Kerberos or Kerberos through Negotiate
authentication.
- Requires the Python library L(gssapi,https://github.com/pythongssapi/python-gssapi) to be installed.
- Credentials for GSSAPI can be specified with I(url_username)/I(url_password) or with the GSSAPI env var
- Credentials for GSSAPI can be specified with O(url_username)/O(url_password) or with the GSSAPI env var
C(KRB5CCNAME) that specified a custom Kerberos credential cache.
- NTLM authentication is C(not) supported even if the GSSAPI mech for NTLM has been installed.
- NTLM authentication is B(not) supported even if the GSSAPI mech for NTLM has been installed.
type: bool
default: no
version_added: '2.11'

78
lib/ansible/modules/user.py
Unescape Escape View File

@ -32,7 +32,7 @@ options:
hidden:
description:
- macOS only, optionally hide the user from the login window and system preferences.
- The default will be C(true) if the I(system) option is used.
- The default will be V(true) if the O(system) option is used.
type: bool
version_added: "2.6"
non_unique:
@ -53,24 +53,24 @@ options:
groups:
description:
- A list of supplementary groups which the user is also a member of.
- By default, the user is removed from all other groups. Configure C(append) to modify this.
- When set to an empty string C(''),
- By default, the user is removed from all other groups. Configure O(append) to modify this.
- When set to an empty string V(''),
the user is removed from all groups except the primary group.
- Before Ansible 2.3, the only input format allowed was a comma separated string.
type: list
elements: str
append:
description:
- If C(true), add the user to the groups specified in C(groups).
- If C(false), user will only be added to the groups specified in C(groups),
- If V(true), add the user to the groups specified in O(groups).
- If V(false), user will only be added to the groups specified in O(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 macOS, before Ansible 2.5, the default shell for non-system users was V(/usr/bin/false).
Since Ansible 2.5, the default shell for non-system users on macOS is V(/bin/bash).
- See notes for details on how other operating systems determine the default shell by
the underlying tool.
type: str
@ -81,7 +81,7 @@ options:
skeleton:
description:
- Optionally set a home skeleton directory.
- Requires C(create_home) option!
- Requires O(create_home) option!
type: str
version_added: "2.0"
password:
@ -90,8 +90,8 @@ options:
- B(Linux/Unix/POSIX:) Enter the hashed password as the value.
- See L(FAQ entry,https://docs.ansible.com/ansible/latest/reference_appendices/faq.html#how-do-i-generate-encrypted-passwords-for-the-user-module)
for details on various ways to generate the hash of a password.
- To create an account with a locked/disabled password on Linux systems, set this to C('!') or C('*').
- To create an account with a locked/disabled password on OpenBSD, set this to C('*************').
- To create an account with a locked/disabled password on Linux systems, set this to V('!') or V('*').
- To create an account with a locked/disabled password on OpenBSD, set this to V('*************').
- B(OS X/macOS:) Enter the cleartext password as the value. Be sure to take relevant security precautions.
type: str
state:
@ -104,34 +104,34 @@ options:
default: present
create_home:
description:
- Unless set to C(false), a home directory will be made for the user
- Unless set to V(false), 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.
- Changed from O(createhome) to O(create_home) in Ansible 2.5.
type: bool
default: yes
aliases: [ createhome ]
move_home:
description:
- "If set to C(true) when used with C(home: ), attempt to move the user's old home
- "If set to V(true) when used with O(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(true) makes the user a system account.
- When creating an account O(state=present), setting this to V(true) 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.
- This only affects O(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.
- When used with O(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.
- This only affects O(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
@ -142,7 +142,7 @@ options:
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).
- This will B(not) overwrite an existing SSH key unless used with O(force=yes).
type: bool
default: no
version_added: "0.9"
@ -164,7 +164,7 @@ options:
description:
- Optionally specify the SSH key filename.
- If this is a relative filename then it will be relative to the user's home directory.
- This parameter defaults to I(.ssh/id_rsa).
- This parameter defaults to V(.ssh/id_rsa).
type: path
version_added: "0.9"
ssh_key_comment:
@ -181,8 +181,8 @@ options:
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.
- V(always) will update passwords if they differ.
- V(on_create) will only set the password for newly created users.
type: str
choices: [ always, on_create ]
default: always
@ -200,7 +200,7 @@ options:
- Lock the password (C(usermod -L), C(usermod -U), C(pw lock)).
- Implementation differs by platform. This option does not always mean the user cannot login using other methods.
- This option does not disable the user, only lock the password.
- This must be set to C(False) in order to unlock a currently locked password. The absence of this parameter will not unlock a password.
- This must be set to V(False) in order to unlock a currently locked password. The absence of this parameter will not unlock a password.
- Currently supported on Linux, FreeBSD, DragonFlyBSD, NetBSD, OpenBSD.
type: bool
version_added: "2.6"
@ -220,7 +220,7 @@ options:
- 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='').
- To delete all the profiles, use O(profile='').
- Currently supported on Illumos/Solaris.
type: str
version_added: "2.8"
@ -229,7 +229,7 @@ options:
- 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='').
- To delete all authorizations, use O(authorization='').
- Currently supported on Illumos/Solaris.
type: str
version_added: "2.8"
@ -238,7 +238,7 @@ options:
- 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='').
- To delete all roles, use O(role='').
- Currently supported on Illumos/Solaris.
type: str
version_added: "2.8"
@ -265,7 +265,7 @@ options:
- Sets the umask of the user.
- Does nothing when used with other platforms.
- Currently supported on Linux.
- Requires C(local) is omitted or False.
- Requires O(local) is omitted or V(False).
type: str
version_added: "2.12"
extends_documentation_fragment: action_common_attributes
@ -356,7 +356,7 @@ EXAMPLES = r'''
RETURN = r'''
append:
description: Whether or not to append the user to groups.
returned: When state is C(present) and the user exists
returned: When O(state) is V(present) and the user exists
type: bool
sample: True
comment:
@ -371,7 +371,7 @@ create_home:
sample: True
force:
description: Whether or not a user account was forcibly deleted.
returned: When I(state) is C(absent) and user exists
returned: When O(state) is V(absent) and user exists
type: bool
sample: False
group:
@ -381,17 +381,17 @@ group:
sample: 1001
groups:
description: List of groups of which the user is a member.
returned: When I(groups) is not empty and I(state) is C(present)
returned: When O(groups) is not empty and O(state) is V(present)
type: str
sample: 'chrony,apache'
home:
description: "Path to user's home directory."
returned: When I(state) is C(present)
returned: When O(state) is V(present)
type: str
sample: '/home/asmith'
move_home:
description: Whether or not to move an existing home directory.
returned: When I(state) is C(present) and user exists
returned: When O(state) is V(present) and user exists
type: bool
sample: False
name:
@ -401,32 +401,32 @@ name:
sample: asmith
password:
description: Masked value of the password.
returned: When I(state) is C(present) and I(password) is not empty
returned: When O(state) is V(present) and O(password) is not empty
type: str
sample: 'NOT_LOGGING_PASSWORD'
remove:
description: Whether or not to remove the user account.
returned: When I(state) is C(absent) and user exists
returned: When O(state) is V(absent) and user exists
type: bool
sample: True
shell:
description: User login shell.
returned: When I(state) is C(present)
returned: When O(state) is V(present)
type: str
sample: '/bin/bash'
ssh_fingerprint:
description: Fingerprint of generated SSH key.
returned: When I(generate_ssh_key) is C(True)
returned: When O(generate_ssh_key) is V(True)
type: str
sample: '2048 SHA256:aYNHYcyVm87Igh0IMEDMbvW0QDlRQfE0aJugp684ko8 ansible-generated on host (RSA)'
ssh_key_file:
description: Path to generated SSH private key file.
returned: When I(generate_ssh_key) is C(True)
returned: When O(generate_ssh_key) is V(True)
type: str
sample: /home/asmith/.ssh/id_rsa
ssh_public_key:
description: Generated SSH public key file.
returned: When I(generate_ssh_key) is C(True)
returned: When O(generate_ssh_key) is V(True)
type: str
sample: >
'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC95opt4SPEC06tOYsJQJIuN23BbLMGmYo8ysVZQc4h2DZE9ugbjWWGS1/pweUGjVstgzMkBEeBCByaEf/RJKNecKRPeGd2Bw9DCj/bn5Z6rGfNENKBmo
@ -444,12 +444,12 @@ stdout:
sample:
system:
description: Whether or not the account is a system account.
returned: When I(system) is passed to the module and the account does not exist
returned: When O(system) is passed to the module and the account does not exist
type: bool
sample: True
uid:
description: User ID of the user account.
returned: When I(uid) is passed to the module
returned: When O(uid) is passed to the module
type: int
sample: 1044
'''

16
lib/ansible/modules/wait_for.py
Unescape Escape View File

@ -12,7 +12,7 @@ DOCUMENTATION = r'''
module: wait_for
short_description: Waits for a condition before continuing
description:
- You can wait for a set amount of time C(timeout), this is the default if nothing is specified or just C(timeout) is specified.
- You can wait for a set amount of time O(timeout), this is the default if nothing is specified or just O(timeout) is specified.
This does not produce an error.
- Waiting for a port to become available is useful for when services are not immediately available after their init scripts return
which is true of certain Java application servers.
@ -49,7 +49,7 @@ options:
port:
description:
- Port number to poll.
- C(path) and C(port) are mutually exclusive parameters.
- O(path) and O(port) are mutually exclusive parameters.
type: int
active_connection_states:
description:
@ -60,17 +60,17 @@ options:
version_added: "2.3"
state:
description:
- Either C(present), C(started), or C(stopped), C(absent), or C(drained).
- When checking a port C(started) will ensure the port is open, C(stopped) will check that it is closed, C(drained) will check for active connections.
- When checking for a file or a search string C(present) or C(started) will ensure that the file or string is present before continuing,
C(absent) will check that file is absent or removed.
- Either V(present), V(started), or V(stopped), V(absent), or V(drained).
- When checking a port V(started) will ensure the port is open, V(stopped) will check that it is closed, V(drained) will check for active connections.
- When checking for a file or a search string V(present) or V(started) will ensure that the file or string is present before continuing,
V(absent) will check that file is absent or removed.
type: str
choices: [ absent, drained, present, started, stopped ]
default: started
path:
description:
- Path to a file on the filesystem that must exist before continuing.
- C(path) and C(port) are mutually exclusive parameters.
- O(path) and O(port) are mutually exclusive parameters.
type: path
version_added: "1.4"
search_regex:
@ -81,7 +81,7 @@ options:
version_added: "1.4"
exclude_hosts:
description:
- List of hosts or IPs to ignore when looking for active TCP connections for C(drained) state.
- List of hosts or IPs to ignore when looking for active TCP connections for V(drained) state.
type: list
elements: str
version_added: "1.8"

6
lib/ansible/modules/wait_for_connection.py
Unescape Escape View File

@ -12,9 +12,9 @@ DOCUMENTATION = r'''
module: wait_for_connection
short_description: Waits until remote system is reachable/usable
description:
- Waits for a total of C(timeout) seconds.
- Retries the transport connection after a timeout of C(connect_timeout).
- Tests the transport connection every C(sleep) seconds.
- Waits for a total of O(timeout) seconds.
- Retries the transport connection after a timeout of O(connect_timeout).
- Tests the transport connection every O(sleep) seconds.
- This module makes use of internal ansible transport (and configuration) and the ping/win_ping module to guarantee correct end-to-end functioning.
- This module is also supported for Windows targets.
version_added: '2.3'

64
lib/ansible/modules/yum.py
Unescape Escape View File

@ -21,9 +21,9 @@ description:
options:
use_backend:
description:
- This module supports C(yum) (as it always has), this is known as C(yum3)/C(YUM3)/C(yum-deprecated) by
- This module supports V(yum) (as it always has), this is known as C(yum3)/C(YUM3)/C(yum-deprecated) by
upstream yum developers. As of Ansible 2.7+, this module also supports C(YUM4), which is the
"new yum" and it has an C(dnf) backend. As of ansible-core 2.15+, this module will auto select the backend
"new yum" and it has an V(dnf) backend. As of ansible-core 2.15+, this module will auto select the backend
based on the C(ansible_pkg_mgr) fact.
- By default, this module will select the backend based on the C(ansible_pkg_mgr) fact.
default: "auto"
@ -32,12 +32,12 @@ options:
version_added: "2.7"
name:
description:
- A package name or package specifier with version, like C(name-1.0).
- Comparison operators for package version are valid here C(>), C(<), C(>=), C(<=). Example - C(name>=1.0)
- If a previous version is specified, the task also needs to turn C(allow_downgrade) on.
See the C(allow_downgrade) documentation for caveats with downgrading packages.
- When using state=latest, this can be C('*') which means run C(yum -y update).
- You can also pass a url or a local path to a rpm file (using state=present).
- A package name or package specifier with version, like V(name-1.0).
- Comparison operators for package version are valid here C(>), C(<), C(>=), C(<=). Example - V(name>=1.0)
- If a previous version is specified, the task also needs to turn O(allow_downgrade) on.
See the O(allow_downgrade) documentation for caveats with downgrading packages.
- When using O(state=latest), this can be V('*') which means run C(yum -y update).
- You can also pass a url or a local path to a rpm file (using O(state=present)).
To operate on several packages this can accept a comma separated string of packages or (as of 2.0) a list of packages.
aliases: [ pkg ]
type: list
@ -53,17 +53,17 @@ options:
list:
description:
- "Package name to run the equivalent of C(yum list --show-duplicates <package>) against. In addition to listing packages,
use can also list the following: C(installed), C(updates), C(available) and C(repos)."
- This parameter is mutually exclusive with I(name).
use can also list the following: V(installed), V(updates), V(available) and V(repos)."
- This parameter is mutually exclusive with O(name).
type: str
state:
description:
- Whether to install (C(present) or C(installed), C(latest)), or remove (C(absent) or C(removed)) a package.
- C(present) and C(installed) will simply ensure that a desired package is installed.
- C(latest) will update the specified package if it's not of the latest available version.
- C(absent) and C(removed) will remove the specified package.
- Default is C(None), however in effect the default action is C(present) unless the C(autoremove) option is
enabled for this module, then C(absent) is inferred.
- Whether to install (V(present) or V(installed), V(latest)), or remove (V(absent) or V(removed)) a package.
- V(present) and V(installed) will simply ensure that a desired package is installed.
- V(latest) will update the specified package if it's not of the latest available version.
- V(absent) and V(removed) will remove the specified package.
- Default is V(None), however in effect the default action is V(present) unless the O(autoremove) option is
enabled for this module, then V(absent) is inferred.
type: str
choices: [ absent, installed, latest, present, removed ]
enablerepo:
@ -96,7 +96,7 @@ options:
disable_gpg_check:
description:
- Whether to disable the GPG checking of signatures of packages being
installed. Has an effect only if state is I(present) or I(latest).
installed. Has an effect only if O(state) is V(present) or V(latest).
type: bool
default: "no"
version_added: "1.2"
@ -110,30 +110,30 @@ options:
update_cache:
description:
- Force yum to check if cache is out of date and redownload if needed.
Has an effect only if state is I(present) or I(latest).
Has an effect only if O(state) is V(present) or V(latest).
type: bool
default: "no"
aliases: [ expire-cache ]
version_added: "1.9"
validate_certs:
description:
- This only applies if using a https url as the source of the rpm. e.g. for localinstall. If set to C(false), the SSL certificates will not be validated.
- This should only set to C(false) 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(true).
- This only applies if using a https url as the source of the rpm. e.g. for localinstall. If set to V(false), the SSL certificates will not be validated.
- This should only set to V(false) 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 V(true).
type: bool
default: "yes"
version_added: "2.1"
sslverify:
description:
- Disables SSL validation of the repository server for this transaction.
- This should be set to C(false) if one of the configured repositories is using an untrusted or self-signed certificate.
- This should be set to V(false) if one of the configured repositories is using an untrusted or self-signed certificate.
type: bool
default: "yes"
version_added: "2.13"
update_only:
description:
- When using latest, only update installed packages. Do not install packages.
- Has an effect only if state is I(latest)
- Has an effect only if O(state) is V(latest)
default: "no"
type: bool
version_added: "2.5"
@ -147,13 +147,13 @@ options:
version_added: "2.3"
security:
description:
- If set to C(true), and C(state=latest) then only installs updates that have been marked security related.
- If set to V(true), and O(state=latest) then only installs updates that have been marked security related.
type: bool
default: "no"
version_added: "2.4"
bugfix:
description:
- If set to C(true), and C(state=latest) then only installs updates that have been marked bugfix related.
- If set to V(true), and O(state=latest) then only installs updates that have been marked bugfix related.
default: "no"
type: bool
version_added: "2.6"
@ -194,9 +194,9 @@ options:
version_added: "2.7"
autoremove:
description:
- If C(true), removes all "leaf" packages from the system that were originally
- If V(true), removes all "leaf" packages from the system that were originally
installed as dependencies of user-installed packages but which are no longer
required by any such package. Should be used alone or when state is I(absent)
required by any such package. Should be used alone or when O(state) is V(absent)
- "NOTE: This feature requires yum >= 3.4.3 (RHEL/CentOS 7+)"
type: bool
default: "no"
@ -204,9 +204,9 @@ options:
disable_excludes:
description:
- Disable the excludes defined in YUM config files.
- If set to C(all), disables all excludes.
- If set to C(main), disable excludes defined in [main] in yum.conf.
- If set to C(repoid), disable excludes defined for given repo id.
- If set to V(all), disables all excludes.
- If set to V(main), disable excludes defined in [main] in yum.conf.
- If set to V(repoid), disable excludes defined for given repo id.
type: str
version_added: "2.7"
download_only:
@ -232,7 +232,7 @@ options:
download_dir:
description:
- Specifies an alternate directory to store packages.
- Has an effect only if I(download_only) is specified.
- Has an effect only if O(download_only) is specified.
type: str
version_added: "2.8"
install_repoquery:
@ -274,7 +274,7 @@ attributes:
platforms: rhel
notes:
- When used with a C(loop:) each package will be processed individually,
it is much more efficient to pass the list directly to the I(name) option.
it is much more efficient to pass the list directly to the O(name) option.
- In versions prior to 1.9.2 this module installed and removed each package
given to the yum module separately. This caused problems when packages
specified by filename or url had to be installed or removed together. In

102
lib/ansible/modules/yum_repository.py
Unescape Escape View File

@ -21,9 +21,9 @@ description:
options:
async:
description:
- If set to C(true) Yum will download packages and metadata from this
- If set to V(true) Yum will download packages and metadata from this
repo in parallel, if possible.
- In ansible-core 2.11, 2.12, and 2.13 the default value is C(true).
- In ansible-core 2.11, 2.12, and 2.13 the default value is V(true).
- This option has been deprecated in RHEL 8. If you're using one of the
versions listed above, you can set this option to None to avoid passing an
unknown configuration option.
@ -31,10 +31,10 @@ options:
bandwidth:
description:
- Maximum available network bandwidth in bytes/second. Used with the
I(throttle) option.
- If I(throttle) is a percentage and bandwidth is C(0) then bandwidth
throttling will be disabled. If I(throttle) is expressed as a data rate
(bytes/sec) then this option is ignored. Default is C(0) (no bandwidth
O(throttle) option.
- If O(throttle) is a percentage and bandwidth is V(0) then bandwidth
throttling will be disabled. If O(throttle) is expressed as a data rate
(bytes/sec) then this option is ignored. Default is V(0) (no bandwidth
throttling).
type: str
baseurl:
@ -42,8 +42,8 @@ options:
- URL to the directory where the yum repository's 'repodata' directory
lives.
- It can also be a list of multiple URLs.
- This, the I(metalink) or I(mirrorlist) parameters are required if I(state) is set to
C(present).
- This, the O(metalink) or O(mirrorlist) parameters are required if O(state) is set to
V(present).
type: list
elements: str
cost:
@ -55,36 +55,36 @@ options:
description:
- When the relative size of deltarpm metadata vs pkgs is larger than
this, deltarpm metadata is not downloaded from the repo. Note that you
can give values over C(100), so C(200) means that the metadata is
required to be half the size of the packages. Use C(0) to turn off
can give values over V(100), so V(200) means that the metadata is
required to be half the size of the packages. Use V(0) to turn off
this check, and always download metadata.
type: str
deltarpm_percentage:
description:
- When the relative size of delta vs pkg is larger than this, delta is
not used. Use C(0) to turn off delta rpm processing. Local repositories
(with file:// I(baseurl)) have delta rpms turned off by default.
not used. Use V(0) to turn off delta rpm processing. Local repositories
(with file://O(baseurl)) have delta rpms turned off by default.
type: str
description:
description:
- A human readable string describing the repository. This option corresponds to the "name" property in the repo file.
- This parameter is only required if I(state) is set to C(present).
- This parameter is only required if O(state) is set to V(present).
type: str
enabled:
description:
- This tells yum whether or not use this repository.
- Yum default value is C(true).
- Yum default value is V(true).
type: bool
enablegroups:
description:
- Determines whether yum will allow the use of package groups for this
repository.
- Yum default value is C(true).
- Yum default value is V(true).
type: bool
exclude:
description:
- List of packages to exclude from updates or installs. This should be a
space separated list. Shell globs using wildcards (eg. C(*) and C(?))
space separated list. Shell globs using wildcards (for example V(*) and V(?))
are allowed.
- The list can also be a regular YAML array.
type: list
@ -92,16 +92,16 @@ options:
failovermethod:
choices: [roundrobin, priority]
description:
- C(roundrobin) randomly selects a URL out of the list of URLs to start
- V(roundrobin) randomly selects a URL out of the list of URLs to start
with and proceeds through each of them as it encounters a failure
contacting the host.
- C(priority) starts from the first I(baseurl) listed and reads through
- V(priority) starts from the first O(baseurl) listed and reads through
them sequentially.
type: str
file:
description:
- File name without the C(.repo) extension to save the repo in. Defaults
to the value of I(name).
to the value of O(name).
type: str
gpgcakey:
description:
@ -112,7 +112,7 @@ options:
- Tells yum whether or not it should perform a GPG signature check on
packages.
- No default setting. If the value is not set, the system setting from
C(/etc/yum.conf) or system default of C(false) will be used.
C(/etc/yum.conf) or system default of V(false) will be used.
type: bool
gpgkey:
description:
@ -123,31 +123,31 @@ options:
module_hotfixes:
description:
- Disable module RPM filtering and make all RPMs from the repository
available. The default is C(None).
available. The default is V(None).
version_added: '2.11'
type: bool
http_caching:
description:
- Determines how upstream HTTP caches are instructed to handle any HTTP
downloads that Yum does.
- C(all) means that all HTTP downloads should be cached.
- C(packages) means that only RPM package downloads should be cached (but
- V(all) means that all HTTP downloads should be cached.
- V(packages) means that only RPM package downloads should be cached (but
not repository metadata downloads).
- C(none) means that no HTTP downloads should be cached.
- V(none) means that no HTTP downloads should be cached.
choices: [all, packages, none]
type: str
include:
description:
- Include external configuration file. Both, local path and URL is
supported. Configuration file will be inserted at the position of the
I(include=) line. Included files may contain further include lines.
C(include=) line. Included files may contain further include lines.
Yum will abort with an error if an inclusion loop is detected.
type: str
includepkgs:
description:
- List of packages you want to only use from a repository. This should be
a space separated list. Shell globs using wildcards (eg. C(*) and C(?))
are allowed. Substitution variables (e.g. C($releasever)) are honored
a space separated list. Shell globs using wildcards (for example V(*) and V(?))
are allowed. Substitution variables (for example V($releasever)) are honored
here.
- The list can also be a regular YAML array.
type: list
@ -155,8 +155,8 @@ options:
ip_resolve:
description:
- Determines how yum resolves host names.
- C(4) or C(IPv4) - resolve to IPv4 addresses only.
- C(6) or C(IPv6) - resolve to IPv6 addresses only.
- V(4) or V(IPv4) - resolve to IPv4 addresses only.
- V(6) or V(IPv6) - resolve to IPv6 addresses only.
choices: ['4', '6', IPv4, IPv6, whatever]
type: str
keepalive:
@ -167,7 +167,7 @@ options:
type: bool
keepcache:
description:
- Either C(1) or C(0). Determines whether or not yum keeps the cache of
- Either V(1) or V(0). Determines whether or not yum keeps the cache of
headers and packages after successful installation.
choices: ['0', '1']
type: str
@ -178,21 +178,21 @@ options:
type: str
metadata_expire_filter:
description:
- Filter the I(metadata_expire) time, allowing a trade of speed for
- Filter the O(metadata_expire) time, allowing a trade of speed for
accuracy if a command doesn't require it. Each yum command can specify
that it requires a certain level of timeliness quality from the remote
repos. from "I'm about to install/upgrade, so this better be current"
to "Anything that's available is good enough".
- C(never) - Nothing is filtered, always obey I(metadata_expire).
- C(read-only:past) - Commands that only care about past information are
filtered from metadata expiring. Eg. I(yum history) info (if history
- V(never) - Nothing is filtered, always obey O(metadata_expire).
- V(read-only:past) - Commands that only care about past information are
filtered from metadata expiring. Eg. C(yum history) info (if history
needs to lookup anything about a previous transaction, then by
definition the remote package was available in the past).
- C(read-only:present) - Commands that are balanced between past and
future. Eg. I(yum list yum).
- C(read-only:future) - Commands that are likely to result in running
- V(read-only:present) - Commands that are balanced between past and
future. Eg. C(yum list yum).
- V(read-only:future) - Commands that are likely to result in running
other commands which will require the latest metadata. Eg.
I(yum check-update).
C(yum check-update).
- Note that this option does not override "yum clean expire-cache".
choices: [never, 'read-only:past', 'read-only:present', 'read-only:future']
type: str
@ -200,15 +200,15 @@ options:
description:
- Specifies a URL to a metalink file for the repomd.xml, a list of
mirrors for the entire repository are generated by converting the
mirrors for the repomd.xml file to a I(baseurl).
- This, the I(baseurl) or I(mirrorlist) parameters are required if I(state) is set to
C(present).
mirrors for the repomd.xml file to a O(baseurl).
- This, the O(baseurl) or O(mirrorlist) parameters are required if O(state) is set to
V(present).
type: str
mirrorlist:
description:
- Specifies a URL to a file containing a list of baseurls.
- This, the I(baseurl) or I(metalink) parameters are required if I(state) is set to
C(present).
- This, the O(baseurl) or O(metalink) parameters are required if O(state) is set to
V(present).
type: str
mirrorlist_expire:
description:
@ -219,8 +219,8 @@ options:
name:
description:
- Unique repository ID. This option builds the section name of the repository in the repo file.
- This parameter is only required if I(state) is set to C(present) or
C(absent).
- This parameter is only required if O(state) is set to V(present) or
V(absent).
type: str
required: true
password:
@ -239,7 +239,7 @@ options:
type: bool
proxy:
description:
- URL to the proxy server that yum should use. Set to C(_none_) to
- URL to the proxy server that yum should use. Set to V(_none_) to
disable the global proxy setting.
type: str
proxy_password:
@ -263,7 +263,7 @@ options:
retries:
description:
- Set the number of times any attempt to retrieve a file should retry
before returning an error. Setting this to C(0) makes yum try forever.
before returning an error. Setting this to V(0) makes yum try forever.
type: str
s3_enabled:
description:
@ -272,7 +272,7 @@ options:
type: bool
skip_if_unavailable:
description:
- If set to C(true) yum will continue running if this repository cannot be
- If set to V(true) yum will continue running if this repository cannot be
contacted for any reason. This should be set carefully as all repos are
consulted for any given command.
type: bool
@ -281,7 +281,7 @@ options:
- Whether yum should check the permissions on the paths for the
certificates on the repository (both remote and local).
- If we can't read any of the files then yum will force
I(skip_if_unavailable) to be C(true). This is most useful for non-root
O(skip_if_unavailable) to be V(true). This is most useful for non-root
processes which use yum on repos that have client cert files which are
readable only by root.
type: bool
@ -327,7 +327,7 @@ options:
ui_repoid_vars:
description:
- When a repository id is displayed, append these yum variables to the
string if they are used in the I(baseurl)/etc. Variables are appended
string if they are used in the O(baseurl)/etc. Variables are appended
in the order listed (and found).
type: str
username:
@ -353,7 +353,7 @@ notes:
- The repo file will be automatically deleted if it contains no repository.
- When removing a repository, beware that the metadata cache may still remain
on disk until you run C(yum clean all). Use a notification handler for this.
- "The C(params) parameter was removed in Ansible 2.5 due to circumventing Ansible's parameter
- "The O(ignore:params) parameter was removed in Ansible 2.5 due to circumventing Ansible's parameter
handling"
'''

Write Preview
Loading…
Cancel
Save