diff --git a/lib/ansible/modules/add_host.py b/lib/ansible/modules/add_host.py index b446df59530..eb9d55979a2 100644 --- a/lib/ansible/modules/add_host.py +++ b/lib/ansible/modules/add_host.py @@ -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. diff --git a/lib/ansible/modules/apt.py b/lib/ansible/modules/apt.py index ad073e8681b..2a8de08cb4f 100644 --- a/lib/ansible/modules/apt.py +++ b/lib/ansible/modules/apt.py @@ -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. ''' diff --git a/lib/ansible/modules/apt_key.py b/lib/ansible/modules/apt_key.py index bab8a35d9a5..295dc262a3a 100644 --- a/lib/ansible/modules/apt_key.py +++ b/lib/ansible/modules/apt_key.py @@ -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' diff --git a/lib/ansible/modules/apt_repository.py b/lib/ansible/modules/apt_repository.py index 17bebce425f..158913a1204 100644 --- a/lib/ansible/modules/apt_repository.py +++ b/lib/ansible/modules/apt_repository.py @@ -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 diff --git a/lib/ansible/modules/assemble.py b/lib/ansible/modules/assemble.py index e046c1129ca..c93b4ff67db 100644 --- a/lib/ansible/modules/assemble.py +++ b/lib/ansible/modules/assemble.py @@ -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: diff --git a/lib/ansible/modules/assert.py b/lib/ansible/modules/assert.py index 0ef5eb04368..0070f25671e 100644 --- a/lib/ansible/modules/assert.py +++ b/lib/ansible/modules/assert.py @@ -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" diff --git a/lib/ansible/modules/async_status.py b/lib/ansible/modules/async_status.py index 1760d0bebd3..e0a5871bcdf 100644 --- a/lib/ansible/modules/async_status.py +++ b/lib/ansible/modules/async_status.py @@ -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 diff --git a/lib/ansible/modules/blockinfile.py b/lib/ansible/modules/blockinfile.py index 7013de97e76..e9feb7eed6a 100644 --- a/lib/ansible/modules/blockinfile.py +++ b/lib/ansible/modules/blockinfile.py @@ -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 diff --git a/lib/ansible/modules/command.py b/lib/ansible/modules/command.py index f2bb117c35a..846ac36afaf 100644 --- a/lib/ansible/modules/command.py +++ b/lib/ansible/modules/command.py @@ -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 diff --git a/lib/ansible/modules/copy.py b/lib/ansible/modules/copy.py index 76395220b5b..af3ab4a2b53 100644 --- a/lib/ansible/modules/copy.py +++ b/lib/ansible/modules/copy.py @@ -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' diff --git a/lib/ansible/modules/cron.py b/lib/ansible/modules/cron.py index 9b4c96ca429..d43c8133831 100644 --- a/lib/ansible/modules/cron.py +++ b/lib/ansible/modules/cron.py @@ -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" diff --git a/lib/ansible/modules/deb822_repository.py b/lib/ansible/modules/deb822_repository.py index f8bacd1c3eb..6b73cfe29e0 100644 --- a/lib/ansible/modules/deb822_repository.py +++ b/lib/ansible/modules/deb822_repository.py @@ -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, diff --git a/lib/ansible/modules/debconf.py b/lib/ansible/modules/debconf.py index 1eb5e3f248d..0e7aad0036b 100644 --- a/lib/ansible/modules/debconf.py +++ b/lib/ansible/modules/debconf.py @@ -31,9 +31,9 @@ notes: Use 'debconf-show ' 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: diff --git a/lib/ansible/modules/debug.py b/lib/ansible/modules/debug.py index b275a209cf6..6e6301c8e6f 100644 --- a/lib/ansible/modules/debug.py +++ b/lib/ansible/modules/debug.py @@ -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 diff --git a/lib/ansible/modules/dnf.py b/lib/ansible/modules/dnf.py index 3bfca3cd715..f2a968f22d6 100644 --- a/lib/ansible/modules/dnf.py +++ b/lib/ansible/modules/dnf.py @@ -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" diff --git a/lib/ansible/modules/dnf5.py b/lib/ansible/modules/dnf5.py index 088810008cd..bf87cd4c0ce 100644 --- a/lib/ansible/modules/dnf5.py +++ b/lib/ansible/modules/dnf5.py @@ -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" diff --git a/lib/ansible/modules/dpkg_selections.py b/lib/ansible/modules/dpkg_selections.py index 87cad529b57..71226f01b06 100644 --- a/lib/ansible/modules/dpkg_selections.py +++ b/lib/ansible/modules/dpkg_selections.py @@ -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 diff --git a/lib/ansible/modules/expect.py b/lib/ansible/modules/expect.py index c9aac71ac56..921aa70a447 100644 --- a/lib/ansible/modules/expect.py +++ b/lib/ansible/modules/expect.py @@ -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 diff --git a/lib/ansible/modules/fetch.py b/lib/ansible/modules/fetch.py index 646f78d97f9..77ebd190409 100644 --- a/lib/ansible/modules/fetch.py +++ b/lib/ansible/modules/fetch.py @@ -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 diff --git a/lib/ansible/modules/file.py b/lib/ansible/modules/file.py index 0c9c3d95045..0aa91838efc 100644 --- a/lib/ansible/modules/file.py +++ b/lib/ansible/modules/file.py @@ -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 ''' diff --git a/lib/ansible/modules/find.py b/lib/ansible/modules/find.py index dd186b08888..64da9336253 100644 --- a/lib/ansible/modules/find.py +++ b/lib/ansible/modules/find.py @@ -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" diff --git a/lib/ansible/modules/gather_facts.py b/lib/ansible/modules/gather_facts.py index aa67a0e3fd9..123001b05ef 100644 --- a/lib/ansible/modules/gather_facts.py +++ b/lib/ansible/modules/gather_facts.py @@ -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 diff --git a/lib/ansible/modules/get_url.py b/lib/ansible/modules/get_url.py index 817bca0ae22..146e6c2f5a6 100644 --- a/lib/ansible/modules/get_url.py +++ b/lib/ansible/modules/get_url.py @@ -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 diff --git a/lib/ansible/modules/getent.py b/lib/ansible/modules/getent.py index ccad406b4ec..5487354bda5 100644 --- a/lib/ansible/modules/getent.py +++ b/lib/ansible/modules/getent.py @@ -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_ prefixed variable. + the host's facts, in a C(getent_) 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: diff --git a/lib/ansible/modules/git.py b/lib/ansible/modules/git.py index 6bbc04adcfe..681708e6a62 100644 --- a/lib/ansible/modules/git.py +++ b/lib/ansible/modules/git.py @@ -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 diff --git a/lib/ansible/modules/group.py b/lib/ansible/modules/group.py index 4119d4a06f1..f433a481fd6 100644 --- a/lib/ansible/modules/group.py +++ b/lib/ansible/modules/group.py @@ -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 ''' diff --git a/lib/ansible/modules/include_role.py b/lib/ansible/modules/include_role.py index ea7c61e3cb8..c0e24ae190c 100644 --- a/lib/ansible/modules/include_role.py +++ b/lib/ansible/modules/include_role.py @@ -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 diff --git a/lib/ansible/modules/include_tasks.py b/lib/ansible/modules/include_tasks.py index ff5d62acf68..d89950a950a 100644 --- a/lib/ansible/modules/include_tasks.py +++ b/lib/ansible/modules/include_tasks.py @@ -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: diff --git a/lib/ansible/modules/include_vars.py b/lib/ansible/modules/include_vars.py index b39a5fe2e5f..3752ca65701 100644 --- a/lib/ansible/modules/include_vars.py +++ b/lib/ansible/modules/include_vars.py @@ -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"] diff --git a/lib/ansible/modules/iptables.py b/lib/ansible/modules/iptables.py index a772189ad77..fee80495a1b 100644 --- a/lib/ansible/modules/iptables.py +++ b/lib/ansible/modules/iptables.py @@ -17,7 +17,7 @@ author: - Linus Unnebäck (@LinusU) - 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 diff --git a/lib/ansible/modules/known_hosts.py b/lib/ansible/modules/known_hosts.py index e1ac5d366a2..0c97ce2e0b1 100644 --- a/lib/ansible/modules/known_hosts.py +++ b/lib/ansible/modules/known_hosts.py @@ -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 or 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( ssh-rsa ). - - 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 diff --git a/lib/ansible/modules/lineinfile.py b/lib/ansible/modules/lineinfile.py index 0c3a397ba40..3d8d85dc53a 100644 --- a/lib/ansible/modules/lineinfile.py +++ b/lib/ansible/modules/lineinfile.py @@ -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 diff --git a/lib/ansible/modules/meta.py b/lib/ansible/modules/meta.py index 1b062c983fb..78c3928ba19 100644 --- a/lib/ansible/modules/meta.py +++ b/lib/ansible/modules/meta.py @@ -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 diff --git a/lib/ansible/modules/package.py b/lib/ansible/modules/package.py index 6078739f2ff..5541635855f 100644 --- a/lib/ansible/modules/package.py +++ b/lib/ansible/modules/package.py @@ -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 = ''' diff --git a/lib/ansible/modules/package_facts.py b/lib/ansible/modules/package_facts.py index b5056f09e10..cc6fafad131 100644 --- a/lib/ansible/modules/package_facts.py +++ b/lib/ansible/modules/package_facts.py @@ -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 diff --git a/lib/ansible/modules/pause.py b/lib/ansible/modules/pause.py index dbd2582d2e9..450bfaf9b3c 100644 --- a/lib/ansible/modules/pause.py +++ b/lib/ansible/modules/pause.py @@ -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 diff --git a/lib/ansible/modules/ping.py b/lib/ansible/modules/ping.py index f6267a8af00..c72479806fa 100644 --- a/lib/ansible/modules/ping.py +++ b/lib/ansible/modules/ping.py @@ -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 diff --git a/lib/ansible/modules/pip.py b/lib/ansible/modules/pip.py index eebda238ec6..9a3daf61b80 100644 --- a/lib/ansible/modules/pip.py +++ b/lib/ansible/modules/pip.py @@ -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 diff --git a/lib/ansible/modules/reboot.py b/lib/ansible/modules/reboot.py index 71e6294eac2..fbeca0271b7 100644 --- a/lib/ansible/modules/reboot.py +++ b/lib/ansible/modules/reboot.py @@ -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' diff --git a/lib/ansible/modules/replace.py b/lib/ansible/modules/replace.py index c3747833817..4fc86e1bdab 100644 --- a/lib/ansible/modules/replace.py +++ b/lib/ansible/modules/replace.py @@ -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''' diff --git a/lib/ansible/modules/rpm_key.py b/lib/ansible/modules/rpm_key.py index 2586076a77e..9c46e43e50e 100644 --- a/lib/ansible/modules/rpm_key.py +++ b/lib/ansible/modules/rpm_key.py @@ -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' diff --git a/lib/ansible/modules/script.py b/lib/ansible/modules/script.py index fa2eea601d2..e9d3c244f47 100644 --- a/lib/ansible/modules/script.py +++ b/lib/ansible/modules/script.py @@ -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: diff --git a/lib/ansible/modules/service.py b/lib/ansible/modules/service.py index 81d2299c7b3..a9d48e79c40 100644 --- a/lib/ansible/modules/service.py +++ b/lib/ansible/modules/service.py @@ -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. diff --git a/lib/ansible/modules/service_facts.py b/lib/ansible/modules/service_facts.py index 35f5d3103b0..85d6250d187 100644 --- a/lib/ansible/modules/service_facts.py +++ b/lib/ansible/modules/service_facts.py @@ -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 diff --git a/lib/ansible/modules/set_fact.py b/lib/ansible/modules/set_fact.py index f4b5c1cf3a7..7fa0cf9d446 100644 --- a/lib/ansible/modules/set_fact.py +++ b/lib/ansible/modules/set_fact.py @@ -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 diff --git a/lib/ansible/modules/set_stats.py b/lib/ansible/modules/set_stats.py index 16d7bfef350..5b11c3652d9 100644 --- a/lib/ansible/modules/set_stats.py +++ b/lib/ansible/modules/set_stats.py @@ -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" ''' diff --git a/lib/ansible/modules/setup.py b/lib/ansible/modules/setup.py index e1013452151..0615f5efe8a 100644 --- a/lib/ansible/modules/setup.py +++ b/lib/ansible/modules/setup.py @@ -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). diff --git a/lib/ansible/modules/shell.py b/lib/ansible/modules/shell.py index c4c359ec537..cd403b7c38d 100644 --- a/lib/ansible/modules/shell.py +++ b/lib/ansible/modules/shell.py @@ -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 diff --git a/lib/ansible/modules/stat.py b/lib/ansible/modules/stat.py index 4fc709962b6..ee29251b005 100644 --- a/lib/ansible/modules/stat.py +++ b/lib/ansible/modules/stat.py @@ -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: diff --git a/lib/ansible/modules/subversion.py b/lib/ansible/modules/subversion.py index 68aacfd263a..847431eb5ec 100644 --- a/lib/ansible/modules/subversion.py +++ b/lib/ansible/modules/subversion.py @@ -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 diff --git a/lib/ansible/modules/systemd_service.py b/lib/ansible/modules/systemd_service.py index 921fdc77e8c..47ff3cf6ddb 100644 --- a/lib/ansible/modules/systemd_service.py +++ b/lib/ansible/modules/systemd_service.py @@ -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. diff --git a/lib/ansible/modules/sysvinit.py b/lib/ansible/modules/sysvinit.py index ac935df6027..fc934d35887 100644 --- a/lib/ansible/modules/sysvinit.py +++ b/lib/ansible/modules/sysvinit.py @@ -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: diff --git a/lib/ansible/modules/tempfile.py b/lib/ansible/modules/tempfile.py index 60ee4b4b56a..c5fedabe8a1 100644 --- a/lib/ansible/modules/tempfile.py +++ b/lib/ansible/modules/tempfile.py @@ -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: diff --git a/lib/ansible/modules/template.py b/lib/ansible/modules/template.py index 7ee581ad122..53db1851c9d 100644 --- a/lib/ansible/modules/template.py +++ b/lib/ansible/modules/template.py @@ -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 diff --git a/lib/ansible/modules/unarchive.py b/lib/ansible/modules/unarchive.py index d811a5c8ed6..ec15a5717af 100644 --- a/lib/ansible/modules/unarchive.py +++ b/lib/ansible/modules/unarchive.py @@ -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" diff --git a/lib/ansible/modules/uri.py b/lib/ansible/modules/uri.py index 94dbd268ebd..c4f7a5e8b3a 100644 --- a/lib/ansible/modules/uri.py +++ b/lib/ansible/modules/uri.py @@ -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' diff --git a/lib/ansible/modules/user.py b/lib/ansible/modules/user.py index e82003cf399..43b61a83fda 100644 --- a/lib/ansible/modules/user.py +++ b/lib/ansible/modules/user.py @@ -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 ''' diff --git a/lib/ansible/modules/wait_for.py b/lib/ansible/modules/wait_for.py index 2abdb1d5978..302f1e3f891 100644 --- a/lib/ansible/modules/wait_for.py +++ b/lib/ansible/modules/wait_for.py @@ -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" diff --git a/lib/ansible/modules/wait_for_connection.py b/lib/ansible/modules/wait_for_connection.py index f0eccb67ef7..3b57e5bc240 100644 --- a/lib/ansible/modules/wait_for_connection.py +++ b/lib/ansible/modules/wait_for_connection.py @@ -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' diff --git a/lib/ansible/modules/yum.py b/lib/ansible/modules/yum.py index c725647b0e7..e9e2d8502b1 100644 --- a/lib/ansible/modules/yum.py +++ b/lib/ansible/modules/yum.py @@ -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 ) 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 diff --git a/lib/ansible/modules/yum_repository.py b/lib/ansible/modules/yum_repository.py index e3072357de4..597001f2ae1 100644 --- a/lib/ansible/modules/yum_repository.py +++ b/lib/ansible/modules/yum_repository.py @@ -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" '''