From 444d7f60e1811ef476a4c4ba47c636781d655624 Mon Sep 17 00:00:00 2001 From: David Salvisberg Date: Wed, 4 Sep 2024 12:35:55 +0200 Subject: [PATCH] Fixes up some docstrings. --- scripts/generate_module_hints.py | 7 +- src/suitable/_module_types.py | 93 +- src/suitable/_modules.py | 3640 +++++++++++++++--------------- src/suitable/api.py | 4 +- 4 files changed, 1898 insertions(+), 1846 deletions(-) diff --git a/scripts/generate_module_hints.py b/scripts/generate_module_hints.py index 670109a..80d607c 100755 --- a/scripts/generate_module_hints.py +++ b/scripts/generate_module_hints.py @@ -222,6 +222,7 @@ def replace(match: re.Match[str]) -> str: if mode == 'M': # module -> method link + value = value.rsplit('.', 1)[-1] value = value.replace(' ', '\u00a0') return f':meth:`{value}`' elif mode == 'P': @@ -231,7 +232,7 @@ def replace(match: re.Match[str]) -> str: value = value[:type_idx] value = value.replace(' ', '\u00a0') - return f'`{value}`' + return f'``{value}``' # be generous about accepting either as either elif mode in 'UL': if ',' in value: @@ -259,7 +260,7 @@ def replace(match: re.Match[str]) -> str: # sphinx reference name, _ = value.split(',') name = name.replace(' ', '\u00a0') - return f'`{name}`' + return f'``{name}``' elif mode in ('O', 'C', 'V', 'RV', 'E'): if isinstance(value, str): # NOTE: Values are already escaped, so we need to unescape @@ -267,7 +268,7 @@ def replace(match: re.Match[str]) -> str: # We also replace spaces with non-breaking spaces # so our line-splitter can't split there. value = value.replace('\\\\', '\\').replace(' ', '\u00a0') - return f'`{value}`' + return f'``{value}``' else: raise ValueError(f'Unknown reference mode {mode}') diff --git a/src/suitable/_module_types.py b/src/suitable/_module_types.py index f4783ac..2fcee4f 100644 --- a/src/suitable/_module_types.py +++ b/src/suitable/_module_types.py @@ -257,7 +257,7 @@ def ansible_job_id(self, server: str | None = None) -> str: def finished(self, server: str | None = None) -> int: """ - Whether the asynchronous job has finished (`1`) or not (`0`). + Whether the asynchronous job has finished (``1``) or not (``0``). Returned when: always """ @@ -265,7 +265,7 @@ def finished(self, server: str | None = None) -> int: def started(self, server: str | None = None) -> int: """ - Whether the asynchronous job has started (`1`) or not (`0`). + Whether the asynchronous job has started (``1``) or not (``0``). Returned when: always """ @@ -780,17 +780,17 @@ class FileResults(RunnerResults): def dest(self, server: str | None = None) -> str: """ - Destination file/path, equal to the value passed to `path`. + Destination file/path, equal to the value passed to ``path``. - Returned when: `state=touch`, `state=hard`, `state=link` + Returned when: ``state=touch``, ``state=hard``, ``state=link`` """ return self.acquire(server, 'dest') def path(self, server: str | None = None) -> str: """ - Destination file/path, equal to the value passed to `path`. + Destination file/path, equal to the value passed to ``path``. - Returned when: `state=absent`, `state=directory`, `state=file` + Returned when: ``state=absent``, ``state=directory``, ``state=file`` """ return self.acquire(server, 'path') @@ -1138,7 +1138,7 @@ def gid(self, server: str | None = None) -> int: """ Group ID of the group. - Returned when: `state` is `present` + Returned when: ``state`` is ``present`` """ return self.acquire(server, 'gid') @@ -1162,7 +1162,7 @@ def system(self, server: str | None = None) -> bool: """ Whether the group is a system group or not. - Returned when: `state` is `present` + Returned when: ``state`` is ``present`` """ return self.acquire(server, 'system') @@ -1557,7 +1557,7 @@ class PingResults(RunnerResults): def ping(self, server: str | None = None) -> str: """ - Value provided with the `data` parameter. + Value provided with the ``data`` parameter. Returned when: success """ @@ -2026,7 +2026,7 @@ class SystemdResults(RunnerResults): def status(self, server: str | None = None) -> dict[str, Incomplete]: """ - A dictionary with the key=value pairs returned from `systemctl show`. + A dictionary with the key=value pairs returned from ``systemctl show``. Returned when: success """ @@ -2050,7 +2050,7 @@ class SystemdServiceResults(RunnerResults): def status(self, server: str | None = None) -> dict[str, Incomplete]: """ - A dictionary with the key=value pairs returned from `systemctl show`. + A dictionary with the key=value pairs returned from ``systemctl show``. Returned when: success """ @@ -2228,7 +2228,7 @@ def files(self, server: str | None = None) -> list[Incomplete]: """ List of all the files in the archive. - Returned when: `list_files` is `True` + Returned when: ``list_files`` is ``True`` """ return self.acquire(server, 'files') @@ -2286,7 +2286,7 @@ def src(self, server: str | None = None) -> str: """ The source archive's path. - If `src` was a remote web URL, or from the local ansible controller, + If ``src`` was a remote web URL, or from the local ansible controller, this shows the temporary location where the download was stored. Returned when: always @@ -2417,7 +2417,7 @@ def append(self, server: str | None = None) -> bool: """ Whether or not to append the user to groups. - Returned when: `state` is `present` and the user exists + Returned when: ``state`` is ``present`` and the user exists """ return self.acquire(server, 'append') @@ -2441,7 +2441,7 @@ def force(self, server: str | None = None) -> bool: """ Whether or not a user account was forcibly deleted. - Returned when: `state` is `absent` and user exists + Returned when: ``state`` is ``absent`` and user exists """ return self.acquire(server, 'force') @@ -2457,7 +2457,7 @@ def groups(self, server: str | None = None) -> str: """ List of groups of which the user is a member. - Returned when: `groups` is not empty and `state` is `present` + Returned when: ``groups`` is not empty and ``state`` is ``present`` """ return self.acquire(server, 'groups') @@ -2465,7 +2465,7 @@ def home(self, server: str | None = None) -> str: """ Path to user's home directory. - Returned when: `state` is `present` + Returned when: ``state`` is ``present`` """ return self.acquire(server, 'home') @@ -2473,7 +2473,7 @@ def move_home(self, server: str | None = None) -> bool: """ Whether or not to move an existing home directory. - Returned when: `state` is `present` and user exists + Returned when: ``state`` is ``present`` and user exists """ return self.acquire(server, 'move_home') @@ -2489,7 +2489,7 @@ def password(self, server: str | None = None) -> str: """ Masked value of the password. - Returned when: `state` is `present` and `password` is not empty + Returned when: ``state`` is ``present`` and ``password`` is not empty """ return self.acquire(server, 'password') @@ -2497,7 +2497,7 @@ def remove(self, server: str | None = None) -> bool: """ Whether or not to remove the user account. - Returned when: `state` is `absent` and user exists + Returned when: ``state`` is ``absent`` and user exists """ return self.acquire(server, 'remove') @@ -2505,7 +2505,7 @@ def shell(self, server: str | None = None) -> str: """ User login shell. - Returned when: `state` is `present` + Returned when: ``state`` is ``present`` """ return self.acquire(server, 'shell') @@ -2513,7 +2513,7 @@ def ssh_fingerprint(self, server: str | None = None) -> str: """ Fingerprint of generated SSH key. - Returned when: `generate_ssh_key` is `True` + Returned when: ``generate_ssh_key`` is ``True`` """ return self.acquire(server, 'ssh_fingerprint') @@ -2521,7 +2521,7 @@ def ssh_key_file(self, server: str | None = None) -> str: """ Path to generated SSH private key file. - Returned when: `generate_ssh_key` is `True` + Returned when: ``generate_ssh_key`` is ``True`` """ return self.acquire(server, 'ssh_key_file') @@ -2529,7 +2529,7 @@ def ssh_public_key(self, server: str | None = None) -> str: """ Generated SSH public key file. - Returned when: `generate_ssh_key` is `True` + Returned when: ``generate_ssh_key`` is ``True`` """ return self.acquire(server, 'ssh_public_key') @@ -2553,7 +2553,7 @@ def system(self, server: str | None = None) -> bool: """ Whether or not the account is a system account. - Returned when: `system` is passed to the module and the account does + Returned when: ``system`` is passed to the module and the account does not exist """ return self.acquire(server, 'system') @@ -2562,7 +2562,7 @@ def uid(self, server: str | None = None) -> int: """ User ID of the user account. - Returned when: `uid` is passed to the module + Returned when: ``uid`` is passed to the module """ return self.acquire(server, 'uid') @@ -3461,7 +3461,7 @@ def user(self, server: str | None = None) -> str: def validate_certs(self, server: str | None = None) -> bool: """ This only applies if using a https url as the source of the keys. If - set to `false`, the SSL certificates will not be validated. + set to ``false``, the SSL certificates will not be validated. Returned when: success """ @@ -3504,7 +3504,7 @@ class FirewalldInfoResults(RunnerResults): def active_zones(self, server: str | None = None) -> bool: """ - Gather active zones only if turn it `true`. + Gather active zones only if turn it ``true``. Returned when: success """ @@ -3520,9 +3520,9 @@ def collected_zones(self, server: str | None = None) -> list[Incomplete]: def undefined_zones(self, server: str | None = None) -> list[Incomplete]: """ - A list of undefined zones in `zones` option. + A list of undefined zones in ``zones`` option. - `undefined_zones` will be ignored for gathering process. + ``undefined_zones`` will be ignored for gathering process. Returned when: success """ @@ -4309,7 +4309,8 @@ def values( # type:ignore[override] ) -> dict[str, Incomplete]: """ dictionary of before and after values; each key is a variable name, - each value is another dict with `before`, `after`, and `changed` keys. + each value is another dict with ``before``, ``after``, and ``changed`` + keys. Returned when: always """ @@ -4547,19 +4548,19 @@ def name(self, server: str | None = None) -> str: def added(self, server: str | None = None) -> list[Incomplete]: """ - A list of members added when `state` is `present` or `pure`; this is - empty if no members are added. + A list of members added when ``state`` is ``present`` or ``pure``; + this is empty if no members are added. - Returned when: success and `state` is `present` + Returned when: success and ``state`` is ``present`` """ return self.acquire(server, 'added') def removed(self, server: str | None = None) -> list[Incomplete]: """ - A list of members removed when `state` is `absent` or `pure`; this is - empty if no members are removed. + A list of members removed when ``state`` is ``absent`` or ``pure``; + this is empty if no members are removed. - Returned when: success and `state` is `absent` + Returned when: success and ``state`` is ``absent`` """ return self.acquire(server, 'removed') @@ -4766,7 +4767,7 @@ class WinPowershellResults(RunnerResults): def result(self, server: str | None = None) -> Incomplete: """ - The values that were set by `$Ansible.Result` in the script. + The values that were set by ``$Ansible.Result`` in the script. Defaults to an empty dict but can be set to anything by the script. @@ -4817,7 +4818,7 @@ def warning(self, server: str | None = None) -> list[Incomplete]: """ A list of warning messages created by the script. - Warning messages only appear when `$WarningPreference = 'Continue'`. + Warning messages only appear when ``$WarningPreference = 'Continue'``. Returned when: always """ @@ -4827,7 +4828,7 @@ def verbose(self, server: str | None = None) -> list[Incomplete]: """ A list of warning messages created by the script. - Verbose messages only appear when `$VerbosePreference = 'Continue'`. + Verbose messages only appear when ``$VerbosePreference = 'Continue'``. Returned when: always """ @@ -4837,7 +4838,7 @@ def debug(self, server: str | None = None) -> list[Incomplete]: """ A list of warning messages created by the script. - Debug messages only appear when `$DebugPreference = 'Continue'`. + Debug messages only appear when ``$DebugPreference = 'Continue'``. Returned when: always """ @@ -5359,8 +5360,8 @@ def reboot_required(self, server: str | None = None) -> bool: def rebooted(self, server: str | None = None) -> bool: """ - Set to `true` when the target Windows host has been rebooted by - `win_updates`. + Set to ``true`` when the target Windows host has been rebooted by + ``win_updates``. Returned when: success """ @@ -5370,7 +5371,7 @@ def updates(self, server: str | None = None) -> dict[str, Incomplete]: """ Updates that were found/installed. - The key for each update is the `id` of the update. + The key for each update is the ``id`` of the update. Returned when: success """ @@ -5726,8 +5727,8 @@ def label(self, server: str | None = None) -> Incomplete: def impersonation_level(self, server: str | None = None) -> str: """ - The impersonation level of the token, only valid if `token_type` is - `TokenImpersonation`, see + The impersonation level of the token, only valid if ``token_type`` is + ``TokenImpersonation``, see `reference `__. Returned when: success diff --git a/src/suitable/_modules.py b/src/suitable/_modules.py index 96ec293..0129516 100644 --- a/src/suitable/_modules.py +++ b/src/suitable/_modules.py @@ -232,52 +232,53 @@ def apt( :ref:`ansible.builtin ` :param name: - A list of package names, like `foo`, or package specifier with - version, like `foo=1.0` or `foo>=1.0`. Name wildcards (fnmatch) - like `apt*` and version wildcards like `foo=1.0*` are also - supported. + A list of package names, like ``foo``, or package specifier with + version, like ``foo=1.0`` or ``foo>=1.0``. Name wildcards + (fnmatch) like ``apt*`` and version wildcards like ``foo=1.0*`` + are also supported. :param state: - Indicates the desired package state. `latest` ensures that the - latest version is installed. `build-dep` ensures the package build - dependencies are installed. `fixed` attempt to correct a system - with broken dependencies in place. + Indicates the desired package state. ``latest`` ensures that the + latest version is installed. ``build-dep`` ensures the package + build dependencies are installed. ``fixed`` attempt to correct a + system with broken dependencies in place. :param update_cache: - Run the equivalent of `apt-get update` before the operation. Can + Run the equivalent of ``apt-get update`` before the operation. Can be run as part of the package installation or as a separate step. Default is not to update the cache. :param update_cache_retries: Amount of retries if the cache update fails. Also see - `update_cache_retry_max_delay`. + ``update_cache_retry_max_delay``. :param update_cache_retry_max_delay: Use an exponential backoff delay for each retry (see - `update_cache_retries`) up to this max delay in seconds. + ``update_cache_retries``) up to this max delay in seconds. :param cache_valid_time: - Update the apt cache if it is older than the `cache_valid_time`. + Update the apt cache if it is older than the ``cache_valid_time``. This option is set in seconds. - As of Ansible 2.4, if explicitly set, this sets `update_cache=yes`. + As of Ansible 2.4, if explicitly set, this sets + ``update_cache=yes``. :param purge: - Will force purging of configuration files if `state=absent` or - `autoremove=yes`. + Will force purging of configuration files if ``state=absent`` or + ``autoremove=yes``. :param default_release: - Corresponds to the `-t` option for *apt* and sets pin priorities. + Corresponds to the ``-t`` option for *apt* and sets pin priorities. :param install_recommends: - Corresponds to the `--no-install-recommends` option for *apt*. - `true` installs recommended packages. `false` does not install + Corresponds to the ``--no-install-recommends`` option for *apt*. + ``true`` installs recommended packages. ``false`` does not install recommended packages. By default, Ansible will use the same defaults as the operating system. Suggested packages are never installed. :param force: - Corresponds to the `--force-yes` to *apt-get* and implies - `allow_unauthenticated=yes` and `allow_downgrade=yes`. + Corresponds to the ``--force-yes`` to *apt-get* and implies + ``allow_unauthenticated=yes`` and ``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 `-f` flag to + This option *is not* the equivalent of passing the ``-f`` flag to *apt-get* on the command line. **This is a destructive operation with the potential to destroy your system, and it should almost never be used.** Please also see - `man apt-get` for more information. + ``man apt-get`` for more information. :param clean: - Run the equivalent of `apt-get clean` to clear out the local + Run the equivalent of ``apt-get clean`` to clear out the local repository of retrieved package files. It removes everything but the lock file from /var/cache/apt/archives/ and /var/cache/apt/archives/partial/. @@ -286,18 +287,18 @@ def apt( :param allow_unauthenticated: Ignore if packages cannot be authenticated. This is useful for bootstrapping environments that manage their own apt-key setup. - `allow_unauthenticated` is only supported with `state`: - `install`/`present`. + ``allow_unauthenticated`` is only supported with ``state``: + ``install``/``present``. :param allow_downgrade: - Corresponds to the `--allow-downgrades` option for *apt*. + Corresponds to the ``--allow-downgrades`` option for *apt*. This option enables the named package and version to replace an already installed higher version of that package. - Note that setting `allow_downgrade=true` can make this module + Note that setting ``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). - `allow_downgrade` is only supported by `apt` and will be ignored - if `aptitude` is detected or specified. + ``allow_downgrade`` is only supported by ``apt`` and will be + ignored if ``aptitude`` is detected or specified. :param allow_change_held_packages: Allows changing the version of a package which is on the apt hold list. @@ -318,34 +319,35 @@ def apt( Path to a .deb package on the remote machine. If :// in the path, ansible will attempt to download deb before installing. (Version added 2.1). - Requires the `xz-utils` package to extract the control file of the - deb package to install. + Requires the ``xz-utils`` package to extract the control file of + the deb package to install. :param autoremove: - If `true`, remove unused dependency packages for all module states - except `build-dep`. It can also be used as the only option. + If ``true``, remove unused dependency packages for all module + states except ``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. :param autoclean: - If `true`, cleans the local repository of retrieved package files - that can no longer be downloaded. + If ``true``, cleans the local repository of retrieved package + files that can no longer be downloaded. :param policy_rc_d: Force the exit code of /usr/sbin/policy-rc.d. For example, if *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 `null`, the /usr/sbin/policy-rc.d isn't created/changed. + If ``null``, the /usr/sbin/policy-rc.d isn't created/changed. :param only_upgrade: Only upgrade a package if it is already installed. :param fail_on_autoremove: - Corresponds to the `--no-remove` option for `apt`. - If `true`, it is ensured that no packages will be removed or the + Corresponds to the ``--no-remove`` option for ``apt``. + If ``true``, it is ensured that no packages will be removed or the task will fail. - `fail_on_autoremove` is only supported with `state` except - `absent`. - `fail_on_autoremove` is only supported by `apt` and will be - ignored if `aptitude` is detected or specified. + ``fail_on_autoremove`` is only supported with ``state`` except + ``absent``. + ``fail_on_autoremove`` is only supported by ``apt`` and will be + ignored if ``aptitude`` is detected or specified. :param force_apt_get: Force usage of apt-get instead of aptitude. :param lock_timeout: @@ -381,14 +383,14 @@ def apt_key( 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 `state` is set to `absent`. + This parameter is required when ``state`` is set to ``absent``. :param data: The keyfile contents to add to the keyring. :param file: The path to a keyfile on the remote server to add to the keyring. :param keyring: The full path to specific keyring file in - `/etc/apt/trusted.gpg.d/`. + ``/etc/apt/trusted.gpg.d/``. :param url: The URL to retrieve key from. :param keyserver: @@ -396,7 +398,7 @@ def apt_key( :param state: Ensures that the key is present (added) or absent (revoked). :param validate_certs: - If `false`, SSL certificates for the target url will not be + If ``false``, SSL certificates for the target url will not be validated. This should only be used on personally controlled sites using self-signed certificates. """ # noqa: E501 @@ -430,16 +432,16 @@ def apt_repository( The octal mode for newly created files in sources.list.d. Default is what system uses (probably 0644). :param update_cache: - Run the equivalent of `apt-get update` when a change occurs. Cache - updates are run after making changes. + Run the equivalent of ``apt-get update`` when a change occurs. + Cache updates are run after making changes. :param update_cache_retries: Amount of retries if the cache update fails. Also see - `update_cache_retry_max_delay`. + ``update_cache_retry_max_delay``. :param update_cache_retry_max_delay: Use an exponential backoff delay for each retry (see - `update_cache_retries`) up to this max delay in seconds. + ``update_cache_retries``) up to this max delay in seconds. :param validate_certs: - If `false`, SSL certificates for the target repo will not be + If ``false``, SSL certificates for the target repo will not be validated. This should only be used on personally controlled sites using self-signed certificates. :param filename: @@ -454,12 +456,12 @@ def apt_repository( Whether to automatically try to install the Python apt library or not, if it is not already installed. Without this library, the module does not work. - Runs `apt-get install python-apt` for Python 2, and - `apt-get install python3-apt` for Python 3. + Runs ``apt-get install python-apt`` for Python 2, and + ``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 - `install_python_apt=false` and ensure that the Python apt library - for your Python version is installed some other way. + ``install_python_apt=false`` and ensure that the Python apt + library for your Python version is installed some other way. """ # noqa: E501 raise AttributeError('apt_repository') @@ -497,20 +499,20 @@ def assemble( A file to create using the concatenation of all of the source files. :param backup: - Create a backup file (if `true`), including the timestamp + Create a backup file (if ``true``), including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. :param delimiter: A delimiter to separate the file contents. :param remote_src: - If `false`, it will search for src at originating/master machine. - If `true`, it will go to the remote/target machine for the src. + If ``false``, it will search for src at originating/master machine. + If ``true``, it will go to the remote/target machine for the src. :param regexp: Assemble files only if the given regular expression matches the filename. If not set, all files are assembled. - Every `\\` (backslash) must be escaped as `\\\\` to comply to YAML - syntax. + Every ``\\`` (backslash) must be escaped as ``\\\\`` to comply to + YAML syntax. Uses `Python regular expressions `__. :param ignore_hidden: @@ -530,23 +532,23 @@ def assemble( For those used to */usr/bin/chmod* remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal - numbers (for example, `'644'` or `'1777'`) so Ansible receives a - string and can do its own conversion from string into number. - Adding a leading zero (for example, `0755`) works sometimes, but + numbers (for example, ``'644'`` or ``'1777'``) so Ansible receives + a string and can do its own conversion from string into number. + Adding a leading zero (for example, ``0755``) works sometimes, but can fail in loops and some other circumstances. Giving Ansible a number without following either 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, `u+rwx` or `u=rw,g=r,o=r`). - If `mode` is not specified and the destination filesystem object - **does not** exist, the default `umask` on the system will be used - when setting the mode for the newly created filesystem object. - If `mode` is not specified and the destination filesystem object + (for example, ``u+rwx`` or ``u=rw,g=r,o=r``). + If ``mode`` is not specified and the destination filesystem object + **does not** exist, the default ``umask`` on the system will be + used when setting the mode for the newly created filesystem object. + If ``mode`` is not specified and the destination filesystem object **does** exist, the mode of the existing filesystem object will be used. - Specifying `mode` is the best way to ensure filesystem objects are - created with the correct permissions. See CVE-2020-1736 for + Specifying ``mode`` is the best way to ensure filesystem objects + are created with the correct permissions. See CVE-2020-1736 for further details. :param owner: Name of the user that should own the filesystem object, as would @@ -563,21 +565,21 @@ def assemble( previous ownership. :param seuser: The user part of the SELinux filesystem object context. - By default it uses the `system` policy, where applicable. - When set to `_default`, it will use the `user` portion of the + By default it uses the ``system`` policy, where applicable. + When set to ``_default``, it will use the ``user`` portion of the policy if available. :param serole: The role part of the SELinux filesystem object context. - When set to `_default`, it will use the `role` portion of the + When set to ``_default``, it will use the ``role`` portion of the policy if available. :param setype: The type part of the SELinux filesystem object context. - When set to `_default`, it will use the `type` portion of the + When set to ``_default``, it will use the ``type`` portion of the policy if available. :param selevel: The level part of the SELinux filesystem object context. - This is the MLS/MCS attribute, sometimes known as the `range`. - When set to `_default`, it will use the `level` portion of the + This is the MLS/MCS attribute, sometimes known as the ``range``. + When set to ``_default``, it will use the ``level`` portion of the policy if available. :param unsafe_writes: Influence when to use atomic operation to prevent data corruption @@ -599,7 +601,7 @@ def assemble( target system. This string should contain the attributes in the same order as the one displayed by *lsattr*. - The `=` operator is assumed as default, otherwise `+` or `-` + The ``=`` operator is assumed as default, otherwise ``+`` or ``-`` operators need to be included in the string. """ # noqa: E501 raise AttributeError('assemble') @@ -628,7 +630,7 @@ def assert_( :param success_msg: The customized message used for a successful assertion. :param quiet: - Set this to `true` to avoid verbose output. + Set this to ``true`` to avoid verbose output. """ # noqa: E501 raise AttributeError('assert') @@ -658,10 +660,10 @@ def async_status( :param jid: Job or task identifier. :param mode: - If `status`, obtain the status. - If `cleanup`, clean up the async job cache (by default in - `~/.ansible_async/`) for the specified job `jid`, without waiting - for it to finish. + If ``status``, obtain the status. + If ``cleanup``, clean up the async job cache (by default in + ``~/.ansible_async/``) for the specified job ``jid``, without + waiting for it to finish. """ # noqa: E501 raise AttributeError('async_status') @@ -699,41 +701,41 @@ def blockinfile( :param path: The file to modify. - Before Ansible 2.3 this option was only usable as `dest`, - `destfile` and `name`. + Before Ansible 2.3 this option was only usable as ``dest``, + ``destfile`` and ``name``. :param state: Whether the block should be there or not. :param marker: The marker line template. - `{mark}` will be replaced with the values in `marker_begin` - (default="BEGIN") and `marker_end` (default="END"). - Using a custom marker without the `{mark}` variable may result in - the block being repeatedly inserted on subsequent playbook runs. + ``{mark}`` will be replaced with the values in ``marker_begin`` + (default="BEGIN") and ``marker_end`` (default="END"). + Using a custom marker without the ``{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 - `marker_begin` and `marker_end`. + ``marker_begin`` and ``marker_end``. :param block: The text to insert inside the marker lines. If it is missing or an empty string, the block will be removed as - if `state` were specified to `absent`. + if ``state`` were specified to ``absent``. :param insertafter: - If specified and no begin/ending `marker` lines are found, the + If specified and no begin/ending ``marker`` lines are found, the block will be inserted after the last match of specified regular expression. - A special value is available; `EOF` for inserting the block at the - end of the file. - If specified regular expression has no matches, `EOF` will be used - instead. + A special value is available; ``EOF`` for inserting the block at + the end of the file. + If specified regular expression has no matches, ``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. :param insertbefore: - If specified and no begin/ending `marker` lines are found, the + If specified and no begin/ending ``marker`` lines are found, the block will be inserted before the last match of specified regular expression. - A special value is available; `BOF` for inserting the block at the - beginning of the file. + A special value is available; ``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 @@ -746,45 +748,45 @@ def blockinfile( can get the original file back if you somehow clobbered it incorrectly. :param marker_begin: - This will be inserted at `{mark}` in the opening ansible block - `marker`. + This will be inserted at ``{mark}`` in the opening ansible block + ``marker``. :param marker_end: - This will be inserted at `{mark}` in the closing ansible block - `marker`. + This will be inserted at ``{mark}`` in the closing ansible block + ``marker``. :param append_newline: Append a blank line to the inserted block, if this does not appear at the end of the file. - Note that this attribute is not considered when `state` is set to - `absent`. + Note that this attribute is not considered when ``state`` is set + to ``absent``. Requires ansible-core >= 2.16 :param prepend_newline: Prepend a blank line to the inserted block, if this does not appear at the beginning of the file. - Note that this attribute is not considered when `state` is set to - `absent`. + Note that this attribute is not considered when ``state`` is set + to ``absent``. Requires ansible-core >= 2.16 :param mode: The permissions the resulting filesystem object should have. For those used to */usr/bin/chmod* remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal - numbers (for example, `'644'` or `'1777'`) so Ansible receives a - string and can do its own conversion from string into number. - Adding a leading zero (for example, `0755`) works sometimes, but + numbers (for example, ``'644'`` or ``'1777'``) so Ansible receives + a string and can do its own conversion from string into number. + Adding a leading zero (for example, ``0755``) works sometimes, but can fail in loops and some other circumstances. Giving Ansible a number without following either 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, `u+rwx` or `u=rw,g=r,o=r`). - If `mode` is not specified and the destination filesystem object - **does not** exist, the default `umask` on the system will be used - when setting the mode for the newly created filesystem object. - If `mode` is not specified and the destination filesystem object + (for example, ``u+rwx`` or ``u=rw,g=r,o=r``). + If ``mode`` is not specified and the destination filesystem object + **does not** exist, the default ``umask`` on the system will be + used when setting the mode for the newly created filesystem object. + If ``mode`` is not specified and the destination filesystem object **does** exist, the mode of the existing filesystem object will be used. - Specifying `mode` is the best way to ensure filesystem objects are - created with the correct permissions. See CVE-2020-1736 for + Specifying ``mode`` is the best way to ensure filesystem objects + are created with the correct permissions. See CVE-2020-1736 for further details. :param owner: Name of the user that should own the filesystem object, as would @@ -801,21 +803,21 @@ def blockinfile( previous ownership. :param seuser: The user part of the SELinux filesystem object context. - By default it uses the `system` policy, where applicable. - When set to `_default`, it will use the `user` portion of the + By default it uses the ``system`` policy, where applicable. + When set to ``_default``, it will use the ``user`` portion of the policy if available. :param serole: The role part of the SELinux filesystem object context. - When set to `_default`, it will use the `role` portion of the + When set to ``_default``, it will use the ``role`` portion of the policy if available. :param setype: The type part of the SELinux filesystem object context. - When set to `_default`, it will use the `type` portion of the + When set to ``_default``, it will use the ``type`` portion of the policy if available. :param selevel: The level part of the SELinux filesystem object context. - This is the MLS/MCS attribute, sometimes known as the `range`. - When set to `_default`, it will use the `level` portion of the + This is the MLS/MCS attribute, sometimes known as the ``range``. + When set to ``_default``, it will use the ``level`` portion of the policy if available. :param unsafe_writes: Influence when to use atomic operation to prevent data corruption @@ -837,7 +839,7 @@ def blockinfile( target system. This string should contain the attributes in the same order as the one displayed by *lsattr*. - The `=` operator is assumed as default, otherwise `+` or `-` + The ``=`` operator is assumed as default, otherwise ``+`` or ``-`` operators need to be included in the string. :param validate: The validation command to run before copying the updated file into @@ -847,7 +849,7 @@ def blockinfile( Also, the command is passed securely so shell features such as expansion and pipes will not work. For an example on how to handle more complex validation than what - this option provides, see `handling complex validation`. + this option provides, see ``handling complex validation``. """ # noqa: E501 raise AttributeError('blockinfile') @@ -889,33 +891,33 @@ def command(self, *args: Any, **kwargs: Any) -> CommandResults: * :ref:`community.routeros ` :param expand_argument_vars: - Expands the arguments that are variables, for example `$HOME` will - be expanded before being passed to the command to run. - Set to `false` to disable expansion and treat the value as a + Expands the arguments that are variables, for example ``$HOME`` + will be expanded before being passed to the command to run. + Set to ``false`` to disable expansion and treat the value as a literal argument. Requires ansible-core >= 2.16 :param cmd: The command to run. :param argv: Passes the command as a list rather than a string. - Use `argv` to avoid quoting values that would otherwise be + Use ``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. :param creates: A filename or (since 2.0) glob pattern. If a matching file already exists, this step **will not** be run. - This is checked before `removes` is checked. + This is checked before ``removes`` is checked. :param removes: A filename or (since 2.0) glob pattern. If a matching file exists, this step **will** be run. - This is checked after `creates` is checked. + This is checked after ``creates`` is checked. :param chdir: Change into this directory before running the command. :param stdin: Set the stdin of the command directly to the specified value. :param stdin_add_newline: - If set to `true`, append a newline to stdin data. + If set to ``true``, append a newline to stdin data. :param strip_empty_ends: Strip empty lines from the end of stdout/stderr in result. """ # noqa: E501 @@ -959,71 +961,74 @@ def copy( path ends with "/", only inside contents of that directory are copied to destination. Otherwise, if it does not end with "/", the directory itself with all contents is copied. This behavior is - similar to the `rsync` command line tool. + similar to the ``rsync`` command line tool. :param content: - When used instead of `src`, sets the contents of a file directly + When used instead of ``src``, sets the contents of a file directly to the specified value. - Works only when `dest` is a file. Creates the file if it does not - exist. - For advanced formatting or if `content` contains a variable, use - the :meth:`ansible.builtin.template` module. + Works only when ``dest`` is a file. Creates the file if it does + not exist. + For advanced formatting or if ``content`` contains a variable, use + the :meth:`template` module. :param dest: Remote absolute path where the file should be copied to. - If `src` is a directory, this must be a directory too. - If `dest` is a non-existent path and if either `dest` ends with - "/" or `src` is a directory, `dest` is created. - If `dest` is a relative path, the starting directory is determined - by the remote host. - If `src` and `dest` are files, the parent directory of `dest` is - not created and the task fails if it does not already exist. + If ``src`` is a directory, this must be a directory too. + If ``dest`` is a non-existent path and if either ``dest`` ends + with "/" or ``src`` is a directory, ``dest`` is created. + If ``dest`` is a relative path, the starting directory is + determined by the remote host. + If ``src`` and ``dest`` are files, the parent directory of + ``dest`` is not created and the task fails if it does not already + exist. :param backup: Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. :param force: Influence whether the remote file must always be replaced. - If `true`, the remote file will be replaced when contents are + If ``true``, the remote file will be replaced when contents are different than the source. - If `false`, the file will only be transferred if the destination + If ``false``, the file will only be transferred if the destination does not exist. :param mode: The permissions of the destination file or directory. - For those used to `/usr/bin/chmod` remember that modes are + For those used to ``/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 `0644` or - `01777`) or quote it (like `'644'` or `'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. + Ansible's YAML parser knows it is an octal number (like ``0644`` + or ``01777``) or quote it (like ``'644'`` or ``'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, `u+rwx` or `u=rw,g=r,o=r`). + (for example, ``u+rwx`` or ``u=rw,g=r,o=r``). As of Ansible 2.3, the mode may also be the special string - `preserve`. - `preserve` means that the file will be given the same permissions - as the source file. - When doing a recursive copy, see also `directory_mode`. - If `mode` is not specified and the destination file **does not** - exist, the default `umask` on the system will be used when setting - the mode for the newly created file. - If `mode` is not specified and the destination file **does** + ``preserve``. + ``preserve`` means that the file will be given the same + permissions as the source file. + When doing a recursive copy, see also ``directory_mode``. + If ``mode`` is not specified and the destination file **does not** + exist, the default ``umask`` on the system will be used when + setting the mode for the newly created file. + If ``mode`` is not specified and the destination file **does** exist, the mode of the existing file will be used. - Specifying `mode` is the best way to ensure files are created with - the correct permissions. See CVE-2020-1736 for further details. + Specifying ``mode`` is the best way to ensure files are created + with the correct permissions. See CVE-2020-1736 for further + details. :param directory_mode: Set the access permissions of newly created directories to the given mode. Permissions on existing directories do not change. - See `mode` for the syntax of accepted values. + See ``mode`` for the syntax of accepted values. The target system's defaults determine permissions when this parameter is not set. :param remote_src: - Influence whether `src` needs to be transferred or already is + Influence whether ``src`` needs to be transferred or already is present remotely. - If `false`, it will search for `src` on the controller node. - If `true` it will search for `src` on the managed (remote) node. - `remote_src` supports recursive copying as of version 2.8. - `remote_src` only works with `mode=preserve` as of version 2.6. - Auto-decryption of files does not work when `remote_src=yes`. + If ``false``, it will search for ``src`` on the controller node. + If ``true`` it will search for ``src`` on the managed (remote) + node. + ``remote_src`` supports recursive copying as of version 2.8. + ``remote_src`` only works with ``mode=preserve`` as of version 2.6. + Auto-decryption of files does not work when ``remote_src=yes``. :param follow: This flag indicates that filesystem links in the destination, if they exist, should be followed. @@ -1053,21 +1058,21 @@ def copy( previous ownership. :param seuser: The user part of the SELinux filesystem object context. - By default it uses the `system` policy, where applicable. - When set to `_default`, it will use the `user` portion of the + By default it uses the ``system`` policy, where applicable. + When set to ``_default``, it will use the ``user`` portion of the policy if available. :param serole: The role part of the SELinux filesystem object context. - When set to `_default`, it will use the `role` portion of the + When set to ``_default``, it will use the ``role`` portion of the policy if available. :param setype: The type part of the SELinux filesystem object context. - When set to `_default`, it will use the `type` portion of the + When set to ``_default``, it will use the ``type`` portion of the policy if available. :param selevel: The level part of the SELinux filesystem object context. - This is the MLS/MCS attribute, sometimes known as the `range`. - When set to `_default`, it will use the `level` portion of the + This is the MLS/MCS attribute, sometimes known as the ``range``. + When set to ``_default``, it will use the ``level`` portion of the policy if available. :param unsafe_writes: Influence when to use atomic operation to prevent data corruption @@ -1089,7 +1094,7 @@ def copy( target system. This string should contain the attributes in the same order as the one displayed by *lsattr*. - The `=` operator is assumed as default, otherwise `+` or `-` + The ``=`` operator is assumed as default, otherwise ``+`` or ``-`` operators need to be included in the string. :param validate: The validation command to run before copying the updated file into @@ -1099,7 +1104,7 @@ def copy( Also, the command is passed securely so shell features such as expansion and pipes will not work. For an example on how to handle more complex validation than what - this option provides, see `handling complex validation`. + this option provides, see ``handling complex validation``. """ # noqa: E501 raise AttributeError('copy') @@ -1148,7 +1153,7 @@ def cron( The command to execute or, if env is set, the value of environment variable. The command should not contain line breaks. - Required if `state=present`. + Required if ``state=present``. :param state: Whether to ensure the job or environment variable is present or absent. @@ -1158,46 +1163,47 @@ def cron( 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 - `/etc/cron.d`. + ``/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 `user` as well, - unless `state` is not `present`. - Either this parameter or `name` is required. + Using this parameter requires you to specify the ``user`` as well, + unless ``state`` is not ``present``. + Either this parameter or ``name`` is required. :param backup: If set, create a backup of the crontab before it is modified. The - location of the backup is returned in the `ignore:backup_file` + location of the backup is returned in the ``ignore:backup_file`` variable by this module. :param minute: - Minute when the job should run (`0-59`, `*`, `*/2`, and so on). + Minute when the job should run (``0-59``, ``*``, ``*/2``, and so + on). :param hour: - Hour when the job should run (`0-23`, `*`, `*/2`, and so on). + Hour when the job should run (``0-23``, ``*``, ``*/2``, and so on). :param day: - Day of the month the job should run (`1-31`, `*`, `*/2`, and so - on). + Day of the month the job should run (``1-31``, ``*``, ``*/2``, and + so on). :param month: - Month of the year the job should run (`1-12`, `*`, `*/2`, and so - on). + Month of the year the job should run (``1-12``, ``*``, ``*/2``, + and so on). :param weekday: - Day of the week that the job should run (`0-6` for - Sunday-Saturday, `*`, and so on). + Day of the week that the job should run (``0-6`` for + Sunday-Saturday, ``*``, and so on). :param special_time: Special time specification nickname. :param disabled: If the job should be disabled (commented out) in the crontab. - Only has effect if `state=present`. + Only has effect if ``state=present``. :param env: If set, manages a crontab's environment variable. New variables are added on top of crontab. - `name` and `value` parameters are the name and the value of + ``name`` and ``value`` parameters are the name and the value of environment variable. :param insertafter: - Used with `state=present` and `env`. + Used with ``state=present`` and ``env``. If specified, the environment variable will be inserted after the declaration of specified environment variable. :param insertbefore: - Used with `state=present` and `env`. + Used with ``state=present`` and ``env``. If specified, the environment variable will be inserted before the declaration of specified environment variable. """ # noqa: E501 @@ -1270,20 +1276,20 @@ def deb822_repository( Defines which languages information such as translated package descriptions should be downloaded. :param name: - Name of the repo. Specifically used for `X-Repolib-Name` and in + Name of the repo. Specifically used for ``X-Repolib-Name`` and in naming the repository and signing key files. :param pdiffs: Controls if APT should try to use PDiffs to update old indexes instead of downloading the new indexes entirely. :param signed_by: Either a URL to a GPG key, absolute path to a keyring file, one or - more fingerprints of keys either in the `trusted.gpg` keyring or - in the keyrings in the `trusted.gpg.d/` directory, or an ASCII + more fingerprints of keys either in the ``trusted.gpg`` keyring or + in the keyrings in the ``trusted.gpg.d/`` directory, or an ASCII armored GPG public key block. :param suites: Suite can specify an exact path in relation to the UR*s* provided, in which case the Components: must be omitted and suite must end - with a slash (`/`). Alternatively, it may take the form of a + with a slash (``/``). 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. @@ -1295,7 +1301,7 @@ def deb822_repository( raised before e.g. packages are installed from this source. :param types: Which types of packages to look for from a given source; either - binary `deb` or source code `deb-src`. + binary ``deb`` or source code ``deb-src``. :param uris: The URIs must specify the base of the Debian distribution archive, from which APT finds the information it needs. @@ -1338,14 +1344,14 @@ def debconf( A debconf configuration setting. :param vtype: The type of the value supplied. - It is highly recommended to add `no_log=True` to task while - specifying `vtype=password`. - `seen` was added in Ansible 2.2. - After Ansible 2.17, user can specify `value` as a list, if `vtype` - is set as `multiselect`. + It is highly recommended to add ``no_log=True`` to task while + specifying ``vtype=password``. + ``seen`` was added in Ansible 2.2. + After Ansible 2.17, user can specify ``value`` as a list, if + ``vtype`` is set as ``multiselect``. :param value: Value to set the configuration to. - After Ansible 2.17, `value` is of type 'raw'. + After Ansible 2.17, ``value`` is of type 'raw'. :param unseen: Do not set 'seen' flag when pre-seeding. """ # noqa: E501 @@ -1369,9 +1375,9 @@ def debug( generic message. :param var: A variable name to debug. - Mutually exclusive with the `msg` option. + Mutually exclusive with the ``msg`` option. Be aware that this option already runs in Jinja2 context and has - an implicit `{{ }}` wrapping, so you should not be using Jinja2 + an implicit ``{{ }}`` wrapping, so you should not be using Jinja2 delimiters unless you are looking for double interpolation. :param verbosity: A number that controls when the debug is run, if you set to 3 it @@ -1438,27 +1444,27 @@ def dnf( Backend module to use. Requires ansible-core >= 2.15 :param name: - A package name or package specifier with version, like `name-1.0`. - When using state=latest, this can be '*' which means run: dnf -y - update. You can also pass a url or a local path to an rpm file. To - operate on several packages this can accept a comma separated - string of packages or a list of packages. - Comparison operators for package version are valid here `>`, `<`, - `>=`, `<=`. Example - `name >= 1.0`. Spaces around the operator - are required. + A package name or package specifier with version, like + ``name-1.0``. When using state=latest, this can be '*' which means + run: dnf -y update. You can also pass a url or a local path to an + rpm file. To operate on several packages this can accept a comma + separated string of packages or a list of packages. + Comparison operators for package version are valid here ``>``, + ``<``, ``>=``, ``<=``. Example - ``name >= 1.0``. Spaces around + the operator are required. You can also pass an absolute path for a binary which is provided by the package to install. See examples for more information. :param list: Various (non-idempotent) commands for usage with - `/usr/bin/ansible` and *not* playbooks. Use - :meth:`ansible.builtin.package_facts` instead of the `list` - argument as a best practice. + ``/usr/bin/ansible`` and *not* playbooks. Use + :meth:`package_facts` instead of the ``list`` argument as a best + practice. :param state: - Whether to install (`present`, `latest`), or remove (`absent`) a - package. - Default is `None`, however in effect the default action is - `present` unless the `autoremove` option is enabled for this - module, then `absent` is inferred. + Whether to install (``present``, ``latest``), or remove + (``absent``) a package. + Default is ``None``, however in effect the default action is + ``present`` unless the ``autoremove`` option is enabled for this + module, then ``absent`` is inferred. :param enablerepo: *Repoid* of repositories to enable for the install/update operation. These repos will not persist beyond the transaction. @@ -1471,8 +1477,8 @@ def dnf( The remote dnf configuration file to use for the transaction. :param disable_gpg_check: Whether to disable the GPG checking of signatures of packages - being installed. Has an effect only if `state` is `present` or - `latest`. + being installed. Has an effect only if ``state`` is ``present`` or + ``latest``. This setting affects packages installed from a repository as well as "local" packages installed from the filesystem or a URL. :param installroot: @@ -1482,10 +1488,10 @@ def dnf( Specifies an alternative release from which all packages will be installed. :param autoremove: - If `true`, removes all "leaf" packages from the system that were + If ``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 `absent`. + used alone or when ``state`` is ``absent``. :param exclude: Package name(s) to exclude when state=present, or latest. This can be a list or a comma separated string. @@ -1495,20 +1501,21 @@ def dnf( option. :param update_cache: Force dnf to check if cache is out of date and redownload if - needed. Has an effect only if `state` is `present` or `latest`. + needed. Has an effect only if ``state`` is ``present`` or + ``latest``. :param update_only: When using latest, only update installed packages. Do not install packages. - Has an effect only if `state` is `latest`. + Has an effect only if ``state`` is ``latest``. :param security: - If set to `true`, and `state=latest` then only installs updates - that have been marked security related. - Note that, similar to `dnf upgrade-minimal`, this filter applies + If set to ``true``, and ``state=latest`` then only installs + updates that have been marked security related. + Note that, similar to ``dnf upgrade-minimal``, this filter applies to dependencies as well. :param bugfix: - If set to `true`, and `state=latest` then only installs updates - that have been marked bugfix related. - Note that, similar to `dnf upgrade-minimal`, this filter applies + If set to ``true``, and ``state=latest`` then only installs + updates that have been marked bugfix related. + Note that, similar to ``dnf upgrade-minimal``, this filter applies to dependencies as well. :param enable_plugin: *Plugin* name to enable for the install/update operation. The @@ -1518,20 +1525,20 @@ def dnf( disabled plugins will not persist beyond the transaction. :param disable_excludes: Disable the excludes defined in DNF config files. - If set to `all`, disables all excludes. - If set to `main`, disable excludes defined in [main] in dnf.conf. - If set to `repoid`, disable excludes defined for given repo id. + If set to ``all``, disables all excludes. + If set to ``main``, disable excludes defined in [main] in dnf.conf. + If set to ``repoid``, disable excludes defined for given repo id. :param validate_certs: This only applies if using a https url as the source of the rpm. - e.g. for localinstall. If set to `false`, the SSL certificates + e.g. for localinstall. If set to ``false``, the SSL certificates will not be validated. - This should only set to `false` used on personally controlled + This should only set to ``false`` used on personally controlled sites using self-signed certificates as it avoids verifying the source site. :param sslverify: Disables SSL validation of the repository server for this transaction. - This should be set to `false` if one of the configured + This should be set to ``false`` if one of the configured repositories is using an untrusted or self-signed certificate. :param allow_downgrade: Specify if the named package and version is allowed to downgrade a @@ -1554,20 +1561,20 @@ def dnf( relation. :param download_dir: Specifies an alternate directory to store packages. - Has an effect only if `download_only` is specified. + Has an effect only if ``download_only`` is specified. :param allowerasing: - If `true` it allows erasing of installed packages to resolve + If ``true`` it allows erasing of installed packages to resolve dependencies. :param nobest: - This is the opposite of the `best` option kept for backwards + This is the opposite of the ``best`` option kept for backwards compatibility. Since ansible-core 2.17 the default value is set by the operating system distribution. :param best: - When set to `true`, either use a package with the highest version - available or fail. - When set to `false`, if the latest version cannot be installed go - with the lower version. + When set to ``true``, either use a package with the highest + version available or fail. + When set to ``false``, if the latest version cannot be installed + go with the lower version. Default is set by the operating system distribution. Requires ansible-core >= 2.17 :param cacheonly: @@ -1626,27 +1633,27 @@ def dnf5( .. note:: Requires ansible-core >= 2.15 :param name: - A package name or package specifier with version, like `name-1.0`. - When using state=latest, this can be '*' which means run: dnf -y - update. You can also pass a url or a local path to an rpm file. To - operate on several packages this can accept a comma separated - string of packages or a list of packages. - Comparison operators for package version are valid here `>`, `<`, - `>=`, `<=`. Example - `name >= 1.0`. Spaces around the operator - are required. + A package name or package specifier with version, like + ``name-1.0``. When using state=latest, this can be '*' which means + run: dnf -y update. You can also pass a url or a local path to an + rpm file. To operate on several packages this can accept a comma + separated string of packages or a list of packages. + Comparison operators for package version are valid here ``>``, + ``<``, ``>=``, ``<=``. Example - ``name >= 1.0``. Spaces around + the operator are required. You can also pass an absolute path for a binary which is provided by the package to install. See examples for more information. :param list: Various (non-idempotent) commands for usage with - `/usr/bin/ansible` and *not* playbooks. Use - :meth:`ansible.builtin.package_facts` instead of the `list` - argument as a best practice. + ``/usr/bin/ansible`` and *not* playbooks. Use + :meth:`package_facts` instead of the ``list`` argument as a best + practice. :param state: - Whether to install (`present`, `latest`), or remove (`absent`) a - package. - Default is `None`, however in effect the default action is - `present` unless the `autoremove` option is enabled for this - module, then `absent` is inferred. + Whether to install (``present``, ``latest``), or remove + (``absent``) a package. + Default is ``None``, however in effect the default action is + ``present`` unless the ``autoremove`` option is enabled for this + module, then ``absent`` is inferred. :param enablerepo: *Repoid* of repositories to enable for the install/update operation. These repos will not persist beyond the transaction. @@ -1659,8 +1666,8 @@ def dnf5( The remote dnf configuration file to use for the transaction. :param disable_gpg_check: Whether to disable the GPG checking of signatures of packages - being installed. Has an effect only if `state` is `present` or - `latest`. + being installed. Has an effect only if ``state`` is ``present`` or + ``latest``. This setting affects packages installed from a repository as well as "local" packages installed from the filesystem or a URL. :param installroot: @@ -1670,10 +1677,10 @@ def dnf5( Specifies an alternative release from which all packages will be installed. :param autoremove: - If `true`, removes all "leaf" packages from the system that were + If ``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 `absent`. + used alone or when ``state`` is ``absent``. :param exclude: Package name(s) to exclude when state=present, or latest. This can be a list or a comma separated string. @@ -1683,20 +1690,21 @@ def dnf5( option. :param update_cache: Force dnf to check if cache is out of date and redownload if - needed. Has an effect only if `state` is `present` or `latest`. + needed. Has an effect only if ``state`` is ``present`` or + ``latest``. :param update_only: When using latest, only update installed packages. Do not install packages. - Has an effect only if `state` is `latest`. + Has an effect only if ``state`` is ``latest``. :param security: - If set to `true`, and `state=latest` then only installs updates - that have been marked security related. - Note that, similar to `dnf upgrade-minimal`, this filter applies + If set to ``true``, and ``state=latest`` then only installs + updates that have been marked security related. + Note that, similar to ``dnf upgrade-minimal``, this filter applies to dependencies as well. :param bugfix: - If set to `true`, and `state=latest` then only installs updates - that have been marked bugfix related. - Note that, similar to `dnf upgrade-minimal`, this filter applies + If set to ``true``, and ``state=latest`` then only installs + updates that have been marked bugfix related. + Note that, similar to ``dnf upgrade-minimal``, this filter applies to dependencies as well. :param enable_plugin: This is currently a no-op as dnf5 itself does not implement this @@ -1710,18 +1718,18 @@ def dnf5( disabled plugins will not persist beyond the transaction. :param disable_excludes: Disable the excludes defined in DNF config files. - If set to `all`, disables all excludes. - If set to `main`, disable excludes defined in [main] in dnf.conf. - If set to `repoid`, disable excludes defined for given repo id. + If set to ``all``, disables all excludes. + If set to ``main``, disable excludes defined in [main] in dnf.conf. + If set to ``repoid``, disable excludes defined for given repo id. :param validate_certs: 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 - :meth:`ansible.builtin.dnf` module. + :meth:`dnf` module. :param sslverify: Disables SSL validation of the repository server for this transaction. - This should be set to `false` if one of the configured + This should be set to ``false`` if one of the configured repositories is using an untrusted or self-signed certificate. :param allow_downgrade: Specify if the named package and version is allowed to downgrade a @@ -1746,20 +1754,20 @@ def dnf5( relation. :param download_dir: Specifies an alternate directory to store packages. - Has an effect only if `download_only` is specified. + Has an effect only if ``download_only`` is specified. :param allowerasing: - If `true` it allows erasing of installed packages to resolve + If ``true`` it allows erasing of installed packages to resolve dependencies. :param nobest: - This is the opposite of the `best` option kept for backwards + This is the opposite of the ``best`` option kept for backwards compatibility. Since ansible-core 2.17 the default value is set by the operating system distribution. :param best: - When set to `true`, either use a package with the highest version - available or fail. - When set to `false`, if the latest version cannot be installed go - with the lower version. + When set to ``true``, either use a package with the highest + version available or fail. + When set to ``false``, if the latest version cannot be installed + go with the lower version. Default is set by the operating system distribution. Requires ansible-core >= 2.17 :param cacheonly: @@ -1819,7 +1827,7 @@ def expect( Change into this directory before running the command. :param responses: Mapping of prompt regular expressions and corresponding answer(s). - Each key in `responses` is a Python regex + Each key in ``responses`` is a Python regex `regular-expression-syntax `__. The value of each key is a string or list of strings. If the value is a string and the prompt is encountered multiple times, the @@ -1827,7 +1835,7 @@ def expect( different answers for successive matches. :param timeout: Amount of time in seconds to wait for the expected strings. Use - `null` to disable timeout. + ``null`` to disable timeout. :param echo: Whether or not to echo out your response strings. """ # noqa: E501 @@ -1871,23 +1879,23 @@ def fetch( Recursive fetching may be supported in a later release. :param dest: A directory to save the file into. - For example, if the `dest` directory is `/backup` a `src` file - named `/etc/profile` on host `host.example.com`, would be saved - into `/backup/host.example.com/etc/profile`. The host name is - based on the inventory name. + For example, if the ``dest`` directory is ``/backup`` a ``src`` + file named ``/etc/profile`` on host ``host.example.com``, would be + saved into ``/backup/host.example.com/etc/profile``. The host name + is based on the inventory name. :param fail_on_missing: - When set to `true`, the task will fail if the remote file cannot + When set to ``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 `true` in Ansible 2.5. + The default was changed to ``true`` in Ansible 2.5. :param validate_checksum: Verify that the source and destination checksums match after the files are fetched. :param flat: Allows you to override the default behavior of appending hostname/path/to/file to the destination. - If `dest` ends with '/', it will use the basename of the source + If ``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. @@ -1935,102 +1943,102 @@ def file( :param path: Path to the file being managed. :param state: - If `absent`, directories will be recursively deleted, and files or - symlinks will be unlinked. In the case of a directory, if `diff` - is declared, you will see the files and folders deleted listed - under `path_contents`. Note that `absent` will not cause - :meth:`ansible.builtin.file` to fail if the `path` does not exist - as the state did not change. - If `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 `file`, with no other options, returns the current state of - `path`. - If `file`, even with other options (such as `mode`), the file will - be modified if it exists but will NOT be created if it does not - exist. Set to `touch` or use the :meth:`ansible.builtin.copy` or - :meth:`ansible.builtin.template` module if you want to create the - file if it does not exist. - If `hard`, the hard link will be created or changed. - If `link`, the symbolic link will be created or changed. - If `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 - `touch` works from the command line). - Default is the current state of the file if it exists, `directory` - if `recurse=yes`, or `file` otherwise. + If ``absent``, directories will be recursively deleted, and files + or symlinks will be unlinked. In the case of a directory, if + ``diff`` is declared, you will see the files and folders deleted + listed under ``path_contents``. Note that ``absent`` will not + cause :meth:`file` to fail if the ``path`` does not exist as the + state did not change. + If ``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 ``file``, with no other options, returns the current state of + ``path``. + If ``file``, even with other options (such as ``mode``), the file + will be modified if it exists but will NOT be created if it does + not exist. Set to ``touch`` or use the :meth:`copy` or + :meth:`template` module if you want to create the file if it does + not exist. + If ``hard``, the hard link will be created or changed. + If ``link``, the symbolic link will be created or changed. + If ``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 ``touch`` works from the command line). + Default is the current state of the file if it exists, + ``directory`` if ``recurse=yes``, or ``file`` otherwise. :param src: Path of the file to link to. - This applies only to `state=link` and `state=hard`. - For `state=link`, this will also accept a non-existing path. - Relative paths are relative to the file being created (`path`) - which is how the Unix command `ln -s SRC DEST` treats relative + This applies only to ``state=link`` and ``state=hard``. + For ``state=link``, this will also accept a non-existing path. + Relative paths are relative to the file being created (``path``) + which is how the Unix command ``ln -s SRC DEST`` treats relative paths. :param recurse: Recursively set the specified file attributes on directory contents. - This applies only when `state` is set to `directory`. + This applies only when ``state`` is set to ``directory``. :param force: 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 `path` file and create a - symlink to the `src` file in place of it). + is a file (so, we need to unlink the ``path`` file and create a + symlink to the ``src`` file in place of it). :param follow: This flag indicates that filesystem links, if they exist, should be followed. - `follow=yes` and `state=link` can modify `src` when combined with - parameters such as `mode`. - Previous to Ansible 2.5, this was `false` by default. + ``follow=yes`` and ``state=link`` can modify ``src`` when combined + with parameters such as ``mode``. + Previous to Ansible 2.5, this was ``false`` by default. While creating a symlink with a non-existent destination, set - `follow` to `false` to avoid a warning message related to + ``follow`` to ``false`` to avoid a warning message related to permission issues. The warning message is added to notify the user that we can not set permissions to the non-existent destination. :param modification_time: This parameter indicates the time the file's modification time should be set to. - Should be `preserve` when no modification is required, - `YYYYMMDDHHMM.SS` when using default time format, or `now`. - Default is None meaning that `preserve` is the default for - `state=[file,directory,link,hard]` and `now` is default for - `state=touch`. + Should be ``preserve`` when no modification is required, + ``YYYYMMDDHHMM.SS`` when using default time format, or ``now``. + Default is None meaning that ``preserve`` is the default for + ``state=[file,directory,link,hard]`` and ``now`` is default for + ``state=touch``. :param modification_time_format: - When used with `modification_time`, indicates the time format that - must be used. + When used with ``modification_time``, indicates the time format + that must be used. Based on default Python format (see time.strftime doc). :param access_time: This parameter indicates the time the file's access time should be set to. - Should be `preserve` when no modification is required, - `YYYYMMDDHHMM.SS` when using default time format, or `now`. - Default is `None` meaning that `preserve` is the default for - `state=[file,directory,link,hard]` and `now` is default for - `state=touch`. + Should be ``preserve`` when no modification is required, + ``YYYYMMDDHHMM.SS`` when using default time format, or ``now``. + Default is ``None`` meaning that ``preserve`` is the default for + ``state=[file,directory,link,hard]`` and ``now`` is default for + ``state=touch``. :param access_time_format: - When used with `access_time`, indicates the time format that must - be used. + When used with ``access_time``, indicates the time format that + must be used. Based on default Python format (see time.strftime doc). :param mode: The permissions the resulting filesystem object should have. For those used to */usr/bin/chmod* remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal - numbers (for example, `'644'` or `'1777'`) so Ansible receives a - string and can do its own conversion from string into number. - Adding a leading zero (for example, `0755`) works sometimes, but + numbers (for example, ``'644'`` or ``'1777'``) so Ansible receives + a string and can do its own conversion from string into number. + Adding a leading zero (for example, ``0755``) works sometimes, but can fail in loops and some other circumstances. Giving Ansible a number without following either 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, `u+rwx` or `u=rw,g=r,o=r`). - If `mode` is not specified and the destination filesystem object - **does not** exist, the default `umask` on the system will be used - when setting the mode for the newly created filesystem object. - If `mode` is not specified and the destination filesystem object + (for example, ``u+rwx`` or ``u=rw,g=r,o=r``). + If ``mode`` is not specified and the destination filesystem object + **does not** exist, the default ``umask`` on the system will be + used when setting the mode for the newly created filesystem object. + If ``mode`` is not specified and the destination filesystem object **does** exist, the mode of the existing filesystem object will be used. - Specifying `mode` is the best way to ensure filesystem objects are - created with the correct permissions. See CVE-2020-1736 for + Specifying ``mode`` is the best way to ensure filesystem objects + are created with the correct permissions. See CVE-2020-1736 for further details. :param owner: Name of the user that should own the filesystem object, as would @@ -2047,21 +2055,21 @@ def file( previous ownership. :param seuser: The user part of the SELinux filesystem object context. - By default it uses the `system` policy, where applicable. - When set to `_default`, it will use the `user` portion of the + By default it uses the ``system`` policy, where applicable. + When set to ``_default``, it will use the ``user`` portion of the policy if available. :param serole: The role part of the SELinux filesystem object context. - When set to `_default`, it will use the `role` portion of the + When set to ``_default``, it will use the ``role`` portion of the policy if available. :param setype: The type part of the SELinux filesystem object context. - When set to `_default`, it will use the `type` portion of the + When set to ``_default``, it will use the ``type`` portion of the policy if available. :param selevel: The level part of the SELinux filesystem object context. - This is the MLS/MCS attribute, sometimes known as the `range`. - When set to `_default`, it will use the `level` portion of the + This is the MLS/MCS attribute, sometimes known as the ``range``. + When set to ``_default``, it will use the ``level`` portion of the policy if available. :param unsafe_writes: Influence when to use atomic operation to prevent data corruption @@ -2083,7 +2091,7 @@ def file( target system. This string should contain the attributes in the same order as the one displayed by *lsattr*. - The `=` operator is assumed as default, otherwise `+` or `-` + The ``=`` operator is assumed as default, otherwise ``+`` or ``-`` operators need to be included in the string. """ # noqa: E501 raise AttributeError('file') @@ -2125,7 +2133,7 @@ def find( specifying the first letter of any of those words (e.g., "1w"). :param patterns: One or more (shell or regex) patterns, which type is controlled by - `use_regex` option. + ``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. @@ -2133,33 +2141,34 @@ def find( directory. When using regexen, the pattern MUST match the ENTIRE file name, not just parts of it. So if you are looking to match all files - ending in .default, you'd need to use `.*\\.default` as a regexp - and not just `\\.default`. + ending in .default, you'd need to use ``.*\\.default`` as a regexp + and not just ``\\.default``. 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 `*` when `use_regex=False`, or `.*` when - `use_regex=True`. + Defaults to ``*`` when ``use_regex=False``, or ``.*`` when + ``use_regex=True``. :param excludes: One or more (shell or regex) patterns, which type is controlled by - `use_regex` option. - Items whose basenames match an `excludes` pattern are culled from - `patterns` matches. Multiple patterns can be specified using a - list. + ``use_regex`` option. + Items whose basenames match an ``excludes`` pattern are culled + from ``patterns`` matches. Multiple patterns can be specified + using a list. :param contains: A regular expression or pattern which should be matched against the file content. - If `read_whole_file` is `false` it matches against the beginning - of the line (uses `re.match(\\`)). If `read_whole_file` is `true`, - it searches anywhere for that pattern (uses `re.search(\\`)). - Works only when `file_type` is `file`. + If ``read_whole_file`` is ``false`` it matches against the + beginning of the line (uses ``re.match(\\``)). If + ``read_whole_file`` is ``true``, it searches anywhere for that + pattern (uses ``re.search(\\``)). + Works only when ``file_type`` is ``file``. :param read_whole_file: - When doing a `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 `true` can have performance and memory + When doing a ``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 ``true`` can have performance and memory implications for large files. - This uses `re.search(\\`) instead of `re.match(\\`). + This uses ``re.search(\\``) instead of ``re.match(\\``). :param paths: List of paths of directories to search. All paths must be fully qualified. @@ -2181,34 +2190,34 @@ def find( :param age_stamp: Choose the file property against which we compare age. :param hidden: - Set this to `true` to include hidden files, otherwise they will be - ignored. + Set this to ``true`` to include hidden files, otherwise they will + be ignored. :param mode: Choose objects matching a specified permission. This value is restricted to modes that can be applied using the python - `os.chmod` function. - The mode can be provided as an octal such as `"0644"` or as - symbolic such as `u=rw,g=r,o=r`. + ``os.chmod`` function. + The mode can be provided as an octal such as ``"0644"`` or as + symbolic such as ``u=rw,g=r,o=r``. Requires ansible-core >= 2.16 :param exact_mode: Restrict mode matching to exact matches only, and not as a minimum set of permissions to match. Requires ansible-core >= 2.16 :param follow: - Set this to `true` to follow symlinks in path for systems with + Set this to ``true`` to follow symlinks in path for systems with python 2.6+. :param get_checksum: - Set this to `true` to retrieve a file's SHA1 checksum. + Set this to ``true`` to retrieve a file's SHA1 checksum. :param use_regex: - If `false`, the patterns are file globs (shell). - If `true`, they are python regexes. + If ``false``, the patterns are file globs (shell). + If ``true``, they are python regexes. :param depth: Set the maximum number of levels to descend into. - Setting recurse to `false` will override this value, which is + Setting recurse to ``false`` will override this value, which is effectively depth 1. Default is unlimited depth. :param encoding: - When doing a `contains` search, determine the encoding of the + When doing a ``contains`` search, determine the encoding of the files to be searched. Requires ansible-core >= 2.17 """ # noqa: E501 @@ -2278,7 +2287,8 @@ def get_url( :param ciphers: SSL/TLS Ciphers to use for the request. - When a list is provided, all ciphers are joined in order with `:`. + When a list is provided, all ciphers are joined in order with + ``:``. See the `OpenSSL Cipher List Format `__ for more details. @@ -2293,25 +2303,26 @@ def get_url( (http|https|ftp)://[user[:pass]]@host.domain[:port]/path. :param dest: Absolute path of where to download the file to. - If `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, `force` has no effect. - If `dest` is a directory, the file will always be downloaded - (regardless of the `force` and `checksum` option), but replaced - only if the contents changed. + If ``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, ``force`` has no effect. + If ``dest`` is a directory, the file will always be downloaded + (regardless of the ``force`` and ``checksum`` option), but + replaced only if the contents changed. :param tmp_dest: 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 `TMPDIR`, `TEMP` - or `TMP` env variables or a platform specific value. + When run on Ansible prior to 2.5, it defaults to ``TMPDIR``, + ``TEMP`` or ``TMP`` env variables or a platform specific value. `tempfile.tempdir `__. :param force: - If `true` and `dest` is not a directory, will download the file - every time and replace the file if the contents change. If - `false`, the file will only be downloaded if the destination does - not exist. Generally should be `true` only for small local files. - Prior to 0.6, this module behaved as if `true` was the default. + If ``true`` and ``dest`` is not a directory, will download the + file every time and replace the file if the contents change. If + ``false``, the file will only be downloaded if the destination + does not exist. Generally should be ``true`` only for small local + files. + Prior to 0.6, this module behaved as if ``true`` was the default. :param backup: Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it @@ -2331,16 +2342,16 @@ def get_url( 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 `dest` location, the `destination_checksum` - would be calculated, and if checksum equals - `destination_checksum`, the file download would be skipped (unless - `force` is `true`). If the checksum does not equal - `destination_checksum`, the destination file is deleted. + file exist under the ``dest`` location, the + ``destination_checksum`` would be calculated, and if checksum + equals ``destination_checksum``, the file download would be + skipped (unless ``force`` is ``true``). If the checksum does not + equal ``destination_checksum``, the destination file is deleted. :param use_proxy: - if `false`, it will not use a proxy, even if one is defined in an - environment variable on the target hosts. + if ``false``, it will not use a proxy, even if one is defined in + an environment variable on the target hosts. :param validate_certs: - If `false`, SSL certificates will not be validated. + If ``false``, SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates. :param timeout: @@ -2348,20 +2359,20 @@ def get_url( :param headers: Add custom HTTP headers to a request in hash/dict format. The hash/dict format was added in Ansible 2.6. - Previous versions used a `"key:value,key:value"` string format. - The `"key:value,key:value"` string format is deprecated and has + Previous versions used a ``"key:value,key:value"`` string format. + The ``"key:value,key:value"`` string format is deprecated and has been removed in version 2.10. :param url_username: The username for use in HTTP basic authentication. - This parameter can be used without `url_password` for sites that + This parameter can be used without ``url_password`` for sites that allow empty passwords. - Since version 2.8 you can also use the `username` alias for this + Since version 2.8 you can also use the ``username`` alias for this option. :param url_password: The password for use in HTTP basic authentication. - If the `url_username` parameter is not specified, the - `url_password` parameter will not be used. - Since version 2.8 you can also use the `password` alias for this + If the ``url_username`` parameter is not specified, the + ``url_password`` parameter will not be used. + Since version 2.8 you can also use the ``password`` alias for this option. :param force_basic_auth: Force the sending of the Basic authentication header upon initial @@ -2374,11 +2385,11 @@ def get_url( 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, `client_key` is not required. + included, ``client_key`` is not required. :param client_key: PEM formatted file that contains your private key to be used for SSL client authentication. - If `client_cert` contains both the certificate and key, this + If ``client_cert`` contains both the certificate and key, this option is not required. :param http_agent: Header to identify as, generally appears in web server logs. @@ -2386,7 +2397,7 @@ def get_url( A list of header names that will not be sent on subsequent redirected requests. This list is case insensitive. By default all headers will be redirected. In some cases it may be beneficial to - list headers such as `Authorization` here to avoid potential + list headers such as ``Authorization`` here to avoid potential credential exposure. :param use_gssapi: Use GSSAPI to perform the authentication, typically this is for @@ -2394,8 +2405,8 @@ def get_url( Requires the Python library `gssapi `__ to be installed. Credentials for GSSAPI can be specified with - `url_username`/`url_password` or with the GSSAPI env var - `KRB5CCNAME` that specified a custom Kerberos credential cache. + ``url_username``/``url_password`` or with the GSSAPI env var + ``KRB5CCNAME`` that specified a custom Kerberos credential cache. NTLM authentication is *not* supported even if the GSSAPI mech for NTLM has been installed. :param use_netrc: @@ -2408,23 +2419,23 @@ def get_url( For those used to */usr/bin/chmod* remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal - numbers (for example, `'644'` or `'1777'`) so Ansible receives a - string and can do its own conversion from string into number. - Adding a leading zero (for example, `0755`) works sometimes, but + numbers (for example, ``'644'`` or ``'1777'``) so Ansible receives + a string and can do its own conversion from string into number. + Adding a leading zero (for example, ``0755``) works sometimes, but can fail in loops and some other circumstances. Giving Ansible a number without following either 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, `u+rwx` or `u=rw,g=r,o=r`). - If `mode` is not specified and the destination filesystem object - **does not** exist, the default `umask` on the system will be used - when setting the mode for the newly created filesystem object. - If `mode` is not specified and the destination filesystem object + (for example, ``u+rwx`` or ``u=rw,g=r,o=r``). + If ``mode`` is not specified and the destination filesystem object + **does not** exist, the default ``umask`` on the system will be + used when setting the mode for the newly created filesystem object. + If ``mode`` is not specified and the destination filesystem object **does** exist, the mode of the existing filesystem object will be used. - Specifying `mode` is the best way to ensure filesystem objects are - created with the correct permissions. See CVE-2020-1736 for + Specifying ``mode`` is the best way to ensure filesystem objects + are created with the correct permissions. See CVE-2020-1736 for further details. :param owner: Name of the user that should own the filesystem object, as would @@ -2441,21 +2452,21 @@ def get_url( previous ownership. :param seuser: The user part of the SELinux filesystem object context. - By default it uses the `system` policy, where applicable. - When set to `_default`, it will use the `user` portion of the + By default it uses the ``system`` policy, where applicable. + When set to ``_default``, it will use the ``user`` portion of the policy if available. :param serole: The role part of the SELinux filesystem object context. - When set to `_default`, it will use the `role` portion of the + When set to ``_default``, it will use the ``role`` portion of the policy if available. :param setype: The type part of the SELinux filesystem object context. - When set to `_default`, it will use the `type` portion of the + When set to ``_default``, it will use the ``type`` portion of the policy if available. :param selevel: The level part of the SELinux filesystem object context. - This is the MLS/MCS attribute, sometimes known as the `range`. - When set to `_default`, it will use the `level` portion of the + This is the MLS/MCS attribute, sometimes known as the ``range``. + When set to ``_default``, it will use the ``level`` portion of the policy if available. :param unsafe_writes: Influence when to use atomic operation to prevent data corruption @@ -2477,7 +2488,7 @@ def get_url( target system. This string should contain the attributes in the same order as the one displayed by *lsattr*. - The `=` operator is assumed as default, otherwise `+` or `-` + The ``=`` operator is assumed as default, otherwise ``+`` or ``-`` operators need to be included in the string. """ # noqa: E501 raise AttributeError('get_url') @@ -2509,11 +2520,11 @@ def getent( always available. :param split: Character used to split the database values into lists/arrays such - as `:` or `\\t`, otherwise it will try to pick one depending on - the database. + as ``:`` or ``\\t``, otherwise it will try to pick one depending + on the database. :param fail_key: If a supplied key is missing this will make the task fail if - `true`. + ``true``. """ # noqa: E501 raise AttributeError('getent') @@ -2553,45 +2564,45 @@ def git( :ref:`ansible.builtin ` :param repo: - git, SSH, or HTT`S` protocol address of the git repository. + git, SSH, or HTT``S`` protocol address of the git repository. :param dest: The path of where the repository should be checked out. This is - equivalent to `git clone [repo_url] [directory]`. The repository - named in `repo` is not appended to this path and the destination + equivalent to ``git clone [repo_url] [directory]``. The repository + named in ``repo`` is not appended to this path and the destination directory must be empty. This parameter is required, unless - `clone` is set to `false`. + ``clone`` is set to ``false``. :param version: What version of the repository to check out. This can be the - literal string `HEAD`, a branch name, a tag name. It can also be a - *SHA-1* hash, in which case `refspec` needs to be specified if the - given revision is not already available. + literal string ``HEAD``, a branch name, a tag name. It can also be + a *SHA-1* hash, in which case ``refspec`` needs to be specified if + the given revision is not already available. :param accept_hostkey: 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 `ssh_opts` to - `StrictHostKeyChecking=accept-new` instead, it does not remove the - MITM issue but it does restrict it to the first attempt. + Those using OpenSSH >= 7.5 might want to set ``ssh_opts`` to + ``StrictHostKeyChecking=accept-new`` instead, it does not remove + the MITM issue but it does restrict it to the first attempt. :param accept_newhostkey: 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 `true`, ensure that "-o + present or are the same. if ``true``, ensure that "-o StrictHostKeyChecking=accept-new" is present as an ssh option. :param ssh_opts: Options git will pass to ssh when used as protocol, it works via - `git`'s `GIT_SSH`/`GIT_SSH_COMMAND` environment variables. - For older versions it appends `GIT_SSH_OPTS` (specific to this + ``git``'s ``GIT_SSH``/``GIT_SSH_COMMAND`` environment variables. + For older versions it appends ``GIT_SSH_OPTS`` (specific to this module) to the variables above or via a wrapper script. - Other options can add to this list, like `key_file` and - `accept_hostkey`. + Other options can add to this list, like ``key_file`` and + ``accept_hostkey``. An example value could be "-o StrictHostKeyChecking=no" (although - this particular option is better set by `accept_hostkey`). + this particular option is better set by ``accept_hostkey``). The module ensures that 'BatchMode=yes' is always present to avoid prompts. :param key_file: 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 ``ssh_opts``. :param reference: Reference repository (see "git clone --reference ..."). :param remote: @@ -2600,21 +2611,21 @@ def git( Add an additional refspec to be fetched. If version is set to a *SHA-1* not reachable from any branch or tag, this option may be necessary to specify the ref containing the *SHA-1*. Uses the same - syntax as the `git fetch` command. An example value could be + syntax as the ``git fetch`` command. An example value could be "refs/meta/config". :param force: - If `true`, any modified files in the working repository will be - discarded. Prior to 0.7, this was always `true` and could not be - disabled. Prior to 1.9, the default was `true`. + If ``true``, any modified files in the working repository will be + discarded. Prior to 0.7, this was always ``true`` and could not be + disabled. Prior to 1.9, the default was ``true``. :param depth: Create a shallow clone with a history truncated to the specified - number or revisions. The minimum possible value is `1`, otherwise - ignored. Needs *git>=1.9.1* to work correctly. + number or revisions. The minimum possible value is ``1``, + otherwise ignored. Needs *git>=1.9.1* to work correctly. :param clone: - If `false`, do not clone the repository even if it does not exist - locally. + If ``false``, do not clone the repository even if it does not + exist locally. :param update: - If `false`, do not retrieve new revisions from the origin + If ``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. @@ -2622,25 +2633,25 @@ def git( Path to git executable to use. If not supplied, the normal mechanism for resolving binary paths will be used. :param bare: - If `true`, repository will be created as a bare repo, otherwise it - will be a standard repo with a workspace. + If ``true``, repository will be created as a bare repo, otherwise + it will be a standard repo with a workspace. :param umask: The umask to set before doing any checkouts, or any other repository maintenance. :param recursive: - If `false`, repository will be cloned without the `--recursive` - option, skipping sub-modules. + If ``false``, repository will be cloned without the + ``--recursive`` option, skipping sub-modules. :param single_branch: Clone only the history leading to the tip of the specified revision. :param track_submodules: - If `true`, submodules will track the latest commit on their master - branch (or other branch specified in .gitmodules). If `false`, - submodules will be kept at the revision specified by the main - project. This is equivalent to specifying the `--remote` flag to - git submodule update. + If ``true``, submodules will track the latest commit on their + master branch (or other branch specified in .gitmodules). If + ``false``, submodules will be kept at the revision specified by + the main project. This is equivalent to specifying the + ``--remote`` flag to git submodule update. :param verify_commit: - If `true`, when cloning or checking out a `version` verify the + If ``true``, when cloning or checking out a ``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. @@ -2653,19 +2664,19 @@ def git( not all git servers support git archive. :param archive_prefix: Specify a prefix to add to each file path in archive. Requires - `archive` to be specified. + ``archive`` to be specified. :param separate_git_dir: The path to place the cloned repository. If specified, Git repository can be separated from working tree. :param gpg_allowlist: A list of trusted GPG fingerprints to compare to the fingerprint of the GPG-signed commit. - Only used when `verify_commit=yes`. + Only used when ``verify_commit=yes``. Use of this feature requires Git 2.6+ due to its reliance on git's - `--raw` flag to `verify-commit` and `verify-tag`. - Alias `gpg_allowlist` is added in version 2.17. - Alias `gpg_whitelist` is deprecated and will be removed in version - 2.21. + ``--raw`` flag to ``verify-commit`` and ``verify-tag``. + Alias ``gpg_allowlist`` is added in version 2.17. + Alias ``gpg_whitelist`` is deprecated and will be removed in + version 2.21. """ # noqa: E501 raise AttributeError('git') @@ -2711,18 +2722,18 @@ def group( group deletion command. Requires ansible-core >= 2.15 :param system: - If `True`, indicates that the group created is a system group. + If ``True``, indicates that the group created is a system group. :param local: Forces the use of "local" command alternatives on platforms that implement it. This is useful in environments that use centralized authentication when you want to manipulate the local groups. (for example, it - uses `lgroupadd` instead of `groupadd`). + uses ``lgroupadd`` instead of ``groupadd``). This requires that these commands exist on the targeted host, otherwise it will be a fatal error. :param non_unique: This option allows to change the group ID to a non-unique value. - Requires `gid`. + Requires ``gid``. Not supported on macOS or BusyBox distributions. """ # noqa: E501 raise AttributeError('group') @@ -2818,24 +2829,25 @@ def import_role( :param name: The name of the role to be executed. :param tasks_from: - File to load from a role's `tasks/` directory. + File to load from a role's ``tasks/`` directory. :param vars_from: - File to load from a role's `vars/` directory. + File to load from a role's ``vars/`` directory. :param defaults_from: - File to load from a role's `defaults/` directory. + File to load from a role's ``defaults/`` directory. :param allow_duplicates: Overrides the role's metadata setting to allow using a role more than once with the same parameters. :param handlers_from: - File to load from a role's `handlers/` directory. + File to load from a role's ``handlers/`` directory. :param rolespec_validate: Perform role argument spec validation if an argument spec is defined. :param public: - This option dictates whether the role's `vars` and `defaults` are - exposed to the play. + This option dictates whether the role's ``vars`` and ``defaults`` + are exposed to the play. Variables are exposed to the play at playbook parsing time, and - available to earlier roles and tasks as well unlike `include_role`. + available to earlier roles and tasks as well unlike + ``include_role``. The default depends on the configuration option `default_private_role_vars`. Requires ansible-core >= 2.17 @@ -2891,30 +2903,29 @@ def include_role( :ref:`ansible.builtin ` :param apply: - Accepts a hash of task keywords (for example `tags`, `become`) + Accepts a hash of task keywords (for example ``tags``, ``become``) that will be applied to all tasks within the included role. :param name: The name of the role to be executed. :param tasks_from: - File to load from a role's `tasks/` directory. + File to load from a role's ``tasks/`` directory. :param vars_from: - File to load from a role's `vars/` directory. + File to load from a role's ``vars/`` directory. :param defaults_from: - File to load from a role's `defaults/` directory. + File to load from a role's ``defaults/`` directory. :param allow_duplicates: Overrides the role's metadata setting to allow using a role more than once with the same parameters. :param public: - This option dictates whether the role's `vars` and `defaults` are - exposed to the play. If set to `true` the variables will be - available to tasks following the `include_role` task. This + This option dictates whether the role's ``vars`` and ``defaults`` + are exposed to the play. If set to ``true`` the variables will be + available to tasks following the ``include_role`` task. This functionality differs from standard variable exposure for roles - listed under the `roles` header or - :meth:`ansible.builtin.import_role` as they are exposed to the - play at playbook parsing time, and available to earlier roles and - tasks as well. + listed under the ``roles`` header or :meth:`import_role` as they + are exposed to the play at playbook parsing time, and available to + earlier roles and tasks as well. :param handlers_from: - File to load from a role's `handlers/` directory. + File to load from a role's ``handlers/`` directory. :param rolespec_validate: Perform role argument spec validation if an argument spec is defined. @@ -2943,7 +2954,7 @@ def include_tasks(self, *args: Any, **kwargs: Any) -> IncludeTasksResults: Specifies the name of the file that lists tasks to add to the current playbook. :param apply: - Accepts a hash of task keywords (for example `tags`, `become`) + Accepts a hash of task keywords (for example ``tags``, ``become``) that will be applied to the tasks within the include. """ # noqa: E501 raise AttributeError('include_tasks') @@ -2987,7 +2998,7 @@ def include_vars(self, *args: Any, **kwargs: Any) -> IncludeVarsResults: The name of a variable into which assign the included vars. If omitted (null) they will be made top level vars. :param depth: - When using `dir`, this module will, by default, recursively go + When using ``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. @@ -2997,20 +3008,20 @@ def include_vars(self, *args: Any, **kwargs: Any) -> IncludeVarsResults: :param ignore_files: List of file names to ignore. :param extensions: - List of file extensions to read when using `dir`. + List of file extensions to read when using ``dir``. :param ignore_unknown_extensions: Ignore unknown file extensions within the directory. This allows users to specify a directory containing vars files that are intermingled with non-vars files extension types (e.g. a directory with a README in it and vars files). :param hash_behaviour: - If set to `merge`, merges existing hash variables instead of + If set to ``merge``, merges existing hash variables instead of overwriting them. - If omitted (`null`), the behavior falls back to the global - `hash_behaviour` configuration. + If omitted (``null``), the behavior falls back to the global + ``hash_behaviour`` configuration. This option is self-contained and does not apply to individual - files in `dir`. You can use a loop to apply `hash_behaviour` per - file. + files in ``dir``. You can use a loop to apply ``hash_behaviour`` + per file. """ # noqa: E501 raise AttributeError('include_vars') @@ -3114,24 +3125,25 @@ def iptables( If the rule already exists the chain will not be modified. :param rule_num: Insert the rule as the given rule number. - This works only with `action=insert`. + This works only with ``action=insert``. :param ip_version: Which version of the IP protocol this rule should apply to. :param chain: Specify the iptables chain to modify. This could be a user-defined chain or one of the standard iptables - chains, like `INPUT`, `FORWARD`, `OUTPUT`, `PREROUTING`, - `POSTROUTING`, `SECMARK` or `CONNSECMARK`. + chains, like ``INPUT``, ``FORWARD``, ``OUTPUT``, ``PREROUTING``, + ``POSTROUTING``, ``SECMARK`` or ``CONNSECMARK``. :param protocol: The protocol of the rule or of the packet to check. - The specified protocol can be one of `tcp`, `udp`, `udplite`, - `icmp`, `ipv6-icmp` or `icmpv6`, `esp`, `ah`, `sctp` or the - special keyword `all`, or it can be a numeric value, representing - one of these protocols or a different one. - A protocol name from `/etc/protocols` is also allowed. - A `!` argument before the protocol inverts the test. + The specified protocol can be one of ``tcp``, ``udp``, + ``udplite``, ``icmp``, ``ipv6-icmp`` or ``icmpv6``, ``esp``, + ``ah``, ``sctp`` or the special keyword ``all``, or it can be a + numeric value, representing one of these protocols or a different + one. + A protocol name from ``/etc/protocols`` is also allowed. + A ``!`` argument before the protocol inverts the test. The number zero is equivalent to all. - `all` will match with all protocols and is taken as default when + ``all`` will match with all protocols and is taken as default when this option is omitted. :param source: Source specification. @@ -3142,8 +3154,9 @@ def iptables( with 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 `!` argument - before the address specification inverts the sense of the address. + Thus, a mask of 24 is equivalent to 255.255.255.0. A ``!`` + argument before the address specification inverts the sense of the + address. :param destination: Destination specification. Address can be either a network name, a hostname, a network IP @@ -3153,12 +3166,13 @@ def iptables( with 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 `!` argument - before the address specification inverts the sense of the address. + Thus, a mask of 24 is equivalent to 255.255.255.0. A ``!`` + argument before the address specification inverts the sense of the + address. :param tcp_flags: TCP flags specification. - `tcp_flags` expects a dict with the two keys `flags` and - `flags_set`. + ``tcp_flags`` expects a dict with the two keys ``flags`` and + ``flags_set``. :param match: Specifies a match to use, that is, an extension module that tests for a specific property. @@ -3180,14 +3194,14 @@ def iptables( :param gateway: This specifies the IP address of the host to send the cloned packets. - This option is only valid when `jump` is set to `TEE`. + This option is only valid when ``jump`` is set to ``TEE``. :param log_prefix: Specifies a log text for the rule. Only makes sense with a LOG jump. :param log_level: Logging level according to the syslogd-defined priorities. The value can be strings or numbers from 1-8. - This parameter is only applicable if `jump` is set to `LOG`. + This parameter is only applicable if ``jump`` is set to ``LOG``. :param goto: This specifies that the processing should continue in a user-specified chain. @@ -3195,18 +3209,20 @@ def iptables( this chain but instead in the chain that called us via jump. :param in_interface: Name of an interface via which a packet was received (only for - packets entering the `INPUT`, `FORWARD` and `PREROUTING` chains). - When the `!` argument is used before the interface name, the sense - is inverted. - If the interface name ends in a `+`, then any interface which + packets entering the ``INPUT``, ``FORWARD`` and ``PREROUTING`` + chains). + When the ``!`` argument is used before the interface name, the + sense is inverted. + If the interface name ends in a ``+``, then any interface which begins with this name will match. If this option is omitted, any interface name will match. :param out_interface: Name of an interface via which a packet is going to be sent (for - packets entering the `FORWARD`, `OUTPUT` and `POSTROUTING` chains). - When the `!` argument is used before the interface name, the sense - is inverted. - If the interface name ends in a `+`, then any interface which + packets entering the ``FORWARD``, ``OUTPUT`` and ``POSTROUTING`` + chains). + When the ``!`` argument is used before the interface name, the + sense is inverted. + If the interface name ends in a ``+``, then any interface which begins with this name will match. If this option is omitted, any interface name will match. :param fragment: @@ -3219,15 +3235,15 @@ def iptables( will only match head fragments, or unfragmented packets. :param set_counters: This enables the administrator to initialize the packet and byte - counters of a rule (during `INSERT`, `APPEND`, `REPLACE` + counters of a rule (during ``INSERT``, ``APPEND``, ``REPLACE`` operations). :param source_port: 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 - `first:last`. - If the first port is omitted, `0` is assumed; if the last is - omitted, `65535` is assumed. + ``first:last``. + If the first port is omitted, ``0`` is assumed; if the last is + omitted, ``65535`` is assumed. If the first port is greater than the second one they will be swapped. :param destination_port: @@ -3247,12 +3263,12 @@ def iptables( 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 - `tcp`, `udp`, `dccp` or `sctp`. + ``tcp``, ``udp``, ``dccp`` or ``sctp``. :param to_destination: - This specifies a destination address to use with `DNAT`. + This specifies a destination address to use with ``DNAT``. Without this, the destination address is never altered. :param to_source: - This specifies a source address to use with `SNAT`. + This specifies a source address to use with ``SNAT``. Without this, the source address is never altered. :param syn: This allows matching packets that have the SYN bit set and the ACK @@ -3262,44 +3278,44 @@ def iptables( :param set_dscp_mark: This allows specifying a DSCP mark to be added to packets. It takes either an integer or hex value. - If the parameter is set, `jump` is set to `DSCP`. - Mutually exclusive with `set_dscp_mark_class`. + If the parameter is set, ``jump`` is set to ``DSCP``. + Mutually exclusive with ``set_dscp_mark_class``. :param set_dscp_mark_class: This allows specifying a predefined DiffServ class which will be translated to the corresponding DSCP mark. - If the parameter is set, `jump` is set to `DSCP`. - Mutually exclusive with `set_dscp_mark`. + If the parameter is set, ``jump`` is set to ``DSCP``. + Mutually exclusive with ``set_dscp_mark``. :param comment: This specifies a comment that will be added to the rule. :param ctstate: A list of the connection states to match in the conntrack module. - Possible values are `INVALID`, `NEW`, `ESTABLISHED`, `RELATED`, - `UNTRACKED`, `SNAT`, `DNAT`. + Possible values are ``INVALID``, ``NEW``, ``ESTABLISHED``, + ``RELATED``, ``UNTRACKED``, ``SNAT``, ``DNAT``. :param src_range: Specifies the source IP range to match the iprange module. :param dst_range: Specifies the destination IP range to match in the iprange module. :param match_set: Specifies a set name that can be defined by ipset. - Must be used together with the `match_set_flags` parameter. - When the `!` argument is prepended then it inverts the rule. + Must be used together with the ``match_set_flags`` parameter. + When the ``!`` argument is prepended then it inverts the rule. Uses the iptables set extension. :param match_set_flags: Specifies the necessary flags for the match_set parameter. - Must be used together with the `match_set` parameter. + Must be used together with the ``match_set`` parameter. Uses the iptables set extension. - Choices `dst,dst` and `src,src` added in version 2.17. + Choices ``dst,dst`` and ``src,src`` added in version 2.17. :param limit: Specifies the maximum average number of matches to allow per second. - The number can specify units explicitly, using `/second`, - `/minute`, `/hour` or `/day`, or parts of them (so `5/second` is - the same as `5/s`). + The number can specify units explicitly, using ``/second``, + ``/minute``, ``/hour`` or ``/day``, or parts of them (so + ``5/second`` is the same as ``5/s``). :param limit_burst: Specifies the maximum burst before the above limit kicks in. :param uid_owner: Specifies the UID or username to use in the match by owner rule. - From Ansible 2.6 when the `!` argument is prepended then the it + From Ansible 2.6 when the ``!`` argument is prepended then the it inverts the rule to apply instead to all users except that one specified. :param gid_owner: @@ -3318,26 +3334,27 @@ def iptables( :param policy: Set the policy for the chain to the given target. Only built-in chains can have policies. - This parameter requires the `chain` parameter. + This parameter requires the ``chain`` parameter. If you specify this parameter, all other parameters will be ignored. This parameter is used to set the default policy for the given - `chain`. Do not confuse this with `jump` parameter. + ``chain``. Do not confuse this with ``jump`` parameter. :param wait: Wait N seconds for the xtables lock to prevent multiple instances of the program from running concurrently. :param chain_management: - If `true` and `state` is `present`, the chain will be created if - needed. - If `true` and `state` is `absent`, the chain will be deleted if - the only other parameter passed are `chain` and optionally `table`. + If ``true`` and ``state`` is ``present``, the chain will be + created if needed. + If ``true`` and ``state`` is ``absent``, the chain will be deleted + if the only other parameter passed are ``chain`` and optionally + ``table``. :param numeric: 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 hang when creating a chain or altering policy. - If `true`, then iptables skips the DNS-lookup of the IP addresses - in a chain when it uses the list -action. + If ``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 creating a chain. Requires ansible-core >= 2.15 @@ -3354,7 +3371,7 @@ def known_hosts( state: Literal['absent', 'present'] = 'present', ) -> KnownHostsResults: """ - Add or remove a host from the `known_hosts` file. + Add or remove a host from the ``known_hosts`` file. .. seealso:: :ref:`ansible.builtin ` @@ -3363,11 +3380,11 @@ def known_hosts( 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, `name` needs to specify port as well. See + For custom SSH port, ``name`` needs to specify port as well. See example section. :param key: The SSH public host key, as a string. - Required if `state=present`, optional when `state=absent`, in + Required if ``state=present``, optional when ``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"). @@ -3376,8 +3393,8 @@ def known_hosts( 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 ` ssh-rsa `. - For custom SSH port, `key` needs to specify port as well. See + Should be of format `` ssh-rsa ``. + For custom SSH port, ``key`` needs to specify port as well. See example section. :param path: The known_hosts file to edit. @@ -3386,8 +3403,8 @@ def known_hosts( :param hash_host: Hash the hostname in the known_hosts file. :param state: - `present` to add the host key. - `absent` to remove it. + ``present`` to add the host key. + ``absent`` to remove it. """ # noqa: E501 raise AttributeError('known_hosts') @@ -3424,79 +3441,79 @@ def lineinfile( :param path: The file to modify. - Before Ansible 2.3 this option was only usable as `dest`, - `destfile` and `name`. + Before Ansible 2.3 this option was only usable as ``dest``, + ``destfile`` and ``name``. :param regexp: The regular expression to look for in every line of the file. - For `state=present`, the pattern to replace if found. Only the + For ``state=present``, the pattern to replace if found. Only the last line found will be replaced. - For `state=absent`, the pattern of the line(s) to remove. + For ``state=absent``, the pattern of the line(s) to remove. If the regular expression is not matched, the line will be added - to the file in keeping with `insertbefore` or `insertafter` + to the file in keeping with ``insertbefore`` or ``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 `line` to ensure idempotence. + by ``line`` to ensure idempotence. Uses Python regular expressions. See `reference `__. :param search_string: The literal string to look for in every line of the file. This does not have to match the entire line. - For `state=present`, the line to replace if the string is found in - the file. Only the last line found will be replaced. - For `state=absent`, the line(s) to remove if the string is in the - line. + For ``state=present``, the line to replace if the string is found + in the file. Only the last line found will be replaced. + For ``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 `insertbefore` or `insertafter` + to the file in keeping with ``insertbefore`` or ``insertafter`` settings. - Mutually exclusive with `backrefs` and `regexp`. + Mutually exclusive with ``backrefs`` and ``regexp``. :param state: Whether the line should be there or not. :param line: The line to insert/replace into the file. - Required for `state=present`. - If `backrefs` is set, may contain backreferences that will get - expanded with the `regexp` capture groups if the regexp matches. + Required for ``state=present``. + If ``backrefs`` is set, may contain backreferences that will get + expanded with the ``regexp`` capture groups if the regexp matches. :param backrefs: - Used with `state=present`. - If set, `line` can contain backreferences (both positional and - named) that will get populated if the `regexp` matches. + Used with ``state=present``. + If set, ``line`` can contain backreferences (both positional and + named) that will get populated if the ``regexp`` matches. This parameter changes the operation of the module slightly; - `insertbefore` and `insertafter` will be ignored, and if the - `regexp` does not match anywhere in the file, the file will be + ``insertbefore`` and ``insertafter`` will be ignored, and if the + ``regexp`` does not match anywhere in the file, the file will be left unchanged. - If the `regexp` does match, the last matching line will be + If the ``regexp`` does match, the last matching line will be replaced by the expanded line parameter. - Mutually exclusive with `search_string`. + Mutually exclusive with ``search_string``. :param insertafter: - Used with `state=present`. + Used with ``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; `EOF` for inserting the line at the - end of the file. + A special value is available; ``EOF`` for inserting the line at + the end of the file. If specified regular expression has no matches, EOF will be used instead. - If `insertbefore` is set, default value `EOF` will be ignored. - If regular expressions are passed to both `regexp` and - `insertafter`, `insertafter` is only honored if no match for - `regexp` is found. - May not be used with `backrefs` or `insertbefore`. + If ``insertbefore`` is set, default value ``EOF`` will be ignored. + If regular expressions are passed to both ``regexp`` and + ``insertafter``, ``insertafter`` is only honored if no match for + ``regexp`` is found. + May not be used with ``backrefs`` or ``insertbefore``. :param insertbefore: - Used with `state=present`. + Used with ``state=present``. If specified, the line will be inserted before the last match of specified regular expression. - If the first match is required, use `firstmatch=yes`. - A value is available; `BOF` for inserting the line at the + If the first match is required, use ``firstmatch=yes``. + A value is available; ``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 `regexp` and - `insertbefore`, `insertbefore` is only honored if no match for - `regexp` is found. - May not be used with `backrefs` or `insertafter`. + If regular expressions are passed to both ``regexp`` and + ``insertbefore``, ``insertbefore`` is only honored if no match for + ``regexp`` is found. + May not be used with ``backrefs`` or ``insertafter``. :param create: - Used with `state=present`. + Used with ``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. @@ -3505,31 +3522,31 @@ def lineinfile( can get the original file back if you somehow clobbered it incorrectly. :param firstmatch: - Used with `insertafter` or `insertbefore`. - If set, `insertafter` and `insertbefore` will work with the first - line that matches the given regular expression. + Used with ``insertafter`` or ``insertbefore``. + If set, ``insertafter`` and ``insertbefore`` will work with the + first line that matches the given regular expression. :param mode: The permissions the resulting filesystem object should have. For those used to */usr/bin/chmod* remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal - numbers (for example, `'644'` or `'1777'`) so Ansible receives a - string and can do its own conversion from string into number. - Adding a leading zero (for example, `0755`) works sometimes, but + numbers (for example, ``'644'`` or ``'1777'``) so Ansible receives + a string and can do its own conversion from string into number. + Adding a leading zero (for example, ``0755``) works sometimes, but can fail in loops and some other circumstances. Giving Ansible a number without following either 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, `u+rwx` or `u=rw,g=r,o=r`). - If `mode` is not specified and the destination filesystem object - **does not** exist, the default `umask` on the system will be used - when setting the mode for the newly created filesystem object. - If `mode` is not specified and the destination filesystem object + (for example, ``u+rwx`` or ``u=rw,g=r,o=r``). + If ``mode`` is not specified and the destination filesystem object + **does not** exist, the default ``umask`` on the system will be + used when setting the mode for the newly created filesystem object. + If ``mode`` is not specified and the destination filesystem object **does** exist, the mode of the existing filesystem object will be used. - Specifying `mode` is the best way to ensure filesystem objects are - created with the correct permissions. See CVE-2020-1736 for + Specifying ``mode`` is the best way to ensure filesystem objects + are created with the correct permissions. See CVE-2020-1736 for further details. :param owner: Name of the user that should own the filesystem object, as would @@ -3546,21 +3563,21 @@ def lineinfile( previous ownership. :param seuser: The user part of the SELinux filesystem object context. - By default it uses the `system` policy, where applicable. - When set to `_default`, it will use the `user` portion of the + By default it uses the ``system`` policy, where applicable. + When set to ``_default``, it will use the ``user`` portion of the policy if available. :param serole: The role part of the SELinux filesystem object context. - When set to `_default`, it will use the `role` portion of the + When set to ``_default``, it will use the ``role`` portion of the policy if available. :param setype: The type part of the SELinux filesystem object context. - When set to `_default`, it will use the `type` portion of the + When set to ``_default``, it will use the ``type`` portion of the policy if available. :param selevel: The level part of the SELinux filesystem object context. - This is the MLS/MCS attribute, sometimes known as the `range`. - When set to `_default`, it will use the `level` portion of the + This is the MLS/MCS attribute, sometimes known as the ``range``. + When set to ``_default``, it will use the ``level`` portion of the policy if available. :param unsafe_writes: Influence when to use atomic operation to prevent data corruption @@ -3582,7 +3599,7 @@ def lineinfile( target system. This string should contain the attributes in the same order as the one displayed by *lsattr*. - The `=` operator is assumed as default, otherwise `+` or `-` + The ``=`` operator is assumed as default, otherwise ``+`` or ``-`` operators need to be included in the string. :param validate: The validation command to run before copying the updated file into @@ -3592,7 +3609,7 @@ def lineinfile( Also, the command is passed securely so shell features such as expansion and pipes will not work. For an example on how to handle more complex validation than what - this option provides, see `handling complex validation`. + this option provides, see ``handling complex validation``. """ # noqa: E501 raise AttributeError('lineinfile') @@ -3620,27 +3637,27 @@ def package( :param name: Package name, or package specifier with version. - Syntax varies with package manager. For example `name-1.0` or - `name=1.0`. + Syntax varies with package manager. For example ``name-1.0`` or + ``name=1.0``. Package names also vary with package manager; this module will not - "translate" them per distribution. For example `libyaml-dev`, - `libyaml-devel`. + "translate" them per distribution. For example ``libyaml-dev``, + ``libyaml-devel``. To operate on several packages this can accept a comma separated string of packages or a list of packages, depending on the underlying package manager. :param state: - Whether to install (`present`), or remove (`absent`) a package. - You can use other states like `latest` ONLY if they are supported - by the underlying package module(s) executed. + Whether to install (``present``), or remove (``absent``) a package. + You can use other states like ``latest`` ONLY if they are + supported by the underlying package module(s) executed. :param use: - The required package manager module to use (`dnf`, `apt`, and so - on). The default `auto` will use existing facts or try to + The required package manager module to use (``dnf``, ``apt``, and + so on). The default ``auto`` will use existing facts or try to auto-detect it. You should only use this field if the automatic selection is not working for some reason. - Since version 2.17 you can use the `ansible_package_use` variable - to override the automatic detection, but this option still takes - precedence. + Since version 2.17 you can use the ``ansible_package_use`` + variable to override the automatic detection, but this option + still takes precedence. """ # noqa: E501 raise AttributeError('package') @@ -3666,8 +3683,8 @@ def package_facts( The 'pkg_info' option was added in version 2.13. :param strategy: This option controls how the module queries the package managers - on the system. `first` means it will return only information for - the first supported package manager available. `all` will return + on the system. ``first`` means it will return only information for + the first supported package manager available. ``all`` will return information for all supported and available package managers on the system. """ # noqa: E501 @@ -3693,12 +3710,12 @@ def pause( A positive number of seconds to pause for. :param prompt: Optional text to use for the prompt message. - User input is only returned if `seconds=None` and `minutes=None`, - otherwise this is just a custom message before playbook execution - is paused. + User input is only returned if ``seconds=None`` and + ``minutes=None``, otherwise this is just a custom message before + playbook execution is paused. :param echo: Controls whether or not keyboard input is shown when typing. - Only has effect if `seconds=None` and `minutes=None`. + Only has effect if ``seconds=None`` and ``minutes=None``. """ # noqa: E501 raise AttributeError('pause') @@ -3708,15 +3725,15 @@ def ping( data: str = 'pong', ) -> PingResults: """ - Try to connect to host, verify a usable python and return `pong` on + Try to connect to host, verify a usable python and return ``pong`` on success. .. seealso:: :ref:`ansible.builtin ` :param data: - Data to return for the `ping` return value. - If this parameter is set to `crash`, the module will cause an + Data to return for the ``ping`` return value. + If this parameter is set to ``crash``, the module will cause an exception. """ # noqa: E501 raise AttributeError('ping') @@ -3757,7 +3774,7 @@ def pip( (since 2.7). :param version: The version number to install of the Python library specified in - the `name` parameter. + the ``name`` parameter. :param requirements: The path to a pip requirements file, which should be local to the remote system. File can be specified as a relative path if using @@ -3776,14 +3793,15 @@ def pip( have any effect, the environment must be deleted and newly created. :param virtualenv_command: The command or a pathname to the command to create the virtual - environment with. For example `pyvenv`, `virtualenv`, - `virtualenv2`, `~/bin/virtualenv`, `/usr/local/bin/virtualenv`. + environment with. For example ``pyvenv``, ``virtualenv``, + ``virtualenv2``, ``~/bin/virtualenv``, + ``/usr/local/bin/virtualenv``. :param virtualenv_python: The Python executable used for creating the virtual environment. - For example `python3.12`, `python2.7`. When not specified, the + For example ``python3.12``, ``python2.7``. When not specified, the Python version used to run the ansible module is used. This - parameter should not be used when `virtualenv_command` is using - `pyvenv` or the `-m venv` module. + parameter should not be used when ``virtualenv_command`` is using + ``pyvenv`` or the ``-m venv`` module. :param state: The state of module. The 'forcereinstall' option is only available in Ansible 2.1 and @@ -3797,9 +3815,9 @@ def pip( :param executable: The explicit executable or pathname for the pip executable, if different from the Ansible Python interpreter. For example - `pip3.3`, if there are both Python 2.7 and 3.3 installations in + ``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 `virtualenv` (added in 2.1). + Mutually exclusive with ``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 @@ -3840,9 +3858,9 @@ def raw(self, *args: Any, **kwargs: Any) -> RawResults: :param executable: Change the shell used to execute the command. Should be an absolute path to the executable. - When using privilege escalation (`become`) a default shell will be - assigned if one is not provided as privilege escalation requires a - shell. + When using privilege escalation (``become``) a default shell will + be assigned if one is not provided as privilege escalation + requires a shell. """ # noqa: E501 raise AttributeError('raw') @@ -3893,10 +3911,10 @@ def reboot( :param msg: Message to display to users before reboot. :param search_paths: - Paths to search on the remote machine for the `shutdown` command. - *Only* these paths will be searched for the `shutdown` command. - `PATH` is ignored in the remote node when searching for the - `shutdown` command. + Paths to search on the remote machine for the ``shutdown`` command. + *Only* these paths will be searched for the ``shutdown`` command. + ``PATH`` is ignored in the remote node when searching for the + ``shutdown`` command. :param boot_time_command: Command to run that returns a unique string indicating the last time the system was booted. @@ -3906,10 +3924,10 @@ def reboot( 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, `search_paths` on - the target system will be searched to find the absolute path. - This will cause `pre_reboot_delay`, `post_reboot_delay`, and `msg` - to be ignored. + If an absolute path to the command is not given, ``search_paths`` + on the target system will be searched to find the absolute path. + This will cause ``pre_reboot_delay``, ``post_reboot_delay``, and + ``msg`` to be ignored. """ # noqa: E501 raise AttributeError('reboot') @@ -3944,21 +3962,21 @@ def replace( :param path: The file to modify. - Before Ansible 2.3 this option was only usable as `dest`, - `destfile` and `name`. + Before Ansible 2.3 this option was only usable as ``dest``, + ``destfile`` and ``name``. :param regexp: The regular expression to look for in the contents of the file. Uses Python regular expressions; see `reference `__. - Uses MULTILINE mode, which means `^` and `$` match the beginning - and end of the file, as well as the beginning and end respectively - of *each line* of the file. - Does not use DOTALL, which means the `.` special character matches - any character *except newlines*. A common mistake is to assume - that a negated character set like `[^#]` will also not match - newlines. + Uses MULTILINE mode, which means ``^`` and ``$`` match the + beginning and end of the file, as well as the beginning and end + respectively of *each line* of the file. + Does not use DOTALL, which means the ``.`` special character + matches any character *except newlines*. A common mistake is to + assume that a negated character set like ``[^#]`` will also not + match newlines. In order to exclude newlines, they must be added to the set like - `[^#\\n]`. + ``[^#\\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. @@ -3967,35 +3985,34 @@ def replace( 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 `\\1`, or explicitly - like `\\g<1>`. + Backreferences can be used ambiguously like ``\\1``, or explicitly + like ``\\g<1>``. :param after: If specified, only content after this match will be replaced/removed. - Can be used in combination with `before`. + Can be used in combination with ``before``. Uses Python regular expressions; see `reference `__. - Uses DOTALL, which means the `.` special character *can match + Uses DOTALL, which means the ``.`` special character *can match newlines*. - Does not use MULTILINE, so `^` and `$` will only match the + Does not use MULTILINE, so ``^`` and ``$`` will only match the beginning and end of the file. :param before: If specified, only content before this match will be replaced/removed. - Can be used in combination with `after`. + Can be used in combination with ``after``. Uses Python regular expressions; see `reference `__. - Uses DOTALL, which means the `.` special character *can match + Uses DOTALL, which means the ``.`` special character *can match newlines*. - Does not use MULTILINE, so `^` and `$` will only match the + Does not use MULTILINE, so ``^`` and ``$`` will only match the beginning and end of the file. :param backup: Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. :param others: - All arguments accepted by the :meth:`ansible.builtin.file` module - also work here. + All arguments accepted by the :meth:`file` module also work here. :param encoding: The character encoding for reading and writing the file. :param mode: @@ -4003,23 +4020,23 @@ def replace( For those used to */usr/bin/chmod* remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal - numbers (for example, `'644'` or `'1777'`) so Ansible receives a - string and can do its own conversion from string into number. - Adding a leading zero (for example, `0755`) works sometimes, but + numbers (for example, ``'644'`` or ``'1777'``) so Ansible receives + a string and can do its own conversion from string into number. + Adding a leading zero (for example, ``0755``) works sometimes, but can fail in loops and some other circumstances. Giving Ansible a number without following either 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, `u+rwx` or `u=rw,g=r,o=r`). - If `mode` is not specified and the destination filesystem object - **does not** exist, the default `umask` on the system will be used - when setting the mode for the newly created filesystem object. - If `mode` is not specified and the destination filesystem object + (for example, ``u+rwx`` or ``u=rw,g=r,o=r``). + If ``mode`` is not specified and the destination filesystem object + **does not** exist, the default ``umask`` on the system will be + used when setting the mode for the newly created filesystem object. + If ``mode`` is not specified and the destination filesystem object **does** exist, the mode of the existing filesystem object will be used. - Specifying `mode` is the best way to ensure filesystem objects are - created with the correct permissions. See CVE-2020-1736 for + Specifying ``mode`` is the best way to ensure filesystem objects + are created with the correct permissions. See CVE-2020-1736 for further details. :param owner: Name of the user that should own the filesystem object, as would @@ -4036,21 +4053,21 @@ def replace( previous ownership. :param seuser: The user part of the SELinux filesystem object context. - By default it uses the `system` policy, where applicable. - When set to `_default`, it will use the `user` portion of the + By default it uses the ``system`` policy, where applicable. + When set to ``_default``, it will use the ``user`` portion of the policy if available. :param serole: The role part of the SELinux filesystem object context. - When set to `_default`, it will use the `role` portion of the + When set to ``_default``, it will use the ``role`` portion of the policy if available. :param setype: The type part of the SELinux filesystem object context. - When set to `_default`, it will use the `type` portion of the + When set to ``_default``, it will use the ``type`` portion of the policy if available. :param selevel: The level part of the SELinux filesystem object context. - This is the MLS/MCS attribute, sometimes known as the `range`. - When set to `_default`, it will use the `level` portion of the + This is the MLS/MCS attribute, sometimes known as the ``range``. + When set to ``_default``, it will use the ``level`` portion of the policy if available. :param unsafe_writes: Influence when to use atomic operation to prevent data corruption @@ -4072,7 +4089,7 @@ def replace( target system. This string should contain the attributes in the same order as the one displayed by *lsattr*. - The `=` operator is assumed as default, otherwise `+` or `-` + The ``=`` operator is assumed as default, otherwise ``+`` or ``-`` operators need to be included in the string. :param validate: The validation command to run before copying the updated file into @@ -4082,7 +4099,7 @@ def replace( Also, the command is passed securely so shell features such as expansion and pipes will not work. For an example on how to handle more complex validation than what - this option provides, see `handling complex validation`. + this option provides, see ``handling complex validation``. """ # noqa: E501 raise AttributeError('replace') @@ -4106,7 +4123,7 @@ def rpm_key( :param state: If the key will be imported or removed from the rpm db. :param validate_certs: - If `false` and the `key` is a url starting with `https`, SSL + If ``false`` and the ``key`` is a url starting with ``https``, SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates. @@ -4183,15 +4200,15 @@ def service( :param name: Name of the service. :param state: - `started`/`stopped` are idempotent actions that will not run + ``started``/``stopped`` are idempotent actions that will not run commands unless necessary. - `restarted` will always bounce the service. - `reloaded` will always reload. + ``restarted`` will always bounce the service. + ``reloaded`` will always reload. **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. :param sleep: - If the service is being `restarted` then sleep this many seconds + If the service is being ``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. @@ -4219,7 +4236,7 @@ def service( Normally it uses the value of the 'ansible_service_mgr' fact and falls back to the old 'service' module when none matching is found. The 'old service module' still uses autodetection and in no way - does it correspond to the `service` command. + does it correspond to the ``service`` command. """ # noqa: E501 raise AttributeError('service') @@ -4245,10 +4262,10 @@ def set_fact( :ref:`ansible.builtin ` :param key_value: - The :meth:`ansible.builtin.set_fact` module takes `key=value` - pairs or `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. + The :meth:`set_fact` module takes ``key=value`` pairs or + ``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. :param cacheable: @@ -4264,7 +4281,7 @@ def set_fact( 'set_fact' host variable with high precedence and a lower 'ansible_fact' one that is available for persistence via the facts cache plugin. This creates a possibly confusing interaction with - `meta: clear_facts` as it will remove the 'ansible_fact' but not + ``meta: clear_facts`` as it will remove the 'ansible_fact' but not the host variable. """ # noqa: E501 raise AttributeError('set_fact') @@ -4289,7 +4306,7 @@ def set_stats( whether the stats are per host or for all hosts in the run. :param aggregate: Whether the provided value is aggregated to the existing stat - `true` or will replace it `false`. + ``true`` or will replace it ``false``. """ # noqa: E501 raise AttributeError('set_stats') @@ -4320,30 +4337,33 @@ def setup( :param gather_subset: If supplied, restrict the additional facts collected to the given - subset. Possible values: `all`, `all_ipv4_addresses`, - `all_ipv6_addresses`, `apparmor`, `architecture`, `caps`, - `chroot`,`cmdline`, `date_time`, `default_ipv4`, `default_ipv6`, - `devices`, `distribution`, `distribution_major_version`, - `distribution_release`, `distribution_version`, `dns`, - `effective_group_ids`, `effective_user_id`, `env`, `facter`, - `fips`, `hardware`, `interfaces`, `is_chroot`, `iscsi`, `kernel`, - `local`, `lsb`, `machine`, `machine_id`, `mounts`, `network`, - `ohai`, `os_family`, `pkg_mgr`, `platform`, `processor`, - `processor_cores`, `processor_count`, `python`, `python_version`, - `real_user_id`, `selinux`, `service_mgr`, - `ssh_host_key_dsa_public`, `ssh_host_key_ecdsa_public`, - `ssh_host_key_ed25519_public`, `ssh_host_key_rsa_public`, - `ssh_host_pub_keys`, `ssh_pub_keys`, `system`, - `system_capabilities`, `system_capabilities_enforced`, `user`, - `user_dir`, `user_gecos`, `user_gid`, `user_id`, `user_shell`, - `user_uid`, `virtual`, `virtualization_role`, - `virtualization_type`. Can specify a list of values to specify a - larger subset. Values can also be used with an initial `!` to - specify that that specific subset should not be collected. For - instance: `!hardware,!network,!virtual,!ohai,!facter`. If `!all` - is specified then only the min subset is collected. To avoid - collecting even the min subset, specify `!all,!min`. To collect - only specific facts, use `!all,!min`, and specify the particular + subset. Possible values: ``all``, ``all_ipv4_addresses``, + ``all_ipv6_addresses``, ``apparmor``, ``architecture``, ``caps``, + ``chroot``,``cmdline``, ``date_time``, ``default_ipv4``, + ``default_ipv6``, ``devices``, ``distribution``, + ``distribution_major_version``, ``distribution_release``, + ``distribution_version``, ``dns``, ``effective_group_ids``, + ``effective_user_id``, ``env``, ``facter``, ``fips``, + ``hardware``, ``interfaces``, ``is_chroot``, ``iscsi``, + ``kernel``, ``local``, ``lsb``, ``machine``, ``machine_id``, + ``mounts``, ``network``, ``ohai``, ``os_family``, ``pkg_mgr``, + ``platform``, ``processor``, ``processor_cores``, + ``processor_count``, ``python``, ``python_version``, + ``real_user_id``, ``selinux``, ``service_mgr``, + ``ssh_host_key_dsa_public``, ``ssh_host_key_ecdsa_public``, + ``ssh_host_key_ed25519_public``, ``ssh_host_key_rsa_public``, + ``ssh_host_pub_keys``, ``ssh_pub_keys``, ``system``, + ``system_capabilities``, ``system_capabilities_enforced``, + ``user``, ``user_dir``, ``user_gecos``, ``user_gid``, ``user_id``, + ``user_shell``, ``user_uid``, ``virtual``, + ``virtualization_role``, ``virtualization_type``. Can specify a + list of values to specify a larger subset. Values can also be used + with an initial ``!`` to specify that that specific subset should + not be collected. For instance: + ``!hardware,!network,!virtual,!ohai,!facter``. If ``!all`` is + specified then only the min subset is collected. To avoid + collecting even the min subset, specify ``!all,!min``. To collect + only specific facts, use ``!all,!min``, and specify the particular fact subsets. Use the filter parameter if you do not want to display some collected facts. :param gather_timeout: @@ -4356,20 +4376,20 @@ def setup( accepted and works as a single pattern. The behaviour prior to Ansible 2.11 remains. :param fact_path: - Path used for local ansible facts (`*.fact`) - files in this dir + Path used for local ansible facts (``*.fact``) - files in this dir will be run (if executable) and their results be added to - `ansible_local` facts. If a file is not executable it is read + ``ansible_local`` facts. If a file is not executable it is read instead. File/results format can be JSON or INI-format. The - default `fact_path` can be specified in `ansible.cfg` for when - setup is automatically called as part of `gather_facts`. NOTE - + default ``fact_path`` can be specified in ``ansible.cfg`` for when + setup is automatically called as part of ``gather_facts``. NOTE - For windows clients, the results will be added to a variable named after the local file (without extension suffix), rather than - `ansible_local`. - Since Ansible 2.1, Windows hosts can use `fact_path`. Make sure + ``ansible_local``. + Since Ansible 2.1, Windows hosts can use ``fact_path``. Make sure that this path exists on the target host. Files in this path MUST - be PowerShell scripts `.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. + be PowerShell scripts ``.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. """ # noqa: E501 raise AttributeError('setup') @@ -4475,15 +4495,15 @@ def stat( 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, `md5` - can be unavailable if the host is FIPS-140 compliant. + The remote host has to support the hashing method specified, + ``md5`` can be unavailable if the host is FIPS-140 compliant. :param get_mime: 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 `stat.mimetype` and `stat.charset` fields to - the return, if possible. - In Ansible 2.3 this option changed from `mime` to `get_mime` and - the default changed to `true`. + This will add both ``stat.mimetype`` and ``stat.charset`` fields + to the return, if possible. + In Ansible 2.3 this option changed from ``mime`` to ``get_mime`` + and the default changed to ``true``. :param get_attributes: Get file attributes using lsattr tool if present. """ # noqa: E501 @@ -4516,41 +4536,42 @@ def subversion( The subversion URL to the repository. :param dest: Absolute path where the repository should be deployed. - The destination directory must be specified unless `checkout=no`, - `update=no`, and `export=no`. + The destination directory must be specified unless + ``checkout=no``, ``update=no``, and ``export=no``. :param revision: Specific revision to checkout. :param force: - If `true`, modified files will be discarded. If `false`, module - will fail if it encounters modified files. Prior to 1.9 the - default was `true`. + If ``true``, modified files will be discarded. If ``false``, + module will fail if it encounters modified files. Prior to 1.9 the + default was ``true``. :param in_place: If the directory exists, then the working copy will be checked-out over-the-top using svn checkout --force; if force is specified then existing files with different content are reverted. :param username: - `--username` parameter passed to svn. + ``--username`` parameter passed to svn. :param password: - `--password` parameter passed to svn when svn is less than version - 1.10.0. This is not secure and the password will be leaked to argv. - `--password-from-stdin` parameter when svn is greater or equal to - version 1.10.0. + ``--password`` parameter passed to svn when svn is less than + version 1.10.0. This is not secure and the password will be leaked + to argv. + ``--password-from-stdin`` parameter when svn is greater or equal + to version 1.10.0. :param executable: Path to svn executable to use. If not supplied, the normal mechanism for resolving binary paths will be used. :param checkout: - If `false`, do not check out the repository if it does not exist + If ``false``, do not check out the repository if it does not exist locally. :param update: - If `false`, do not retrieve new revisions from the origin + If ``false``, do not retrieve new revisions from the origin repository. :param export: - If `true`, do export instead of checkout/update. + If ``true``, do export instead of checkout/update. :param switch: - If `false`, do not call svn switch before update. + If ``false``, do not call svn switch before update. :param validate_certs: - If `false`, passes the `--trust-server-cert` flag to svn. - If `true`, does not pass the flag. + If ``false``, passes the ``--trust-server-cert`` flag to svn. + If ``true``, does not pass the flag. """ # noqa: E501 raise AttributeError('subversion') @@ -4581,45 +4602,46 @@ def systemd( :param name: Name of the unit. This parameter takes the name of exactly one unit to work with. - When no extension is given, it is implied to a `.service` as + When no extension is given, it is implied to a ``.service`` as systemd. When using in a chroot environment you always need to specify the - name of the unit with the extension. For example, `crond.service`. + name of the unit with the extension. For example, + ``crond.service``. :param state: - `started`/`stopped` are idempotent actions that will not run - commands unless necessary. `restarted` will always bounce the - unit. `reloaded` will always reload and if the service is not + ``started``/``stopped`` are idempotent actions that will not run + commands unless necessary. ``restarted`` will always bounce the + unit. ``reloaded`` will always reload and if the service is not running at the moment of the reload, it is started. - If set, requires `name`. + If set, requires ``name``. :param enabled: Whether the unit should start on boot. **At least one of state and enabled are required.**. - If set, requires `name`. + If set, requires ``name``. :param force: Whether to override existing symlinks. :param masked: Whether the unit should be masked or not. A masked unit is impossible to start. - If set, requires `name`. + If set, requires ``name``. :param daemon_reload: Run daemon-reload before doing any other operations, to make sure systemd has read any changes. - When set to `true`, runs daemon-reload even if the module does not - start or stop anything. + When set to ``true``, runs daemon-reload even if the module does + not start or stop anything. :param daemon_reexec: Run daemon_reexec command before doing any other operations, the systemd manager will serialize the manager state. :param scope: Run systemctl within a given service manager scope, either as the - default system scope `system`, the current user's scope `user`, or - the scope of all users `global`. + default system scope ``system``, the current user's scope + ``user``, or the scope of all users ``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. The user must have access, normally given via setting the - `XDG_RUNTIME_DIR` variable, see the example below. + ``XDG_RUNTIME_DIR`` variable, see the example below. :param no_block: Do not synchronously wait for the requested operation to finish. Enqueued job will continue without Ansible blocking on its @@ -4654,45 +4676,46 @@ def systemd_service( :param name: Name of the unit. This parameter takes the name of exactly one unit to work with. - When no extension is given, it is implied to a `.service` as + When no extension is given, it is implied to a ``.service`` as systemd. When using in a chroot environment you always need to specify the - name of the unit with the extension. For example, `crond.service`. + name of the unit with the extension. For example, + ``crond.service``. :param state: - `started`/`stopped` are idempotent actions that will not run - commands unless necessary. `restarted` will always bounce the - unit. `reloaded` will always reload and if the service is not + ``started``/``stopped`` are idempotent actions that will not run + commands unless necessary. ``restarted`` will always bounce the + unit. ``reloaded`` will always reload and if the service is not running at the moment of the reload, it is started. - If set, requires `name`. + If set, requires ``name``. :param enabled: Whether the unit should start on boot. **At least one of state and enabled are required.**. - If set, requires `name`. + If set, requires ``name``. :param force: Whether to override existing symlinks. :param masked: Whether the unit should be masked or not. A masked unit is impossible to start. - If set, requires `name`. + If set, requires ``name``. :param daemon_reload: Run daemon-reload before doing any other operations, to make sure systemd has read any changes. - When set to `true`, runs daemon-reload even if the module does not - start or stop anything. + When set to ``true``, runs daemon-reload even if the module does + not start or stop anything. :param daemon_reexec: Run daemon_reexec command before doing any other operations, the systemd manager will serialize the manager state. :param scope: Run systemctl within a given service manager scope, either as the - default system scope `system`, the current user's scope `user`, or - the scope of all users `global`. + default system scope ``system``, the current user's scope + ``user``, or the scope of all users ``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. The user must have access, normally given via setting the - `XDG_RUNTIME_DIR` variable, see the example below. + ``XDG_RUNTIME_DIR`` variable, see the example below. :param no_block: Do not synchronously wait for the requested operation to finish. Enqueued job will continue without Ansible blocking on its @@ -4726,17 +4749,17 @@ def sysvinit( :param name: Name of the service. :param state: - `started`/`stopped` are idempotent actions that will not run + ``started``/``stopped`` are idempotent actions that will not run commands unless necessary. Not all init scripts support - `restarted` nor `reloaded` natively, so these will both trigger a - stop and start as needed. + ``restarted`` nor ``reloaded`` natively, so these will both + trigger a stop and start as needed. :param enabled: Whether the service should start on boot. **At least one of state and enabled are required.**. :param sleep: - If the service is being `restarted` or `reloaded` then sleep this - many seconds between the stop and start command. This helps to - workaround badly behaving services. + If the service is being ``restarted`` or ``reloaded`` then sleep + this many seconds between the stop and start command. This helps + to workaround badly behaving services. :param pattern: A substring to look for as would be found in the output of the *ps* command as a stand-in for a status result. @@ -4824,9 +4847,10 @@ def template( :param follow: Determine whether symbolic links should be followed. - When set to `true` symbolic links will be followed, if they exist. - When set to `false` symbolic links will not be followed. - Previous to Ansible 2.4, this was hardcoded as `true`. + When set to ``true`` symbolic links will be followed, if they + exist. + When set to ``false`` symbolic links will not be followed. + Previous to Ansible 2.4, this was hardcoded as ``true``. :param backup: Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it @@ -4836,23 +4860,23 @@ def template( For those used to */usr/bin/chmod* remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal - numbers (for example, `'644'` or `'1777'`) so Ansible receives a - string and can do its own conversion from string into number. - Adding a leading zero (for example, `0755`) works sometimes, but + numbers (for example, ``'644'`` or ``'1777'``) so Ansible receives + a string and can do its own conversion from string into number. + Adding a leading zero (for example, ``0755``) works sometimes, but can fail in loops and some other circumstances. Giving Ansible a number without following either 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, `u+rwx` or `u=rw,g=r,o=r`). - If `mode` is not specified and the destination filesystem object - **does not** exist, the default `umask` on the system will be used - when setting the mode for the newly created filesystem object. - If `mode` is not specified and the destination filesystem object + (for example, ``u+rwx`` or ``u=rw,g=r,o=r``). + If ``mode`` is not specified and the destination filesystem object + **does not** exist, the default ``umask`` on the system will be + used when setting the mode for the newly created filesystem object. + If ``mode`` is not specified and the destination filesystem object **does** exist, the mode of the existing filesystem object will be used. - Specifying `mode` is the best way to ensure filesystem objects are - created with the correct permissions. See CVE-2020-1736 for + Specifying ``mode`` is the best way to ensure filesystem objects + are created with the correct permissions. See CVE-2020-1736 for further details. :param owner: Name of the user that should own the filesystem object, as would @@ -4869,21 +4893,21 @@ def template( previous ownership. :param seuser: The user part of the SELinux filesystem object context. - By default it uses the `system` policy, where applicable. - When set to `_default`, it will use the `user` portion of the + By default it uses the ``system`` policy, where applicable. + When set to ``_default``, it will use the ``user`` portion of the policy if available. :param serole: The role part of the SELinux filesystem object context. - When set to `_default`, it will use the `role` portion of the + When set to ``_default``, it will use the ``role`` portion of the policy if available. :param setype: The type part of the SELinux filesystem object context. - When set to `_default`, it will use the `type` portion of the + When set to ``_default``, it will use the ``type`` portion of the policy if available. :param selevel: The level part of the SELinux filesystem object context. - This is the MLS/MCS attribute, sometimes known as the `range`. - When set to `_default`, it will use the `level` portion of the + This is the MLS/MCS attribute, sometimes known as the ``range``. + When set to ``_default``, it will use the ``level`` portion of the policy if available. :param unsafe_writes: Influence when to use atomic operation to prevent data corruption @@ -4905,13 +4929,13 @@ def template( target system. This string should contain the attributes in the same order as the one displayed by *lsattr*. - The `=` operator is assumed as default, otherwise `+` or `-` + The ``=`` operator is assumed as default, otherwise ``+`` or ``-`` operators need to be included in the string. :param src: Path of a Jinja2 formatted template on the Ansible controller. This can be a relative or an absolute path. - The file must be encoded with `utf-8` but `output_encoding` can be - used to control the encoding of the output template. + The file must be encoded with ``utf-8`` but ``output_encoding`` + can be used to control the encoding of the output template. :param dest: Location to render the template to on the remote machine. :param newline_sequence: @@ -4930,26 +4954,26 @@ def template( The string marking the end of a comment statement. :param trim_blocks: Determine when newlines should be removed from blocks. - When set to `True` the first newline after a block is removed + When set to ``True`` the first newline after a block is removed (block, not variable tag!). :param lstrip_blocks: Determine when leading spaces and tabs should be stripped. - When set to `True` leading spaces and tabs are stripped from the + When set to ``True`` leading spaces and tabs are stripped from the start of a line to a block. :param force: Determine when the file is being transferred if the destination already exists. - When set to `True`, replace the remote file when contents are + When set to ``True``, replace the remote file when contents are different than the source. - When set to `False`, the file will only be transferred if the + When set to ``False``, the file will only be transferred if the destination does not exist. :param output_encoding: Overrides the encoding used to write the template file defined by - `dest`. - It defaults to `utf-8`, but any encoding supported by python can + ``dest``. + It defaults to ``utf-8``, but any encoding supported by python can be used. - The source template file must always be encoded using `utf-8`, for - homogeneity. + The source template file must always be encoded using ``utf-8``, + for homogeneity. :param validate: The validation command to run before copying the updated file into the final destination. @@ -4958,7 +4982,7 @@ def template( Also, the command is passed securely so shell features such as expansion and pipes will not work. For an example on how to handle more complex validation than what - this option provides, see `handling complex validation`. + this option provides, see ``handling complex validation``. """ # noqa: E501 raise AttributeError('template') @@ -4996,14 +5020,14 @@ def unarchive( :ref:`ansible.builtin ` :param src: - If `remote_src=no` (default), local path to archive file to copy + If ``remote_src=no`` (default), local path to archive file to copy to the target server; can be absolute or relative. If - `remote_src=yes`, path on the target server to existing archive + ``remote_src=yes``, path on the target server to existing archive file to unpack. - If `remote_src=yes` and `src` contains `://`, 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 - :meth:`ansible.builtin.get_url` module. + If ``remote_src=yes`` and ``src`` contains ``://``, 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 :meth:`get_url` module. :param dest: Remote absolute path where the archive should be unpacked. The given path must exist. Base directory is not created by this @@ -5012,13 +5036,13 @@ def unarchive( 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 `remote_src`. - This option is mutually exclusive with `remote_src`. + This option has been deprecated in favor of ``remote_src``. + This option is mutually exclusive with ``remote_src``. :param creates: If the specified absolute path (file or directory) already exists, this step will **not** be run. The specified absolute path (file or directory) must be below the - base path given with `dest`. + base path given with ``dest``. :param io_buffer_size: Size of the volatile memory buffer that is used for extracting files from the archive in bytes. @@ -5028,12 +5052,12 @@ def unarchive( :param exclude: List the directory and file entries that you would like to exclude from the unarchive action. - Mutually exclusive with `include`. + Mutually exclusive with ``include``. :param include: List of directory and file entries that you would like to extract - from the archive. If `include` is not empty, only files listed + from the archive. If ``include`` is not empty, only files listed here will be extracted. - Mutually exclusive with `exclude`. + Mutually exclusive with ``exclude``. :param keep_newer: Do not replace existing files that are newer than files from the archive. @@ -5044,14 +5068,14 @@ def unarchive( Command-line options with multiple elements must use multiple lines in the array, one for each element. :param remote_src: - Set to `true` to indicate the archived file is already on the + Set to ``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 `copy`. + This option is mutually exclusive with ``copy``. :param validate_certs: This only applies if using a https URL as the source of the file. - This should only set to `false` used on personally controlled + This should only set to ``false`` used on personally controlled sites using self-signed certificate. - Prior to 2.2 the code worked as if this was set to `true`. + Prior to 2.2 the code worked as if this was set to ``true``. :param decrypt: This option controls the auto-decryption of source files using vault. @@ -5060,23 +5084,23 @@ def unarchive( For those used to */usr/bin/chmod* remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal - numbers (for example, `'644'` or `'1777'`) so Ansible receives a - string and can do its own conversion from string into number. - Adding a leading zero (for example, `0755`) works sometimes, but + numbers (for example, ``'644'`` or ``'1777'``) so Ansible receives + a string and can do its own conversion from string into number. + Adding a leading zero (for example, ``0755``) works sometimes, but can fail in loops and some other circumstances. Giving Ansible a number without following either 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, `u+rwx` or `u=rw,g=r,o=r`). - If `mode` is not specified and the destination filesystem object - **does not** exist, the default `umask` on the system will be used - when setting the mode for the newly created filesystem object. - If `mode` is not specified and the destination filesystem object + (for example, ``u+rwx`` or ``u=rw,g=r,o=r``). + If ``mode`` is not specified and the destination filesystem object + **does not** exist, the default ``umask`` on the system will be + used when setting the mode for the newly created filesystem object. + If ``mode`` is not specified and the destination filesystem object **does** exist, the mode of the existing filesystem object will be used. - Specifying `mode` is the best way to ensure filesystem objects are - created with the correct permissions. See CVE-2020-1736 for + Specifying ``mode`` is the best way to ensure filesystem objects + are created with the correct permissions. See CVE-2020-1736 for further details. :param owner: Name of the user that should own the filesystem object, as would @@ -5093,21 +5117,21 @@ def unarchive( previous ownership. :param seuser: The user part of the SELinux filesystem object context. - By default it uses the `system` policy, where applicable. - When set to `_default`, it will use the `user` portion of the + By default it uses the ``system`` policy, where applicable. + When set to ``_default``, it will use the ``user`` portion of the policy if available. :param serole: The role part of the SELinux filesystem object context. - When set to `_default`, it will use the `role` portion of the + When set to ``_default``, it will use the ``role`` portion of the policy if available. :param setype: The type part of the SELinux filesystem object context. - When set to `_default`, it will use the `type` portion of the + When set to ``_default``, it will use the ``type`` portion of the policy if available. :param selevel: The level part of the SELinux filesystem object context. - This is the MLS/MCS attribute, sometimes known as the `range`. - When set to `_default`, it will use the `level` portion of the + This is the MLS/MCS attribute, sometimes known as the ``range``. + When set to ``_default``, it will use the ``level`` portion of the policy if available. :param unsafe_writes: Influence when to use atomic operation to prevent data corruption @@ -5129,7 +5153,7 @@ def unarchive( target system. This string should contain the attributes in the same order as the one displayed by *lsattr*. - The `=` operator is assumed as default, otherwise `+` or `-` + The ``=`` operator is assumed as default, otherwise ``+`` or ``-`` operators need to be included in the string. """ # noqa: E501 raise AttributeError('unarchive') @@ -5197,7 +5221,8 @@ def uri( :param ciphers: SSL/TLS Ciphers to use for the request. - When a list is provided, all ciphers are joined in order with `:`. + When a list is provided, all ciphers are joined in order with + ``:``. See the `OpenSSL Cipher List Format `__ for more details. @@ -5211,9 +5236,9 @@ def uri( HTTP or HTTPS URL in the form (http|https)://host.domain[:port]/path. :param dest: - A path of where to download the file to (if desired). If `dest` is - a directory, the basename of the file on the remote server will be - used. + A path of where to download the file to (if desired). If ``dest`` + is a directory, the basename of the file on the remote server will + be used. :param url_username: A username for the module to use for Digest, Basic or WSSE authentication. @@ -5222,24 +5247,25 @@ def uri( authentication. :param body: The body of the http request/response to the web service. If - `body_format` is set to `json` it will take an already formatted - JSON string or convert a data structure into JSON. - If `body_format` is set to `form-urlencoded` it will convert a + ``body_format`` is set to ``json`` it will take an already + formatted JSON string or convert a data structure into JSON. + If ``body_format`` is set to ``form-urlencoded`` it will convert a dictionary or list of tuples into an 'application/x-www-form-urlencoded' string. (Added in v2.7). - If `body_format` is set to `form-multipart` it will convert a + If ``body_format`` is set to ``form-multipart`` it will convert a dictionary into 'multipart/form-multipart' body. (Added in v2.10). :param body_format: - The serialization format of the body. When set to `json`, - `form-multipart`, or `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 `Content-Type` header, - when set to `json` or `form-urlencoded` via the `headers` option. + The serialization format of the body. When set to ``json``, + ``form-multipart``, or ``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 ``Content-Type`` header, + when set to ``json`` or ``form-urlencoded`` via the ``headers`` + option. The 'Content-Type' header cannot be overridden when using - `form-multipart`. - `form-urlencoded` was added in v2.7. - `form-multipart` was added in v2.10. + ``form-multipart``. + ``form-urlencoded`` was added in v2.7. + ``form-multipart`` was added in v2.10. :param method: The HTTP method of the request or response. In more recent versions we do not restrict the method at the @@ -5250,14 +5276,14 @@ def uri( 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 `ignore:json` in the dictionary results. + called ``ignore:json`` in the dictionary results. :param force_basic_auth: Force the sending of the Basic authentication header upon initial request. - When this setting is `false`, this module will first try an + When this setting is ``false``, this module will first try an unauthenticated request, and when the server replies with an - `HTTP 401` error, it will submit the Basic authentication header. - When this setting is `true`, this module will immediately send a + ``HTTP 401`` error, it will submit the Basic authentication header. + When this setting is ``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 @@ -5281,42 +5307,42 @@ def uri( The socket level timeout in seconds. :param headers: Add custom HTTP headers to a request in the format of a YAML hash. - As of Ansible 2.3 supplying `Content-Type` here will override the - header generated by supplying `json` or `form-urlencoded` for - `body_format`. + As of Ansible 2.3 supplying ``Content-Type`` here will override + the header generated by supplying ``json`` or ``form-urlencoded`` + for ``body_format``. :param validate_certs: - If `false`, SSL certificates will not be validated. - This should only set to `false` used on personally controlled + If ``false``, SSL certificates will not be validated. + This should only set to ``false`` used on personally controlled sites using self-signed certificates. - Prior to 1.9.2 the code defaulted to `false`. + Prior to 1.9.2 the code defaulted to ``false``. :param client_cert: 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, `client_key` is not required. + included, ``client_key`` is not required. :param client_key: PEM formatted file that contains your private key to be used for SSL client authentication. - If `client_cert` contains both the certificate and key, this + If ``client_cert`` contains both the certificate and key, this option is not required. :param ca_path: PEM formatted file that contains a CA certificate to be used for validation. :param src: Path to file to be submitted to the remote server. - Cannot be used with `body`. - Should be used with `force_basic_auth` to ensure success when the - remote end sends a 401. + Cannot be used with ``body``. + Should be used with ``force_basic_auth`` to ensure success when + the remote end sends a 401. :param remote_src: - If `false`, the module will search for the `src` on the controller - node. - If `true`, the module will search for the `src` on the managed + If ``false``, the module will search for the ``src`` on the + controller node. + If ``true``, the module will search for the ``src`` on the managed (remote) node. :param force: - If `true` do not get a cached copy. + If ``true`` do not get a cached copy. :param use_proxy: - If `false`, it will not use a proxy, even if one is defined in an - environment variable on the target hosts. + If ``false``, it will not use a proxy, even if one is defined in + an environment variable on the target hosts. :param unix_socket: Path to Unix domain socket to use for connection. :param http_agent: @@ -5325,7 +5351,7 @@ def uri( A list of header names that will not be sent on subsequent redirected requests. This list is case insensitive. By default all headers will be redirected. In some cases it may be beneficial to - list headers such as `Authorization` here to avoid potential + list headers such as ``Authorization`` here to avoid potential credential exposure. :param use_gssapi: Use GSSAPI to perform the authentication, typically this is for @@ -5333,8 +5359,8 @@ def uri( Requires the Python library `gssapi `__ to be installed. Credentials for GSSAPI can be specified with - `url_username`/`url_password` or with the GSSAPI env var - `KRB5CCNAME` that specified a custom Kerberos credential cache. + ``url_username``/``url_password`` or with the GSSAPI env var + ``KRB5CCNAME`` that specified a custom Kerberos credential cache. NTLM authentication is **not** supported even if the GSSAPI mech for NTLM has been installed. :param use_netrc: @@ -5347,23 +5373,23 @@ def uri( For those used to */usr/bin/chmod* remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal - numbers (for example, `'644'` or `'1777'`) so Ansible receives a - string and can do its own conversion from string into number. - Adding a leading zero (for example, `0755`) works sometimes, but + numbers (for example, ``'644'`` or ``'1777'``) so Ansible receives + a string and can do its own conversion from string into number. + Adding a leading zero (for example, ``0755``) works sometimes, but can fail in loops and some other circumstances. Giving Ansible a number without following either 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, `u+rwx` or `u=rw,g=r,o=r`). - If `mode` is not specified and the destination filesystem object - **does not** exist, the default `umask` on the system will be used - when setting the mode for the newly created filesystem object. - If `mode` is not specified and the destination filesystem object + (for example, ``u+rwx`` or ``u=rw,g=r,o=r``). + If ``mode`` is not specified and the destination filesystem object + **does not** exist, the default ``umask`` on the system will be + used when setting the mode for the newly created filesystem object. + If ``mode`` is not specified and the destination filesystem object **does** exist, the mode of the existing filesystem object will be used. - Specifying `mode` is the best way to ensure filesystem objects are - created with the correct permissions. See CVE-2020-1736 for + Specifying ``mode`` is the best way to ensure filesystem objects + are created with the correct permissions. See CVE-2020-1736 for further details. :param owner: Name of the user that should own the filesystem object, as would @@ -5380,21 +5406,21 @@ def uri( previous ownership. :param seuser: The user part of the SELinux filesystem object context. - By default it uses the `system` policy, where applicable. - When set to `_default`, it will use the `user` portion of the + By default it uses the ``system`` policy, where applicable. + When set to ``_default``, it will use the ``user`` portion of the policy if available. :param serole: The role part of the SELinux filesystem object context. - When set to `_default`, it will use the `role` portion of the + When set to ``_default``, it will use the ``role`` portion of the policy if available. :param setype: The type part of the SELinux filesystem object context. - When set to `_default`, it will use the `type` portion of the + When set to ``_default``, it will use the ``type`` portion of the policy if available. :param selevel: The level part of the SELinux filesystem object context. - This is the MLS/MCS attribute, sometimes known as the `range`. - When set to `_default`, it will use the `level` portion of the + This is the MLS/MCS attribute, sometimes known as the ``range``. + When set to ``_default``, it will use the ``level`` portion of the policy if available. :param unsafe_writes: Influence when to use atomic operation to prevent data corruption @@ -5416,7 +5442,7 @@ def uri( target system. This string should contain the attributes in the same order as the one displayed by *lsattr*. - The `=` operator is assumed as default, otherwise `+` or `-` + The ``=`` operator is assumed as default, otherwise ``+`` or ``-`` operators need to be included in the string. """ # noqa: E501 raise AttributeError('uri') @@ -5495,11 +5521,11 @@ def user( Optionally sets the *UID* of the user. :param comment: Optionally sets the description (aka *GECOS*) of user account. - On macOS, this defaults to the `name` option. + On macOS, this defaults to the ``name`` option. :param hidden: macOS only, optionally hide the user from the login window and system preferences. - The default will be `true` if the `system` option is used. + The default will be ``true`` if the ``system`` option is used. :param non_unique: Optionally when used with the -u option, this option allows to change the user ID to a non-unique value. @@ -5508,24 +5534,24 @@ def user( systems. :param group: Optionally sets the user's primary group (takes a group name). - On macOS, this defaults to `'staff'`. + On macOS, this defaults to ``'staff'``. :param groups: A list of supplementary groups which the user is also a member of. By default, the user is removed from all other groups. Configure - `append` to modify this. - When set to an empty string `''`, the user is removed from all + ``append`` to modify this. + When set to an empty string ``''``, 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. :param append: - If `true`, add the user to the groups specified in `groups`. - If `false`, user will only be added to the groups specified in - `groups`, removing them from all other groups. + If ``true``, add the user to the groups specified in ``groups``. + If ``false``, user will only be added to the groups specified in + ``groups``, removing them from all other groups. :param shell: Optionally set the user's shell. On macOS, before Ansible 2.5, the default shell for non-system - users was `/usr/bin/false`. Since Ansible 2.5, the default shell - for non-system users on macOS is `/bin/bash`. + users was ``/usr/bin/false``. Since Ansible 2.5, the default shell + for non-system users on macOS is ``/bin/bash``. On other operating systems, the default shell is determined by the underlying tool invoked by this module. See Notes for a per platform list of invoked tools. @@ -5533,7 +5559,7 @@ def user( Optionally set the user's home directory. :param skeleton: Optionally set a home skeleton directory. - Requires `create_home` option!. + Requires ``create_home`` option!. :param password: If provided, set the user's password to the provided encrypted hash (Linux) or plain text password (macOS). @@ -5542,17 +5568,17 @@ def user( `__ 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 `'!'` or `'*'`. + systems, set this to ``'!'`` or ``'*'``. To create an account with a locked/disabled password on OpenBSD, - set this to `'*************'`. + set this to ``'*************'``. **OS X/macOS:** Enter the cleartext password as the value. Be sure to take relevant security precautions. - On macOS, the password specified in the `password` option will + On macOS, the password specified in the ``password`` option will always be set, regardless of whether the user account already exists or not. - When the password is passed as an argument, the `user` module will - always return changed to `true` for macOS systems. Since macOS no - longer provides access to the hashed passwords directly. + When the password is passed as an argument, the ``user`` module + will always return changed to ``true`` for macOS systems. Since + macOS no longer provides access to the hashed passwords directly. :param state: Whether the account should exist or not, taking action if the state is different from what is stated. @@ -5560,36 +5586,36 @@ def user( `__ for additional requirements when removing users on macOS systems. :param create_home: - Unless set to `false`, a home directory will be made for the user - when the account is created or if the home directory does not + Unless set to ``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 `createhome` to `create_home` in Ansible 2.5. + Changed from ``createhome`` to ``create_home`` in Ansible 2.5. :param move_home: - If set to `true` when used with `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. + If set to ``true`` when used with ``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. :param system: - When creating an account `state=present`, setting this to `true` - makes the user a system account. + When creating an account ``state=present``, setting this to + ``true`` makes the user a system account. This setting cannot be changed on existing users. :param force: - This only affects `state=absent`, it forces removal of the user + This only affects ``state=absent``, it forces removal of the user and associated directories on supported platforms. - The behavior is the same as `userdel --force`, check the man page - for `userdel` on your system for details and support. - When used with `generate_ssh_key=yes` this forces an existing key - to be overwritten. + The behavior is the same as ``userdel --force``, check the man + page for ``userdel`` on your system for details and support. + When used with ``generate_ssh_key=yes`` this forces an existing + key to be overwritten. :param remove: - This only affects `state=absent`, it attempts to remove + This only affects ``state=absent``, it attempts to remove directories associated with the user. - The behavior is the same as `userdel --remove`, check the man page - for details and support. + The behavior is the same as ``userdel --remove``, check the man + page for details and support. :param login_class: Optionally sets the user's login class, a feature of most BSD OSs. :param generate_ssh_key: Whether to generate a SSH key for the user in question. This will **not** overwrite an existing SSH key unless used with - `force=yes`. + ``force=yes``. :param ssh_key_bits: Optionally specify number of bits in SSH key to create. The default value depends on ssh-keygen. @@ -5601,7 +5627,7 @@ def user( 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 `.ssh/id_rsa`. + This parameter defaults to ``.ssh/id_rsa``. :param ssh_key_comment: Optionally define the comment for the SSH key. :param ssh_key_passphrase: @@ -5609,8 +5635,8 @@ def user( If no passphrase is provided, the SSH key will default to having no passphrase. :param update_password: - `always` will update passwords if they differ. - `on_create` will only set the password for newly created users. + ``always`` will update passwords if they differ. + ``on_create`` will only set the password for newly created users. :param expires: An expiry time for the user in epoch, it will be ignored on platforms that do not support this. @@ -5618,12 +5644,13 @@ def user( Since Ansible 2.6 you can remove the expiry time by specifying a negative value. Currently supported on GNU/Linux and FreeBSD. :param password_lock: - Lock the password (`usermod -L`, `usermod -U`, `pw lock`). + Lock the password (``usermod -L``, ``usermod -U``, ``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 `False` in order to unlock a currently locked - password. The absence of this parameter will not unlock a password. + This must be set to ``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. :param local: @@ -5631,28 +5658,28 @@ def user( implement it. This is useful in environments that use centralized authentication when you want to manipulate the local users (in other words, it - uses `luseradd` instead of `useradd`). - This will check `/etc/passwd` for an existing account before + uses ``luseradd`` instead of ``useradd``). + This will check ``/etc/passwd`` for an existing account before invoking commands. If the local account database exists somewhere - other than `/etc/passwd`, this setting will not work properly. - This requires that the above commands as well as `/etc/passwd` + other than ``/etc/passwd``, this setting will not work properly. + This requires that the above commands as well as ``/etc/passwd`` must exist on the target host, otherwise it will be a fatal error. :param profile: Sets the profile of the user. Can set multiple profiles using comma separation. - To delete all the profiles, use `profile=''`. + To delete all the profiles, use ``profile=''``. Currently supported on Illumos/Solaris. Does nothing when used with other platforms. :param authorization: Sets the authorization of the user. Can set multiple authorizations using comma separation. - To delete all authorizations, use `authorization=''`. + To delete all authorizations, use ``authorization=''``. Currently supported on Illumos/Solaris. Does nothing when used with other platforms. :param role: Sets the role of the user. Can set multiple roles using comma separation. - To delete all roles, use `role=''`. + To delete all roles, use ``role=''``. Currently supported on Illumos/Solaris. Does nothing when used with other platforms. :param password_expire_max: @@ -5669,7 +5696,7 @@ def user( Sets the umask of the user. Currently supported on Linux. Does nothing when used with other platforms. - Requires `local` is omitted or `False`. + Requires ``local`` is omitted or ``False``. """ # noqa: E501 raise AttributeError('user') @@ -5687,7 +5714,7 @@ def validate_argument_spec( :param argument_spec: A dictionary like AnsibleModule argument_spec. See - `argument spec definition`. + ``argument spec definition``. :param provided_arguments: A dictionary of the arguments that will be validated according to argument_spec. @@ -5736,28 +5763,29 @@ def wait_for( Number of seconds to wait before starting to poll. :param port: Port number to poll. - `path` and `port` are mutually exclusive parameters. + ``path`` and ``port`` are mutually exclusive parameters. :param active_connection_states: The list of TCP connection states which are counted as active connections. :param state: - Either `present`, `started`, or `stopped`, `absent`, or `drained`. - When checking a port `started` will ensure the port is open, - `stopped` will check that it is closed, `drained` will check for - active connections. - When checking for a file or a search string `present` or `started` - will ensure that the file or string is present before continuing, - `absent` will check that file is absent or removed. + Either ``present``, ``started``, or ``stopped``, ``absent``, or + ``drained``. + When checking a port ``started`` will ensure the port is open, + ``stopped`` will check that it is closed, ``drained`` will check + for active connections. + When checking for a file or a search string ``present`` or + ``started`` will ensure that the file or string is present before + continuing, ``absent`` will check that file is absent or removed. :param path: Path to a file on the filesystem that must exist before continuing. - `path` and `port` are mutually exclusive parameters. + ``path`` and ``port`` are mutually exclusive parameters. :param search_regex: Can be used to match a string in either a file or a socket connection. Defaults to a multiline regex. :param exclude_hosts: List of hosts or IPs to ignore when looking for active TCP - connections for `drained` state. + connections for ``drained`` state. :param sleep: Number of seconds to sleep between checks. Before Ansible 2.3 this was hardcoded to 1 second. @@ -5834,19 +5862,20 @@ def yum( Manages packages with the *yum* package manager. :param use_backend: - This module supports `yum` (as it always has), this is known as - `yum3`/`YUM3`/`yum-deprecated` by upstream yum developers. As of - Ansible 2.7+, this module also supports `YUM4`, which is the "new - yum" and it has an `dnf` backend. + This module supports ``yum`` (as it always has), this is known as + ``yum3``/``YUM3``/``yum-deprecated`` by upstream yum developers. + As of Ansible 2.7+, this module also supports ``YUM4``, which is + the "new yum" and it has an ``dnf`` backend. By default, this module will select the backend based on the - `ansible_pkg_mgr` fact. + ``ansible_pkg_mgr`` fact. :param name: - A package name or package specifier with version, like `name-1.0`. + A package name or package specifier with version, like + ``name-1.0``. If a previous version is specified, the task also needs to turn - `allow_downgrade` on. See the `allow_downgrade` documentation for - caveats with downgrading packages. - When using state=latest, this can be `'*'` which means run - `yum -y update`. + ``allow_downgrade`` on. See the ``allow_downgrade`` documentation + for caveats with downgrading packages. + When using state=latest, this can be ``'*'`` which means run + ``yum -y update``. You can also pass a url or a local path to a rpm file (using state=present). To operate on several packages this can accept a comma separated string of packages or (as of 2.0) a list of @@ -5856,32 +5885,32 @@ def yum( :param list: Package name to run the equivalent of yum list --show-duplicates against. In addition to listing packages, use can also - list the following: `installed`, `updates`, `available` and - `repos`. - This parameter is mutually exclusive with `name`. + list the following: ``installed``, ``updates``, ``available`` and + ``repos``. + This parameter is mutually exclusive with ``name``. :param state: - Whether to install (`present` or `installed`, `latest`), or remove - (`absent` or `removed`) a package. - `present` and `installed` will simply ensure that a desired + Whether to install (``present`` or ``installed``, ``latest``), or + remove (``absent`` or ``removed``) a package. + ``present`` and ``installed`` will simply ensure that a desired package is installed. - `latest` will update the specified package if it's not of the + ``latest`` will update the specified package if it's not of the latest available version. - `absent` and `removed` will remove the specified package. - Default is `None`, however in effect the default action is - `present` unless the `autoremove` option is enabled for this - module, then `absent` is inferred. + ``absent`` and ``removed`` will remove the specified package. + Default is ``None``, however in effect the default action is + ``present`` unless the ``autoremove`` option is enabled for this + module, then ``absent`` is inferred. :param enablerepo: *Repoid* of repositories to enable for the install/update operation. These repos will not persist beyond the transaction. - When specifying multiple repos, separate them with a `","`. + When specifying multiple repos, separate them with a ``","``. As of Ansible 2.7, this can alternatively be a list instead of - `","` separated string. + ``","`` separated string. :param disablerepo: *Repoid* of repositories to disable for the install/update operation. These repos will not persist beyond the transaction. - When specifying multiple repos, separate them with a `","`. + When specifying multiple repos, separate them with a ``","``. As of Ansible 2.7, this can alternatively be a list instead of - `","` separated string. + ``","`` separated string. :param conf_file: The remote yum configuration file to use for the transaction. :param disable_gpg_check: @@ -5896,12 +5925,12 @@ def yum( needed. Has an effect only if state is *present* or *latest*. :param validate_certs: This only applies if using a https url as the source of the rpm. - e.g. for localinstall. If set to `False`, the SSL certificates + e.g. for localinstall. If set to ``False``, the SSL certificates will not be validated. - This should only set to `False` used on personally controlled + This should only set to ``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 `True`. + Prior to 2.1 the code worked as if this was set to ``True``. :param update_only: When using latest, only update installed packages. Do not install packages. @@ -5910,11 +5939,11 @@ def yum( Specifies an alternative installroot, relative to which all packages will be installed. :param security: - If set to `True`, and `state=latest` then only installs updates - that have been marked security related. + If set to ``True``, and ``state=latest`` then only installs + updates that have been marked security related. :param bugfix: - If set to `True`, and `state=latest` then only installs updates - that have been marked bugfix related. + If set to ``True``, and ``state=latest`` then only installs + updates that have been marked bugfix related. :param allow_downgrade: Specify if the named package and version is allowed to downgrade a maybe already installed higher version of that package. Note that @@ -5934,16 +5963,16 @@ def yum( Specifies an alternative release from which all packages will be installed. :param autoremove: - If `True`, removes all "leaf" packages from the system that were + If ``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 *absent*. NOTE: This feature requires yum >= 3.4.3 (RHEL/CentOS 7+). :param disable_excludes: Disable the excludes defined in YUM config files. - If set to `all`, disables all excludes. - If set to `main`, disable excludes defined in [main] in yum.conf. - If set to `repoid`, disable excludes defined for given repo id. + If set to ``all``, disables all excludes. + If set to ``main``, disable excludes defined in [main] in yum.conf. + If set to ``repoid``, disable excludes defined for given repo id. :param download_only: Only download the packages, do not install them. :param lock_timeout: @@ -6047,139 +6076,140 @@ def yum_repository( :ref:`ansible.builtin ` :param async: - If set to `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 `true`. + If set to ``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 ``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. :param bandwidth: Maximum available network bandwidth in bytes/second. Used with the - `throttle` option. - If `throttle` is a percentage and bandwidth is `0` then bandwidth - throttling will be disabled. If `throttle` is expressed as a data - rate (bytes/sec) then this option is ignored. Default is `0` (no - bandwidth throttling). + ``throttle`` option. + If ``throttle`` is a percentage and bandwidth is ``0`` then + bandwidth throttling will be disabled. If ``throttle`` is + expressed as a data rate (bytes/sec) then this option is ignored. + Default is ``0`` (no bandwidth throttling). :param baseurl: URL to the directory where the yum repository's 'repodata' directory lives. It can also be a list of multiple URLs. - This, the `metalink` or `mirrorlist` parameters are required if - `state` is set to `present`. + This, the ``metalink`` or ``mirrorlist`` parameters are required + if ``state`` is set to ``present``. :param cost: Relative cost of accessing this repository. Useful for weighing one repo's packages as greater/less than any other. :param deltarpm_metadata_percentage: 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 `100`, so `200` means that the metadata - is required to be half the size of the packages. Use `0` to turn - off this check, and always download metadata. + you can give values over ``100``, so ``200`` means that the + metadata is required to be half the size of the packages. Use + ``0`` to turn off this check, and always download metadata. :param deltarpm_percentage: When the relative size of delta vs pkg is larger than this, delta - is not used. Use `0` to turn off delta rpm processing. Local - repositories (with file://`baseurl`) have delta rpms turned off by - default. + is not used. Use ``0`` to turn off delta rpm processing. Local + repositories (with file://``baseurl``) have delta rpms turned off + by default. :param 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 `state` is set to `present`. + This parameter is only required if ``state`` is set to ``present``. :param enabled: This tells yum whether or not use this repository. - Yum default value is `true`. + Yum default value is ``true``. :param enablegroups: Determines whether yum will allow the use of package groups for this repository. - Yum default value is `true`. + Yum default value is ``true``. :param exclude: List of packages to exclude from updates or installs. This should be a space separated list. Shell globs using wildcards (for - example `*` and `?`) are allowed. + example ``*`` and ``?``) are allowed. The list can also be a regular YAML array. :param failovermethod: - `roundrobin` randomly selects a URL out of the list of URLs to + ``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. - `priority` starts from the first `baseurl` listed and reads + ``priority`` starts from the first ``baseurl`` listed and reads through them sequentially. :param file: - File name without the `.repo` extension to save the repo in. - Defaults to the value of `name`. + File name without the ``.repo`` extension to save the repo in. + Defaults to the value of ``name``. :param gpgcakey: A URL pointing to the ASCII-armored CA key file for the repository. :param gpgcheck: 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 `/etc/yum.conf` or system default of `false` will be used. + from ``/etc/yum.conf`` or system default of ``false`` will be used. :param gpgkey: A URL pointing to the ASCII-armored GPG key file for the repository. It can also be a list of multiple URLs. :param module_hotfixes: Disable module RPM filtering and make all RPMs from the repository - available. The default is `None`. + available. The default is ``None``. :param http_caching: Determines how upstream HTTP caches are instructed to handle any HTTP downloads that Yum does. - `all` means that all HTTP downloads should be cached. - `packages` means that only RPM package downloads should be cached - (but not repository metadata downloads). - `none` means that no HTTP downloads should be cached. + ``all`` means that all HTTP downloads should be cached. + ``packages`` means that only RPM package downloads should be + cached (but not repository metadata downloads). + ``none`` means that no HTTP downloads should be cached. :param include: Include external configuration file. Both, local path and URL is supported. Configuration file will be inserted at the position of - the `include=` line. Included files may contain further include + the ``include=`` line. Included files may contain further include lines. Yum will abort with an error if an inclusion loop is detected. :param includepkgs: List of packages you want to only use from a repository. This should be a space separated list. Shell globs using wildcards (for - example `*` and `?`) are allowed. Substitution variables (for - example `$releasever`) are honored here. + example ``*`` and ``?``) are allowed. Substitution variables (for + example ``$releasever``) are honored here. The list can also be a regular YAML array. :param ip_resolve: Determines how yum resolves host names. - `4` or `IPv4` - resolve to IPv4 addresses only. - `6` or `IPv6` - resolve to IPv6 addresses only. + ``4`` or ``IPv4`` - resolve to IPv4 addresses only. + ``6`` or ``IPv6`` - resolve to IPv6 addresses only. :param keepalive: This tells yum whether or not HTTP/1.1 keepalive should be used with this repository. This can improve transfer speeds by using one connection when downloading multiple files from a repository. :param keepcache: - Either `1` or `0`. Determines whether or not yum keeps the cache - of headers and packages after successful installation. + Either ``1`` or ``0``. Determines whether or not yum keeps the + cache of headers and packages after successful installation. This parameter is deprecated and will be removed in version 2.20. :param metadata_expire: Time (in seconds) after which the metadata will expire. Default value is 6 hours. :param metadata_expire_filter: - Filter the `metadata_expire` time, allowing a trade of speed for + Filter the ``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". - `never` - Nothing is filtered, always obey `metadata_expire`. - `read-only:past` - Commands that only care about past information - are filtered from metadata expiring. Eg. `yum history` info (if - history needs to lookup anything about a previous transaction, - then by definition the remote package was available in the past). - `read-only:present` - Commands that are balanced between past and - future. Eg. `yum list yum`. - `read-only:future` - Commands that are likely to result in running - other commands which will require the latest metadata. Eg. - `yum check-update`. + ``never`` - Nothing is filtered, always obey ``metadata_expire``. + ``read-only:past`` - Commands that only care about past + information are filtered from metadata expiring. Eg. + ``yum history`` info (if history needs to lookup anything about a + previous transaction, then by definition the remote package was + available in the past). + ``read-only:present`` - Commands that are balanced between past + and future. Eg. ``yum list yum``. + ``read-only:future`` - Commands that are likely to result in + running other commands which will require the latest metadata. Eg. + ``yum check-update``. Note that this option does not override "yum clean expire-cache". :param metalink: 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 `baseurl`. - This, the `baseurl` or `mirrorlist` parameters are required if - `state` is set to `present`. + mirrors for the repomd.xml file to a ``baseurl``. + This, the ``baseurl`` or ``mirrorlist`` parameters are required if + ``state`` is set to ``present``. :param mirrorlist: Specifies a URL to a file containing a list of baseurls. - This, the `baseurl` or `metalink` parameters are required if - `state` is set to `present`. + This, the ``baseurl`` or ``metalink`` parameters are required if + ``state`` is set to ``present``. :param mirrorlist_expire: Time (in seconds) after which the mirrorlist locally cached will expire. @@ -6187,8 +6217,8 @@ def yum_repository( :param name: Unique repository ID. This option builds the section name of the repository in the repo file. - This parameter is only required if `state` is set to `present` or - `absent`. + This parameter is only required if ``state`` is set to ``present`` + or ``absent``. :param password: Password to use with the username for basic authentication. :param priority: @@ -6198,7 +6228,7 @@ def yum_repository( :param protect: Protect packages from updates from other repositories. :param proxy: - URL to the proxy server that yum should use. Set to `_none_` to + URL to the proxy server that yum should use. Set to ``_none_`` to disable the global proxy setting. :param proxy_password: Password for this proxy. @@ -6208,23 +6238,23 @@ def yum_repository( This tells yum whether or not it should perform a GPG signature check on the repodata from this repository. :param reposdir: - Directory where the `.repo` files will be stored. + Directory where the ``.repo`` files will be stored. :param retries: Set the number of times any attempt to retrieve a file should - retry before returning an error. Setting this to `0` makes yum try - forever. + retry before returning an error. Setting this to ``0`` makes yum + try forever. :param s3_enabled: Enables support for S3 repositories. This option only works if the YUM S3 plugin is installed. :param skip_if_unavailable: - If set to `true` yum will continue running if this repository + If set to ``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. :param ssl_check_cert_permissions: 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 - `skip_if_unavailable` to be `true`. This is most useful for + ``skip_if_unavailable`` to be ``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. :param sslcacert: @@ -6248,7 +6278,7 @@ def yum_repository( Number of seconds to wait for a connection before timing out. :param ui_repoid_vars: When a repository id is displayed, append these yum variables to - the string if they are used in the `baseurl`/etc. Variables are + the string if they are used in the ``baseurl``/etc. Variables are appended in the order listed (and found). :param username: Username to use for basic authentication to a repo or really any @@ -6258,23 +6288,23 @@ def yum_repository( For those used to */usr/bin/chmod* remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal - numbers (for example, `'644'` or `'1777'`) so Ansible receives a - string and can do its own conversion from string into number. - Adding a leading zero (for example, `0755`) works sometimes, but + numbers (for example, ``'644'`` or ``'1777'``) so Ansible receives + a string and can do its own conversion from string into number. + Adding a leading zero (for example, ``0755``) works sometimes, but can fail in loops and some other circumstances. Giving Ansible a number without following either 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, `u+rwx` or `u=rw,g=r,o=r`). - If `mode` is not specified and the destination filesystem object - **does not** exist, the default `umask` on the system will be used - when setting the mode for the newly created filesystem object. - If `mode` is not specified and the destination filesystem object + (for example, ``u+rwx`` or ``u=rw,g=r,o=r``). + If ``mode`` is not specified and the destination filesystem object + **does not** exist, the default ``umask`` on the system will be + used when setting the mode for the newly created filesystem object. + If ``mode`` is not specified and the destination filesystem object **does** exist, the mode of the existing filesystem object will be used. - Specifying `mode` is the best way to ensure filesystem objects are - created with the correct permissions. See CVE-2020-1736 for + Specifying ``mode`` is the best way to ensure filesystem objects + are created with the correct permissions. See CVE-2020-1736 for further details. :param owner: Name of the user that should own the filesystem object, as would @@ -6291,21 +6321,21 @@ def yum_repository( previous ownership. :param seuser: The user part of the SELinux filesystem object context. - By default it uses the `system` policy, where applicable. - When set to `_default`, it will use the `user` portion of the + By default it uses the ``system`` policy, where applicable. + When set to ``_default``, it will use the ``user`` portion of the policy if available. :param serole: The role part of the SELinux filesystem object context. - When set to `_default`, it will use the `role` portion of the + When set to ``_default``, it will use the ``role`` portion of the policy if available. :param setype: The type part of the SELinux filesystem object context. - When set to `_default`, it will use the `type` portion of the + When set to ``_default``, it will use the ``type`` portion of the policy if available. :param selevel: The level part of the SELinux filesystem object context. - This is the MLS/MCS attribute, sometimes known as the `range`. - When set to `_default`, it will use the `level` portion of the + This is the MLS/MCS attribute, sometimes known as the ``range``. + When set to ``_default``, it will use the ``level`` portion of the policy if available. :param unsafe_writes: Influence when to use atomic operation to prevent data corruption @@ -6327,7 +6357,7 @@ def yum_repository( target system. This string should contain the attributes in the same order as the one displayed by *lsattr*. - The `=` operator is assumed as default, otherwise `+` or `-` + The ``=`` operator is assumed as default, otherwise ``+`` or ``-`` operators need to be included in the string. """ # noqa: E501 raise AttributeError('yum_repository') @@ -6365,11 +6395,11 @@ def cli_backup( This option provides the path ending with directory name in which the backup configuration file will be stored. If the directory does not exist it will be first created and the filename is either - the value of `filename` or default filename as described in - `filename` options description. If the path value is not given in - that case a *backup* directory will be created in the current + the value of ``filename`` or default filename as described in + ``filename`` options description. If the path value is not given + in that case a *backup* directory will be created in the current working directory and backup configuration will be copied in - `filename` within *backup* directory. + ``filename`` within *backup* directory. """ # noqa: E501 raise AttributeError('cli_backup') @@ -6407,12 +6437,12 @@ def cli_command( The boolean value, that when set to false will send *answer* to the device without a trailing newline. :param check_all: - By default if any one of the prompts mentioned in `prompt` option - is matched it won't check for other prompts. This boolean flag, - that when set to *True* will check for all the prompts mentioned - in `prompt` option in the given order. If the option is set to - *True* all the prompts should be received from remote host if not - it will result in timeout. + By default if any one of the prompts mentioned in ``prompt`` + option is matched it won't check for other prompts. This boolean + flag, that when set to *True* will check for all the prompts + mentioned in ``prompt`` option in the given order. If the option + is set to *True* all the prompts should be received from remote + host if not it will result in timeout. """ # noqa: E501 raise AttributeError('cli_command') @@ -6440,44 +6470,45 @@ def cli_config( :param config: The config to be pushed to the network device. This argument is - mutually exclusive with `rollback` and either one of the option + mutually exclusive with ``rollback`` and either one of the option should be given as input. To ensure idempotency and correct diff the configuration lines should be similar to how they appear if present in the running configuration on device including the indentation. :param commit: - The `commit` argument instructs the module to push the + The ``commit`` argument instructs the module to push the configuration to the device. This is mapped to module check mode. :param replace: - If the `replace` argument is set to `True`, it will replace the - entire running-config of the device with the `config` argument - value. For devices that support replacing running configuration - from file on device like NXOS/JUNOS, the `replace` argument takes - path to the file on the device that will be used for replacing the - entire running-config. The value of `config` option should be - *None* for such devices. Nexus 9K devices only support replace. - Use *net_put* or *nxos_file_copy* in case of NXOS module to copy - the flat file to remote device and then use set the fullpath to - this argument. + If the ``replace`` argument is set to ``True``, it will replace + the entire running-config of the device with the ``config`` + argument value. For devices that support replacing running + configuration from file on device like NXOS/JUNOS, the ``replace`` + argument takes path to the file on the device that will be used + for replacing the entire running-config. The value of ``config`` + option should be *None* for such devices. Nexus 9K devices only + support replace. Use *net_put* or *nxos_file_copy* in case of NXOS + module to copy the flat file to remote device and then use set the + fullpath to this argument. :param backup: This argument will cause the module to create a full backup of the current running config from the remote device before any changes - are made. If the `backup_options` value is not given, the backup - file is written to the `backup` folder in the playbook root + are made. If the ``backup_options`` value is not given, the backup + file is written to the ``backup`` folder in the playbook root directory or role root directory, if playbook is part of an ansible role. If the directory does not exist, it is created. :param rollback: - The `rollback` argument instructs the module to rollback the + The ``rollback`` argument instructs the module to rollback the current configuration to the identifier specified in the argument. If the specified rollback identifier does not exist on the remote device, the module will fail. To rollback to the most recent - commit, set the `rollback` argument to 0. This option is mutually - exclusive with `config`. + commit, set the ``rollback`` argument to 0. This option is + mutually exclusive with ``config``. :param commit_comment: - The `commit_comment` argument specifies a text string to be used - when committing the configuration. If the `commit` argument is set - to False, this argument is silently ignored. This argument is only - valid for the platforms that support commit operation with comment. + The ``commit_comment`` argument specifies a text string to be used + when committing the configuration. If the ``commit`` argument is + set to False, this argument is silently ignored. This argument is + only valid for the platforms that support commit operation with + comment. :param defaults: The *defaults* argument will influence how the running-config is collected from the device. When the value is set to true, the @@ -6491,7 +6522,7 @@ def cli_config( action. :param diff_replace: Instructs the module on the way to perform the configuration on - the device. If the `diff_replace` argument is set to *line* then + the device. If the ``diff_replace`` argument is set to *line* then the modified lines are pushed to the device in configuration mode. If the argument is set to *block* then the entire command block is pushed to the device in configuration mode if any line is not @@ -6499,14 +6530,15 @@ def cli_config( has onbox diff support. :param diff_match: Instructs the module on the way to perform the matching of the set - of commands against the current device config. If `diff_match` is - set to *line*, commands are matched line by line. If `diff_match` - is set to *strict*, command lines are matched with respect to - position. If `diff_match` is set to *exact*, command lines must be - an equal match. Finally, if `diff_match` is set to *none*, the - module will not attempt to compare the source configuration with - the running configuration on the remote device. Note that this - parameter will be ignored if the platform has onbox diff support. + of commands against the current device config. If ``diff_match`` + is set to *line*, commands are matched line by line. If + ``diff_match`` is set to *strict*, command lines are matched with + respect to position. If ``diff_match`` is set to *exact*, command + lines must be an equal match. Finally, if ``diff_match`` is set to + *none*, the module will not attempt to compare the source + configuration with the running configuration on the remote device. + Note that this parameter will be ignored if the platform has onbox + diff support. :param diff_ignore_lines: Use this argument to specify one or more lines that should be ignored during the diff. This is used for lines in the @@ -6517,7 +6549,7 @@ def cli_config( :param backup_options: This is a dict object containing configurable options related to backup file path. The value of this option is read only when - `backup` is set to *True*, if `backup` is set to *False* this + ``backup`` is set to *True*, if ``backup`` is set to *False* this option will be silently ignored. """ # noqa: E501 raise AttributeError('cli_config') @@ -6572,15 +6604,16 @@ def grpc_config( action to be performed. :param backup: This argument will cause the module to create a full backup of the - current `running-config` from the remote device before any changes - are made. If the `backup_options` value is not given, the backup - file is written to the `backup` folder in the playbook root - directory or role root directory, if playbook is part of an - ansible role. If the directory does not exist, it is created. + current ``running-config`` from the remote device before any + changes are made. If the ``backup_options`` value is not given, + the backup file is written to the ``backup`` folder in the + playbook root directory or role root directory, if playbook is + part of an ansible role. If the directory does not exist, it is + created. :param backup_options: This is a dict object containing configurable options related to backup file path. The value of this option is read only when - `backup` is set to *True*, if `backup` is set to *False* this + ``backup`` is set to *True*, if ``backup`` is set to *False* this option will be silently ignored. """ # noqa: E501 raise AttributeError('grpc_config') @@ -6750,7 +6783,7 @@ def netconf_config( onto the remote host. In case the value of this option isn *text* format the format should be supported by remote Netconf server. - If the value of `content` option is in *xml* format in that case + If the value of ``content`` option is in *xml* format in that case the xml value should have *config* as root tag. :param target: Name of the configuration datastore to be edited. - auto, uses @@ -6759,41 +6792,41 @@ def netconf_config( directly. :param source_datastore: Name of the configuration datastore to use as the source to copy - the configuration to the datastore mentioned by `target` option. + the configuration to the datastore mentioned by ``target`` option. The values can be either *running*, *candidate*, *startup* or a remote URL. :param format: - The format of the configuration provided as value of `content`. + The format of the configuration provided as value of ``content``. In case of json string format it will be converted to the corresponding xml string using xmltodict library before pushing onto the remote host. In case of *text* format of the configuration should be supported by remote Netconf server. - If the value of `format` options is not given it tries to guess - the data format of `content` option as one of *xml* or *json* or + If the value of ``format`` options is not given it tries to guess + the data format of ``content`` option as one of *xml* or *json* or *text*. If the data format is not identified it is set to *xml* by default. :param lock: Instructs the module to explicitly lock the datastore specified as - `target`. By setting the option value *always* is will explicitly - lock the datastore mentioned in `target` option. It the value is - *never* it will not lock the `target` datastore. The value - *if-supported* lock the `target` datastore only if it is supported - by the remote Netconf server. + ``target``. By setting the option value *always* is will + explicitly lock the datastore mentioned in ``target`` option. It + the value is *never* it will not lock the ``target`` datastore. + The value *if-supported* lock the ``target`` datastore only if it + is supported by the remote Netconf server. :param default_operation: The default operation for rpc, valid values are *merge*, *replace* and *none*. If the default value is merge, the - configuration data in the `content` option is merged at the - corresponding level in the `target` datastore. If the value is - replace the data in the `content` option completely replaces the - configuration in the `target` datastore. If the value is none the - `target` datastore is unaffected by the configuration in the + configuration data in the ``content`` option is merged at the + corresponding level in the ``target`` datastore. If the value is + replace the data in the ``content`` option completely replaces the + configuration in the ``target`` datastore. If the value is none + the ``target`` datastore is unaffected by the configuration in the config option, unless and until the incoming configuration data - uses the `operation` operation to request a different operation. + uses the ``operation`` operation to request a different operation. :param confirm: This argument will configure a timeout value for the commit to be confirmed before it is automatically rolled back. If the - `confirm_commit` argument is set to False, this argument is + ``confirm_commit`` argument is set to False, this argument is silently ignored. If the value of this argument is set to 0, the commit is confirmed immediately. The remote host MUST support :candidate and :confirmed-commit capability for this option to . @@ -6813,19 +6846,20 @@ def netconf_config( Netconf server to support the *error_option=rollback-on-error* capability. :param save: - The `save` argument instructs the module to save the configuration - in `target` datastore to the startup-config if changed and if - :startup capability is supported by Netconf server. + The ``save`` argument instructs the module to save the + configuration in ``target`` datastore to the startup-config if + changed and if :startup capability is supported by Netconf server. :param backup: This argument will cause the module to create a full backup of the - current `running-config` from the remote device before any changes - are made. If the `backup_options` value is not given, the backup - file is written to the `backup` folder in the playbook root - directory or role root directory, if playbook is part of an - ansible role. If the directory does not exist, it is created. + current ``running-config`` from the remote device before any + changes are made. If the ``backup_options`` value is not given, + the backup file is written to the ``backup`` folder in the + playbook root directory or role root directory, if playbook is + part of an ansible role. If the directory does not exist, it is + created. :param delete: It instructs the module to delete the configuration from value - mentioned in `target` datastore. + mentioned in ``target`` datastore. :param commit: This boolean flag controls if the configuration changes should be committed or not after editing the candidate datastore. This @@ -6835,12 +6869,12 @@ def netconf_config( commit or discard-changes explicitly. :param validate: This boolean flag if set validates the content of datastore given - in `target` option. For this option to work remote Netconf server - should support :validate capability. + in ``target`` option. For this option to work remote Netconf + server should support :validate capability. :param backup_options: This is a dict object containing configurable options related to backup file path. The value of this option is read only when - `backup` is set to *True*, if `backup` is set to *False* this + ``backup`` is set to *True*, if ``backup`` is set to *False* this option will be silently ignored. :param get_filter: This argument specifies the XML string which acts as a filter to @@ -6848,10 +6882,11 @@ def netconf_config( when comparing the before and after state of the device following calls to edit_config. When not specified, the entire configuration or state data is returned for comparison depending on the value of - `source` option. The `get_filter` value can be either XML string - or XPath or JSON string or native python dictionary, if the filter - is in XPath format the NETCONF server running on remote host - should support xpath capability else it will result in an error. + ``source`` option. The ``get_filter`` value can be either XML + string or XPath or JSON string or native python dictionary, if the + filter is in XPath format the NETCONF server running on remote + host should support xpath capability else it will result in an + error. """ # noqa: E501 raise AttributeError('netconf_config') @@ -6872,15 +6907,15 @@ def netconf_get( :param source: This argument specifies the datastore from which configuration data should be fetched. Valid values are *running*, *candidate* - and *startup*. If the `source` value is not set both configuration - and state information are returned in response from running - datastore. + and *startup*. If the ``source`` value is not set both + configuration and state information are returned in response from + running datastore. :param filter: This argument specifies the string which acts as a filter to restrict the portions of the data to be are retrieved from the remote device. If this option is not specified entire configuration or state data is returned in result depending on the - value of `source` option. The `filter` value can be either XML + value of ``source`` option. The ``filter`` value can be either XML string or XPath or JSON string or native python dictionary, if the filter is in XPath format the NETCONF server running on remote host should support xpath capability else it will result in an @@ -6896,13 +6931,13 @@ def netconf_get( removes all XML namespaces. :param lock: Instructs the module to explicitly lock the datastore specified as - `source`. If no *source* is defined, the *running* datastore will - be locked. By setting the option value *always* is will explicitly - lock the datastore mentioned in `source` option. By setting the - option value *never* it will not lock the `source` datastore. The - value *if-supported* allows better interworking with NETCONF - servers, which do not support the (un)lock operation for all - supported datastores. + ``source``. If no *source* is defined, the *running* datastore + will be locked. By setting the option value *always* is will + explicitly lock the datastore mentioned in ``source`` option. By + setting the option value *never* it will not lock the ``source`` + datastore. The value *if-supported* allows better interworking + with NETCONF servers, which do not support the (un)lock operation + for all supported datastores. """ # noqa: E501 raise AttributeError('netconf_get') @@ -6979,7 +7014,7 @@ def network_resource( The value of this option should be the output received from the host device by executing the cli command to get the resource configuration on host. - The state *parsed* reads the configuration from `running_config` + The state *parsed* reads the configuration from ``running_config`` option and transforms it into Ansible structured data as per the resource module's argspec and the value is then returned in the *parsed* key within the result. @@ -7008,8 +7043,8 @@ def restconf_config( :param path: URI being used to execute API calls. :param content: - The configuration data in format as specififed in `format` option. - Required unless `method` is *delete*. + The configuration data in format as specififed in ``format`` + option. Required unless ``method`` is *delete*. :param method: The RESTCONF method to manage the configuration change on device. The value *post* is used to create a data resource or invoke an @@ -7017,7 +7052,7 @@ def restconf_config( resource, *patch* is used to modify the target resource, and *delete* is used to delete the target resource. :param format: - The format of the configuration provided as value of `content`. + The format of the configuration provided as value of ``content``. Accepted values are *xml* and *json* and the given configuration format should be supported by remote RESTCONF server. """ # noqa: E501 @@ -7039,13 +7074,13 @@ def restconf_get( :param path: URI being used to execute API calls. :param content: - The `content` is a query parameter that controls how descendant - nodes of the requested data nodes in `path` will be processed in + The ``content`` is a query parameter that controls how descendant + nodes of the requested data nodes in ``path`` will be processed in the reply. If value is *config* return only configuration - descendant data nodes of value in `path`. If value is *nonconfig* - return only non-configuration descendant data nodes of value in - `path`. If value is *all* return all descendant data nodes of - value in `path`. + descendant data nodes of value in ``path``. If value is + *nonconfig* return only non-configuration descendant data nodes of + value in ``path``. If value is *all* return all descendant data + nodes of value in ``path``. :param output: The output of response received. """ # noqa: E501 @@ -7131,47 +7166,48 @@ def acl( The full path of the file or object. :param state: Define whether the ACL should be present or not. - The `query` state gets the current ACL without changing it, for - use in `register` operations. + The ``query`` state gets the current ACL without changing it, for + use in ``register`` operations. :param follow: Whether to follow symlinks on the path if a symlink is encountered. :param default: - If the target is a directory, setting this to `true` will make it - the default ACL for entities created inside the directory. - Setting `default` to `true` causes an error if the path is a file. + If the target is a directory, setting this to ``true`` will make + it the default ACL for entities created inside the directory. + Setting ``default`` to ``true`` causes an error if the path is a + file. :param entity: The actual user or group that the ACL applies to when matching entity types user or group are selected. :param etype: - The entity type of the ACL to apply, see `setfacl` documentation + The entity type of the ACL to apply, see ``setfacl`` documentation for more info. :param permissions: - The permissions to apply/remove can be any combination of `r`, - `w`, `x`. - (read, write and execute respectively), and `X` (execute + The permissions to apply/remove can be any combination of ``r``, + ``w``, ``x``. + (read, write and execute respectively), and ``X`` (execute permission if the file is a directory or already has execute permission for some user). :param entry: DEPRECATED. The ACL to set or remove. This must always be quoted in the form of - `::`. + ``::``. The qualifier may be empty for some types, but the type and perms are always required. - `-` can be used as placeholder when you do not care about + ``-`` can be used as placeholder when you do not care about permissions. This is now superseded by entity, type and permissions fields. :param recursive: Recursively sets the specified ACL. - Incompatible with `state=query`. - Alias `recurse` added in version 1.3.0. + Incompatible with ``state=query``. + Alias ``recurse`` added in version 1.3.0. :param use_nfsv4_acls: Use NFSv4 ACLs instead of POSIX ACLs. :param recalculate_mask: Select if and when to recalculate the effective right masks of the files. - See `setfacl` documentation for more info. - Incompatible with `state=query`. + See ``setfacl`` documentation for more info. + Incompatible with ``state=query``. """ raise AttributeError('acl') @@ -7241,11 +7277,11 @@ def authorized_key( :param manage_dir: Whether this module should manage the directory of the authorized key file. - If set to `true`, the module will create the directory, as well as - set the owner and permissions of an existing directory. - Be sure to set `manage_dir=false` if you are using an alternate - directory for authorized_keys, as set with `path`, since you could - lock yourself out of SSH access. + If set to ``true``, the module will create the directory, as well + as set the owner and permissions of an existing directory. + Be sure to set ``manage_dir=false`` if you are using an alternate + directory for authorized_keys, as set with ``path``, since you + could lock yourself out of SSH access. See the example below. :param state: Whether the given key (with the given key_options) should or @@ -7256,19 +7292,19 @@ def authorized_key( :param exclusive: Whether to remove all other non-specified keys from the authorized_keys file. - Multiple keys can be specified in a single `key` string value by + Multiple keys can be specified in a single ``key`` string value by separating them by newlines. - This option is not loop aware, so if you use `with_` , it will be - exclusive per iteration of the loop. + This option is not loop aware, so if you use ``with_`` , it will + be exclusive per iteration of the loop. If you want multiple keys in the file you need to pass them all to - `key` in a single batch as mentioned above. + ``key`` in a single batch as mentioned above. :param validate_certs: This only applies if using a https url as the source of the keys. - If set to `false`, the SSL certificates will not be validated. - This should only set to `false` used on personally controlled + If set to ``false``, the SSL certificates will not be validated. + This should only set to ``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 `true`. + Prior to 2.1 the code worked as if this was set to ``true``. :param comment: Change the comment on the public key. Rewriting the comment is useful in cases such as fetching it from @@ -7345,17 +7381,18 @@ def firewalld( :param zone: The firewalld zone to add/remove to/from. Note that the default zone can be configured per system but - `public` is default from upstream. + ``public`` is default from upstream. Available choices can be extended based on per-system configs, listed here are "out of the box" defaults. - Possible values include `block`, `dmz`, `drop`, `external`, - `home`, `internal`, `public`, `trusted`, `work`. + Possible values include ``block``, ``dmz``, ``drop``, + ``external``, ``home``, ``internal``, ``public``, ``trusted``, + ``work``. :param permanent: Should this configuration be in the running firewalld configuration or persist across reboots. As of Ansible 2.3, permanent operations can operate on firewalld configs when it is not running (requires firewalld >= 0.3.9). - Note that if this is `false`, immediate is assumed `true`. + Note that if this is ``false``, immediate is assumed ``true``. :param immediate: Should this configuration be applied immediately, if set as permanent. @@ -7363,9 +7400,9 @@ def firewalld( Enable or disable a setting. For ports: Should this port accept (enabled) or reject (disabled) connections. - The states `present` and `absent` can only be used in zone level - operations (i.e. when no other parameters but zone and state are - set). + The states ``present`` and ``absent`` can only be used in zone + level operations (i.e. when no other parameters but zone and state + are set). :param timeout: The amount of time in seconds the rule should be in effect for when non-permanent. @@ -7376,7 +7413,8 @@ def firewalld( Whether to run this module even when firewalld is offline. :param target: firewalld Zone target. - If state is set to `absent`, this will reset the target to default. + If state is set to ``absent``, this will reset the target to + default. """ # noqa: E501 raise AttributeError('firewalld') @@ -7396,7 +7434,7 @@ def firewalld_info( Gather information about active zones. :param zones: Gather information about specific zones. - If only works if `active_zones` is set to `false`. + If only works if ``active_zones`` is set to ``false``. """ # noqa: E501 raise AttributeError('firewalld_info') @@ -7429,39 +7467,40 @@ def mount( :ref:`ansible.posix ` :param path: - Path to the mount point (e.g. `/mnt/files`). + Path to the mount point (e.g. ``/mnt/files``). Before Ansible 2.3 this option was only usable as *dest*, *destfile* and *name*. :param src: Device (or NFS volume, or something else) to be mounted on *path*. - Required when *state* set to `present`, `mounted` or `ephemeral`. + Required when *state* set to ``present``, ``mounted`` or + ``ephemeral``. :param fstype: Filesystem type. - Required when *state* is `present`, `mounted` or `ephemeral`. + Required when *state* is ``present``, ``mounted`` or ``ephemeral``. :param opts: Mount options (see fstab(5), or vfstab(4) on Solaris). :param dump: Dump (see fstab(5)). - Note that if set to `null` and *state* set to `present`, it will - cease to work and duplicate entries will be made with subsequent - runs. - Has no effect on Solaris systems or when used with `ephemeral`. + Note that if set to ``null`` and *state* set to ``present``, it + will cease to work and duplicate entries will be made with + subsequent runs. + Has no effect on Solaris systems or when used with ``ephemeral``. :param passno: Passno (see fstab(5)). - Note that if set to `null` and *state* set to `present`, it will - cease to work and duplicate entries will be made with subsequent - runs. + Note that if set to ``null`` and *state* set to ``present``, it + will cease to work and duplicate entries will be made with + subsequent runs. Deprecated on Solaris systems. Has no effect when used with - `ephemeral`. + ``ephemeral``. :param state: - If `mounted`, the device will be actively mounted and + If ``mounted``, the device will be actively mounted and appropriately configured in *fstab*. If the mount point is not present, the mount point will be created. - If `unmounted`, the device will be unmounted without changing + If ``unmounted``, the device will be unmounted without changing *fstab*. - `present` only specifies that the device is to be configured in + ``present`` only specifies that the device is to be configured in *fstab* and does not trigger or require a mount. - `ephemeral` only specifies that the device is to be mounted, + ``ephemeral`` only specifies that the device is to be mounted, without changing *fstab*. If it is already mounted, a remount will be triggered. This will always return changed=True. If the mount point *path* has already a device mounted on, and its source is @@ -7469,24 +7508,24 @@ def mount( unmount or mount point override. If the mount point is not present, the mount point will be created. The *fstab* is completely ignored. This option is added in version 1.5.0. - `absent` specifies that the device mount's entry will be removed + ``absent`` specifies that the device mount's entry will be removed from *fstab* and will also unmount the device and remove the mount point. - `remounted` specifies that the device will be remounted for when + ``remounted`` specifies that the device will be remounted for when you want to force a refresh on the mount itself (added in 2.9). This will always return changed=true. If *opts* is set, the options will be applied to the remount, but will not change *fstab*. Additionally, if *opts* is set, and the remount command fails, the module will error to prevent unexpected mount changes. - Try using `mounted` instead to work around this issue. `remounted` - expects the mount point to be present in the *fstab*. To remount a - mount point not registered in *fstab*, use `ephemeral` instead, - especially with BSD nodes. - `absent_from_fstab` specifies that the device mount's entry will + Try using ``mounted`` instead to work around this issue. + ``remounted`` expects the mount point to be present in the + *fstab*. To remount a mount point not registered in *fstab*, use + ``ephemeral`` instead, especially with BSD nodes. + ``absent_from_fstab`` specifies that the device mount's entry will be removed from *fstab*. This option does not unmount it or delete the mountpoint. :param fstab: - File to use instead of `/etc/fstab`. + File to use instead of ``/etc/fstab``. You should not use this option unless you really know what you are doing. This might be useful if you need to configure mountpoints in a @@ -7495,17 +7534,17 @@ def mount( so do not use this on OpenBSD with any state that operates on the live filesystem. This parameter defaults to /etc/fstab or /etc/vfstab on Solaris. - This parameter is ignored when *state* is set to `ephemeral`. + This parameter is ignored when *state* is set to ``ephemeral``. :param boot: Determines if the filesystem should be mounted on boot. Only applies to Solaris and Linux systems. - For Solaris systems, `true` will set `True` as the value of mount - at boot in */etc/vfstab*. - For Linux, FreeBSD, NetBSD and OpenBSD systems, `false` will add - `noauto` to mount options in */etc/fstab*. - To avoid mount option conflicts, if `noauto` specified in `opts`, - mount module will ignore `boot`. - This parameter is ignored when *state* is set to `ephemeral`. + For Solaris systems, ``true`` will set ``True`` as the value of + mount at boot in */etc/vfstab*. + For Linux, FreeBSD, NetBSD and OpenBSD systems, ``false`` will add + ``noauto`` to mount options in */etc/fstab*. + To avoid mount option conflicts, if ``noauto`` specified in + ``opts``, mount module will ignore ``boot``. + This parameter is ignored when *state* is set to ``ephemeral``. :param backup: Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it @@ -7534,7 +7573,8 @@ def patch( :param basedir: Path of a base directory in which the patch file will be applied. - May be omitted when `dest` option is specified, otherwise required. + May be omitted when ``dest`` option is specified, otherwise + required. :param dest: Path of the file on the remote machine to be patched. The names of the files to be patched are usually taken from the @@ -7542,30 +7582,30 @@ def patch( specified with this option. :param src: Path of the patch file as accepted by the GNU patch tool. If - `remote_src` is `false`, the patch source file is looked up from - the module's *files* directory. + ``remote_src`` is ``false``, the patch source file is looked up + from the module's *files* directory. :param state: Whether the patch should be applied or reverted. :param remote_src: - If `false`, it will search for src at originating/controller - machine, if `true` it will go to the remote/target machine for the - `src`. + If ``false``, it will search for src at originating/controller + machine, if ``true`` it will go to the remote/target machine for + the ``src``. :param strip: Number that indicates the smallest prefix containing leading slashes that will be stripped from each file name found in the patch file. For more information see the strip parameter of the GNU patch tool. :param backup: - Passes `--backup --version-control=numbered` to patch, producing + Passes ``--backup --version-control=numbered`` to patch, producing numbered backup copies. :param binary: - Setting to `true` will disable patch's heuristic for transforming - CRLF line endings into LF. + Setting to ``true`` will disable patch's heuristic for + transforming CRLF line endings into LF. Line endings of src and dest must match. - If set to `false`, `patch` will replace CRLF in `src` files on - POSIX. + If set to ``false``, ``patch`` will replace CRLF in ``src`` files + on POSIX. :param ignore_whitespace: - Setting to `true` will ignore white space changes between patch + Setting to ``true`` will ignore white space changes between patch and input. """ # noqa: E501 raise AttributeError('patch') @@ -7598,29 +7638,30 @@ def rhel_rpm_ostree( :ref:`ansible.posix ` :param name: - A package name or package specifier with version, like `name-1.0`. - Comparison operators for package version are valid here `>`, `<`, - `>=`, `<=`. Example - `name>=1.0`. + A package name or package specifier with version, like + ``name-1.0``. + Comparison operators for package version are valid here ``>``, + ``<``, ``>=``, ``<=``. Example - ``name>=1.0``. If a previous version is specified, the task also needs to turn - `allow_downgrade` on. See the `allow_downgrade` documentation for - caveats with downgrading packages. - When using state=latest, this can be `'*'` which means run - `yum -y update`. + ``allow_downgrade`` on. See the ``allow_downgrade`` documentation + for caveats with downgrading packages. + When using state=latest, this can be ``'*'`` which means run + ``yum -y update``. You can also pass a url or a local path to a rpm file (using 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. :param state: - Whether to install (`present` or `installed`, `latest`), or remove - (`absent` or `removed`) a package. - `present` and `installed` will simply ensure that a desired + Whether to install (``present`` or ``installed``, ``latest``), or + remove (``absent`` or ``removed``) a package. + ``present`` and ``installed`` will simply ensure that a desired package is installed. - `latest` will update the specified package if it's not of the + ``latest`` will update the specified package if it's not of the latest available version. - `absent` and `removed` will remove the specified package. - Default is `None`, however in effect the default action is - `present` unless the `autoremove` option is enabled for this - module, then `absent` is inferred. + ``absent`` and ``removed`` will remove the specified package. + Default is ``None``, however in effect the default action is + ``present`` unless the ``autoremove`` option is enabled for this + module, then ``absent`` is inferred. """ # noqa: E501 raise AttributeError('rhel_rpm_ostree') @@ -7668,7 +7709,7 @@ def seboolean( :param name: Name of the boolean to configure. :param persistent: - Set to `true` if the boolean setting should survive a reboot. + Set to ``true`` if the boolean setting should survive a reboot. :param state: Desired boolean value. :param ignore_selinux_state: @@ -7696,15 +7737,15 @@ def selinux( :ref:`ansible.posix ` :param policy: - The name of the SELinux policy to use (e.g. `targeted`) will be - required if *state* is not `disabled`. + The name of the SELinux policy to use (e.g. ``targeted``) will be + required if *state* is not ``disabled``. :param state: The SELinux mode. :param update_kernel_param: If set to *true*, will update also the kernel boot parameters when disabling/enabling SELinux. - The `grubby` tool must be present on the target system for this to - work. + The ``grubby`` tool must be present on the target system for this + to work. :param configfile: The path to the SELinux configuration file, if non-standard. """ # noqa: E501 @@ -7761,8 +7802,8 @@ def synchronize( Port number for ssh on the destination host. Prior to Ansible 2.0, the ansible_ssh_port inventory var took precedence over this value. - This parameter defaults to the value of `ansible_port`, the - `remote_port` config setting or the value from ssh client + This parameter defaults to the value of ``ansible_port``, the + ``remote_port`` config setting or the value from ssh client configuration if none of the former have been set. :param mode: Specify the direction of the synchronization. @@ -7785,7 +7826,7 @@ def synchronize( before) in the *src* path. This option requires *recursive=true*. This option ignores excluded files and behaves like the rsync opt - `--delete-after`. + ``--delete-after``. :param dirs: Transfer directories without recursing. :param recursive: @@ -7811,37 +7852,37 @@ def synchronize( This parameter defaults to the value of the archive option. :param rsync_path: Specify the rsync command to run on the remote host. See - `--rsync-path` on the rsync man page. + ``--rsync-path`` on the rsync man page. To specify the rsync command to run on the local host, you need to - set this your task var `ansible_rsync_path`. + set this your task var ``ansible_rsync_path``. :param rsync_timeout: - Specify a `--timeout` for the rsync command in seconds. + Specify a ``--timeout`` for the rsync command in seconds. :param set_remote_user: Put user@ for the remote paths. If you have a custom ssh config to define the remote user for a host that does not match the inventory user, you should set this - parameter to `false`. + parameter to ``false``. :param use_ssh_args: In Ansible 2.10 and lower, it uses the ssh_args specified in - `ansible.cfg`. - In Ansible 2.11 and onwards, when set to `true`, it uses all SSH - connection configurations like `ansible_ssh_args`, - `ansible_ssh_common_args`, and `ansible_ssh_extra_args`. + ``ansible.cfg``. + In Ansible 2.11 and onwards, when set to ``true``, it uses all SSH + connection configurations like ``ansible_ssh_args``, + ``ansible_ssh_common_args``, and ``ansible_ssh_extra_args``. :param ssh_connection_multiplexing: SSH connection multiplexing for rsync is disabled by default to prevent misconfigured ControlSockets from resulting in failed SSH connections. This is accomplished by setting the SSH - `ControlSocket` to `none`. - Set this option to `true` to allow multiplexing and reduce SSH + ``ControlSocket`` to ``none``. + Set this option to ``true`` to allow multiplexing and reduce SSH connection overhead. - Note that simply setting this option to `true` is not enough; You - must also configure SSH connection multiplexing in your SSH client - config by setting values for `ControlMaster`, `ControlPersist` and - `ControlPath`. + Note that simply setting this option to ``true`` is not enough; + You must also configure SSH connection multiplexing in your SSH + client config by setting values for ``ControlMaster``, + ``ControlPersist`` and ``ControlPath``. :param rsync_opts: Specify additional rsync options by passing in an array. - Note that an empty string in `rsync_opts` will end up transfer the - current working directory. + Note that an empty string in ``rsync_opts`` will end up transfer + the current working directory. :param partial: Tells rsync to keep the partial file which should make a subsequent transfer of the rest of the file much faster. @@ -7849,7 +7890,7 @@ def synchronize( Verify destination host key. :param private_key: Specify the private key to use for SSH-based rsync connections - (e.g. `~/.ssh/id_rsa`). + (e.g. ``~/.ssh/id_rsa``). :param link_dest: Add a destination to hard link against during the rsync. :param delay_updates: @@ -7886,12 +7927,12 @@ def sysctl( :param ignoreerrors: Use this option to ignore errors about unknown keys. :param reload: - If `true`, performs a */sbin/sysctl -p* if the `sysctl_file` is - updated. If `false`, does not reload *sysctl* even if the - `sysctl_file` is updated. + If ``true``, performs a */sbin/sysctl -p* if the ``sysctl_file`` + is updated. If ``false``, does not reload *sysctl* even if the + ``sysctl_file`` is updated. :param sysctl_file: - Specifies the absolute path to `sysctl.conf`, if not - `/etc/sysctl.conf`. + Specifies the absolute path to ``sysctl.conf``, if not + ``/etc/sysctl.conf``. :param sysctl_set: Verify token value with the sysctl command and set with -w if necessary. @@ -8026,29 +8067,29 @@ def win_acl( User or Group to add specified rights to act on src file/folder or registry key. :param state: - Specify whether to add `present` or remove `absent` the specified - access rule. + Specify whether to add ``present`` or remove ``absent`` the + specified access rule. :param type: Specify whether to allow or deny the rights specified. :param rights: The rights/permissions that are to be allowed/denied for the - specified user or group for the item at `path`. - If `path` is a file or directory, rights can be any right under + specified user or group for the item at ``path``. + If ``path`` is a file or directory, rights can be any right under MSDN FileSystemRights `reference `__. - If `path` is a registry key, rights can be any right under MSDN + If ``path`` is a registry key, rights can be any right under MSDN RegistryRights `reference `__. - If *path* is a certificate key, rights can be `Read` and/or - `FullControl`. (Added in 2.2.0). + If *path* is a certificate key, rights can be ``Read`` and/or + ``FullControl``. (Added in 2.2.0). :param inherit: Inherit flags on the ACL rules. Can be specified as a comma separated list, e.g. - `ContainerInherit`, `ObjectInherit`. + ``ContainerInherit``, ``ObjectInherit``. For more information on the choices see MSDN InheritanceFlags enumeration at `reference `__. - Defaults to `ContainerInherit, ObjectInherit` for Directories. + Defaults to ``ContainerInherit, ObjectInherit`` for Directories. :param propagation: Propagation flag on the ACL rules. For more information on the choices see MSDN PropagationFlags @@ -8076,16 +8117,16 @@ def win_acl_inheritance( :param path: Path to be used for changing inheritance. Support for registry keys have been added in - `ansible.windows>=1.11.0`. + ``ansible.windows>=1.11.0``. :param state: Specify whether to enable *present* or disable *absent* ACL inheritance. :param reorganize: - For `state=absent`, indicates if the inherited ACE's should be + For ``state=absent``, indicates if the inherited ACE's should be copied from the parent. This is necessary (in combination with removal) for a simple ACL instead of using multiple ACE deny entries. - For `state=present`, indicates if the inherited ACE's should be + For ``state=present``, indicates if the inherited ACE's should be deduplicated compared to the parent. This removes complexity of the ACL structure. """ # noqa: E501 @@ -8112,19 +8153,19 @@ def win_certificate_store( :ref:`ansible.windows ` :param state: - If `present`, will ensure that the certificate at *path* is + If ``present``, will ensure that the certificate at *path* is imported into the certificate store specified. - If `absent`, will ensure that the certificate specified by + If ``absent``, will ensure that the certificate specified by *thumbprint* or the thumbprint of the cert at *path* is removed from the store specified. - If `exported`, will ensure the file at *path* is a certificate + If ``exported``, will ensure the file at *path* is a certificate specified by *thumbprint*. When exporting a certificate, if *path* is a directory then the module will fail, otherwise the file will be replaced if needed. :param path: The path to a certificate file. - This is required when *state* is `present` or `exported`. - When *state* is `absent` and *thumbprint* is not specified, the + This is required when *state* is ``present`` or ``exported``. + When *state* is ``absent`` and *thumbprint* is not specified, the thumbprint is derived from the certificate at this path. :param thumbprint: The thumbprint as a hex string to either export or remove. @@ -8132,63 +8173,65 @@ def win_certificate_store( :param store_name: The store name to use when importing a certificate or searching for a certificate. - `AddressBook`: The X.509 certificate store for other users. - `AuthRoot`: The X.509 certificate store for third-party + ``AddressBook``: The X.509 certificate store for other users. + ``AuthRoot``: The X.509 certificate store for third-party certificate authorities (CAs). - `CertificateAuthority`: The X.509 certificate store for + ``CertificateAuthority``: The X.509 certificate store for intermediate certificate authorities (CAs). - `Disallowed`: The X.509 certificate store for revoked certificates. - `My`: The X.509 certificate store for personal certificates. - `Root`: The X.509 certificate store for trusted root certificate + ``Disallowed``: The X.509 certificate store for revoked + certificates. + ``My``: The X.509 certificate store for personal certificates. + ``Root``: The X.509 certificate store for trusted root certificate authorities (CAs). - `TrustedPeople`: The X.509 certificate store for directly trusted - people and resources. - `TrustedPublisher`: The X.509 certificate store for directly + ``TrustedPeople``: The X.509 certificate store for directly + trusted people and resources. + ``TrustedPublisher``: The X.509 certificate store for directly trusted publishers. :param store_location: The store location to use when importing a certificate or searching for a certificate. - Can be set to `CurrentUser` or `LocalMachine` when - `store_type=system`. - Defaults to `LocalMachine` when `store_type=system`. - Must be set to any service name when `store_type=service`. + Can be set to ``CurrentUser`` or ``LocalMachine`` when + ``store_type=system``. + Defaults to ``LocalMachine`` when ``store_type=system``. + Must be set to any service name when ``store_type=service``. :param store_type: The store type to manage. - Use `system` to manage locations in the system store, - `LocalMachine` and `CurrentUser`. - Use `service` to manage the store of a service account specified + Use ``system`` to manage locations in the system store, + ``LocalMachine`` and ``CurrentUser``. + Use ``service`` to manage the store of a service account specified by *store_location*. :param password: The password of the pkcs12 certificate key. This is used when reading a pkcs12 certificate file or the - password to set when `state=exported` and `file_type=pkcs12`. + password to set when ``state=exported`` and ``file_type=pkcs12``. If the pkcs12 file has no password set or no password should be set on the exported file, do not set this option. :param key_exportable: Whether to allow the private key to be exported. - If `false`, then this module and other process will only be able + If ``false``, then this module and other process will only be able to export the certificate and the private key cannot be exported. - Used when `state=present` only. + Used when ``state=present`` only. :param key_storage: Specifies where Windows will store the private key when it is imported. - When set to `default`, the default option as set by Windows is - used, typically `user`. - When set to `machine`, the key is stored in a path accessible by + When set to ``default``, the default option as set by Windows is + used, typically ``user``. + When set to ``machine``, the key is stored in a path accessible by various users. - When set to `user`, the key is stored in a path only accessible by - the current user. - Used when `state=present` only and cannot be changed once imported. + When set to ``user``, the key is stored in a path only accessible + by the current user. + Used when ``state=present`` only and cannot be changed once + imported. See `reference `__ for more details. :param file_type: - The file type to export the certificate as when `state=exported`. - `der` is a binary ASN.1 encoded file. - `pem` is a base64 encoded file of a der file in the OpenSSL form. - `pkcs12` (also known as pfx) is a binary container that contains + The file type to export the certificate as when ``state=exported``. + ``der`` is a binary ASN.1 encoded file. + ``pem`` is a base64 encoded file of a der file in the OpenSSL form. + ``pkcs12`` (also known as pfx) is a binary container that contains both the certificate and private key unlike the other options. - When `pkcs12` is set and the private key is not exportable or + When ``pkcs12`` is set and the private key is not exportable or accessible by the current user, it will throw an exception. """ # noqa: E501 raise AttributeError('win_certificate_store') @@ -8212,13 +8255,13 @@ def win_command( :ref:`ansible.windows ` :param _raw_params: - The `win_command` module takes a free form command to run. - This is mutually exclusive with the `cmd` and `argv` options. + The ``win_command`` module takes a free form command to run. + This is mutually exclusive with the ``cmd`` and ``argv`` options. There is no parameter actually named '_raw_params'. See the examples!. :param cmd: The command and arguments to run. - This is mutually exclusive with the `_raw_params` and `argv` + This is mutually exclusive with the ``_raw_params`` and ``argv`` options. :param argv: A list that contains the executable and arguments to run. @@ -8226,7 +8269,7 @@ def win_command( the `Win32 C command-line argument rules `__. Not all applications use the same quoting rules so the escaping - may not work, for those scenarios use `cmd` instead. + may not work, for those scenarios use ``cmd`` instead. :param creates: A path or path filter pattern; when the referenced path exists on the target host, the task will be skipped. @@ -8243,8 +8286,8 @@ def win_command( You can use this option when you need to run a command which ignore the console's codepage. You should only need to use this option in very rare circumstances. - This value can be any valid encoding `Name` based on the output of - `[System.Text.Encoding]::GetEncodings(`). See + This value can be any valid encoding ``Name`` based on the output + of ``[System.Text.Encoding]::GetEncodings(``). See `reference `__. """ # noqa: E501 raise AttributeError('win_command') @@ -8268,56 +8311,56 @@ def win_copy( :ref:`ansible.windows ` :param content: - When used instead of `src`, sets the contents of a file directly + When used instead of ``src``, sets the contents of a file directly to the specified value. This is for simple values, for anything complex or with formatting - please switch to the :meth:`ansible.windows.win_template` module. + please switch to the :meth:`win_template` module. :param decrypt: This option controls the autodecryption of source files using vault. :param dest: Remote absolute path where the file should be copied to. - If `src` is a directory, this must be a directory too. + If ``src`` is a directory, this must be a directory too. Use \\ for path separators or \\\\ when in "double quotes". - If `dest` ends with \\ then source or the contents of source will - be copied to the directory without renaming. - If `dest` is a nonexistent path, it will only be created if `dest` - ends with "/" or "\\", or `src` is a directory. - If `src` and `dest` are files and if the parent directory of - `dest` doesn't exist, then the task will fail. + If ``dest`` ends with \\ then source or the contents of source + will be copied to the directory without renaming. + If ``dest`` is a nonexistent path, it will only be created if + ``dest`` ends with "/" or "\\", or ``src`` is a directory. + If ``src`` and ``dest`` are files and if the parent directory of + ``dest`` doesn't exist, then the task will fail. :param backup: Determine whether a backup should be created. - When set to `true`, create a backup file including the timestamp + When set to ``true``, create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. - No backup is taken when `remote_src=False` and multiple files are - being copied. + No backup is taken when ``remote_src=False`` and multiple files + are being copied. :param force: - If set to `true`, the file will only be transferred if the content - is different than destination. - If set to `false`, the file will only be transferred if the + If set to ``true``, the file will only be transferred if the + content is different than destination. + If set to ``false``, the file will only be transferred if the destination does not exist. - If set to `false`, no checksuming of the content is performed + If set to ``false``, no checksuming of the content is performed which can help improve performance on larger files. :param local_follow: This flag indicates that filesystem links in the source tree, if they exist, should be followed. :param remote_src: - If `false`, it will search for src at originating/controller + If ``false``, it will search for src at originating/controller machine. - If `true`, it will go to the remote/target machine for the src. + If ``true``, it will go to the remote/target machine for the src. :param src: Local path to a file to copy to the remote server; can be absolute or relative. If path is a directory, it is copied (including the source folder - name) recursively to `dest`. + name) recursively to ``dest``. If path is a directory and ends with "/", only the inside contents of that directory are copied to the destination. Otherwise, if it does not end with "/", the directory itself with all contents is copied. If path is a file and dest ends with "\\", the file is copied to the folder with the same filename. - Required unless using `content`. + Required unless using ``content``. """ # noqa: E501 raise AttributeError('win_copy') @@ -8338,7 +8381,7 @@ def win_dns_client( settings ('*' is supported as a wildcard value). The adapter name used is the connection caption in the Network Control Panel or the InterfaceAlias of - `Get-DnsClientServerAddress`. + ``Get-DnsClientServerAddress``. :param dns_servers: Single or ordered list of DNS servers (IPv4 and IPv6 addresses) to configure for lookup. @@ -8399,16 +8442,16 @@ def win_domain( :param database_path: The path to a directory on a fixed disk of the Windows host where the domain database will be created. - If not set then the default path is `%SYSTEMROOT%\\NTDS`. + If not set then the default path is ``%SYSTEMROOT%\\NTDS``. :param log_path: Specifies the fully qualified, non-UNC path to a directory on a fixed disk of the local computer where the log file for this operation is written. - If not set then the default path is `%SYSTEMROOT%\\NTDS`. + If not set then the default path is ``%SYSTEMROOT%\\NTDS``. :param sysvol_path: The path to a directory on a fixed disk of the Windows host where the Sysvol file will be created. - If not set then the default path is `%SYSTEMROOT%\\SYSVOL`. + If not set then the default path is ``%SYSTEMROOT%\\SYSVOL``. :param create_dns_delegation: Whether to create a DNS delegation that references the new DNS server that you install along with the domain controller. @@ -8458,33 +8501,33 @@ def win_domain_controller( :ref:`ansible.windows ` :param dns_domain_name: - When `state` is `domain_controller`, the DNS name of the domain - for which the targeted Windows host should be a DC. + When ``state`` is ``domain_controller``, the DNS name of the + domain for which the targeted Windows host should be a DC. :param domain_admin_user: Username of a domain admin for the target domain (necessary to promote or demote a domain controller). :param domain_admin_password: - Password for the specified `domain_admin_user`. + Password for the specified ``domain_admin_user``. :param safe_mode_password: Safe mode password for the domain controller (required when - `state` is `domain_controller`). + ``state`` is ``domain_controller``). :param local_admin_password: - Password to be assigned to the local `Administrator` user - (required when `state` is `member_server`). + Password to be assigned to the local ``Administrator`` user + (required when ``state`` is ``member_server``). :param read_only: Whether to install the domain controller as a read only replica for an existing domain. :param site_name: Specifies the name of an existing site where you can place the new domain controller. - This option is required when *read_only* is `true`. + This option is required when *read_only* is ``true``. :param state: Whether the target host should be a domain controller or a member server. :param database_path: The path to a directory on a fixed disk of the Windows host where the domain database will be created.. - If not set then the default path is `%SYSTEMROOT%\\NTDS`. + If not set then the default path is ``%SYSTEMROOT%\\NTDS``. :param domain_log_path: Specified the fully qualified, non-UNC path to a directory on a fixed disk of the local computer that will contain the domain log @@ -8492,24 +8535,24 @@ def win_domain_controller( :param sysvol_path: The path to a directory on a fixed disk of the Windows host where the Sysvol folder will be created. - If not set then the default path is `%SYSTEMROOT%\\SYSVOL`. + If not set then the default path is ``%SYSTEMROOT%\\SYSVOL``. :param install_media_path: The path to a directory on a fixed disk of the Windows host where - the Install From Media `IFC` data will be used. + the Install From Media ``IFC`` data will be used. See the `Install using IFM guide `__ for more information. :param install_dns: Whether to install the DNS service when creating the domain controller. - If not specified then the `-InstallDns` option is not supplied to - `Install-ADDSDomainController` command, see + If not specified then the ``-InstallDns`` option is not supplied + to ``Install-ADDSDomainController`` command, see `reference `__. :param log_path: The path to log any debug information when running the module. This option is deprecated and should not be used, it will be - removed on the major release after `2022-07-01`. - This does not relate to the `-LogPath` paramter of the install + removed on the major release after ``2022-07-01``. + This does not relate to the ``-LogPath`` paramter of the install controller cmdlet. """ # noqa: E501 raise AttributeError('win_domain_controller') @@ -8532,13 +8575,13 @@ def win_domain_membership( :ref:`ansible.windows ` :param dns_domain_name: - When `state` is `domain`, the DNS name of the domain to which the - targeted Windows host should be joined. + When ``state`` is ``domain``, the DNS name of the domain to which + the targeted Windows host should be joined. :param domain_admin_user: Username of a domain admin for the target domain (required to join or leave the domain). :param domain_admin_password: - Password for the specified `domain_admin_user`. + Password for the specified ``domain_admin_user``. :param hostname: The desired hostname for the Windows host. :param domain_ou_path: @@ -8549,8 +8592,8 @@ def win_domain_membership( Whether the target host should be a member of a domain or workgroup. :param workgroup_name: - When `state` is `workgroup`, the name of the workgroup that the - Windows host should be in. + When ``state`` is ``workgroup``, the name of the workgroup that + the Windows host should be in. """ # noqa: E501 raise AttributeError('win_domain_membership') @@ -8601,8 +8644,8 @@ def win_environment( :ref:`ansible.windows ` :param state: - Set to `present` to ensure environment variable is set. - Set to `absent` to ensure it is removed. + Set to ``present`` to ensure environment variable is set. + Set to ``absent`` to ensure it is removed. When using *variables*, do not set this option. :param name: The name of the environment variable. Required when *state=absent*. @@ -8614,15 +8657,15 @@ def win_environment( A dictionary where multiple environment variables can be defined at once. Not valid when *state* is set. Variables with a value will be set - (`present`) and variables with an empty value will be unset - (`absent`). + (``present``) and variables with an empty value will be unset + (``absent``). *level* applies to all vars defined this way. :param level: The level at which to set the environment variable. - Use `machine` to set for all users. - Use `user` to set for the current user that ansible is connected + Use ``machine`` to set for all users. + Use ``user`` to set for the current user that ansible is connected as. - Use `process` to set for the current process. Probably not that + Use ``process`` to set for the current process. Probably not that useful. """ # noqa: E501 raise AttributeError('win_environment') @@ -8646,7 +8689,7 @@ def win_feature( Names of roles or features to install as a single feature or a comma-separated list of features. To list all available features use the PowerShell command - `Get-WindowsFeature`. + ``Get-WindowsFeature``. :param state: State of the features or roles on the system. :param include_sub_features: @@ -8657,8 +8700,8 @@ def win_feature( :param source: Specify a source to install the feature from. Not supported in Windows 2008 R2 and will be ignored. - Can either be `{driveletter}:\\sources\\sxs` or - `\\{IP}\\share\\sources\\sxs`. + Can either be ``{driveletter}:\\sources\\sxs`` or + ``\\{IP}\\share\\sources\\sxs``. """ # noqa: E501 raise AttributeError('win_feature') @@ -8682,18 +8725,17 @@ def win_file( :param path: Path to the file being managed. :param state: - If `directory`, all immediate subdirectories will be created if + If ``directory``, all immediate subdirectories will be created if they do not exist. - If `file`, the file will NOT be created if it does not exist, see - the :meth:`ansible.windows.win_copy` or - :meth:`ansible.windows.win_template` module if you want that - behavior. - If `absent`, directories will be recursively deleted, and files + If ``file``, the file will NOT be created if it does not exist, + see the :meth:`win_copy` or :meth:`win_template` module if you + want that behavior. + If ``absent``, directories will be recursively deleted, and files will be removed. - If `touch`, an empty file will be created if the `path` does not - exist, while an existing file or directory will receive updated - file access and modification times (similar to the way `touch` - works from the command line). + If ``touch``, an empty file will be created if the ``path`` does + not exist, while an existing file or directory will receive + updated file access and modification times (similar to the way + ``touch`` works from the command line). """ # noqa: E501 raise AttributeError('win_file') @@ -8735,7 +8777,7 @@ def win_find( specifying the first letter of an of those words (e.g., "2s", "10d", 1w"). :param age_stamp: - Choose the file property against which we compare `age`. + Choose the file property against which we compare ``age``. The default attribute we compare with is the last modification time. :param checksum_algorithm: @@ -8744,17 +8786,17 @@ def win_find( algorithm. :param depth: Set the maximum number of levels to descend into. - Setting recurse to `false` will override this value, which is + Setting recurse to ``false`` will override this value, which is effectively depth 1. Default depth is unlimited. :param file_type: Type of file to search for. :param follow: - Set this to `true` to follow symlinks in the path. - This needs to be used in conjunction with `recurse`. + Set this to ``true`` to follow symlinks in the path. + This needs to be used in conjunction with ``recurse``. :param get_checksum: Whether to return a checksum of the file in the return info - (default sha1), use `checksum_algorithm` to change from the + (default sha1), use ``checksum_algorithm`` to change from the default. :param hidden: Set this to include hidden files or folders. @@ -8764,7 +8806,7 @@ def win_find( :param patterns: One or more (powershell or regex) patterns to compare filenames with. - The type of pattern matching is controlled by `use_regex` option. + The type of pattern matching is controlled by ``use_regex`` option. The patterns restrict the list of files or folders to be returned based on the filenames. For a file to be matched it only has to match with one pattern in @@ -8781,7 +8823,7 @@ def win_find( = k, mega = m... Size is not evaluated for symbolic links. :param use_regex: - Will set patterns to run as a regex check if set to `true`. + Will set patterns to run as a regex check if set to ``true``. """ # noqa: E501 raise AttributeError('win_find') @@ -8831,10 +8873,10 @@ def win_get_url( The location to save the file at the URL. Be sure to include a filename and extension as appropriate. :param force: - If `true`, will download the file every time and replace the file - if the contents change. If `false`, will only download the file if - it does not exist or the remote file has been modified more - recently than the local file. + If ``true``, will download the file every time and replace the + file if the contents change. If ``false``, will only download the + file if it does not exist or the remote file has been modified + more recently than the local file. This works by sending an http HEAD request to retrieve last modified time of the requested resource, so for this to work, the remote web server must support HEAD requests. @@ -8850,7 +8892,7 @@ def win_get_url( :param checksum_url: Specifies a URL that contains the checksum values for the resource at *url*. - Like `checksum`, this is used to verify the integrity of the + Like ``checksum``, this is used to verify the integrity of the remote transfer. This option cannot be set with *checksum*. :param url_method: @@ -8858,15 +8900,15 @@ def win_get_url( :param url_timeout: Specifies how long the request can be pending before it times out (in seconds). - Set to `0` to specify an infinite timeout. + Set to ``0`` to specify an infinite timeout. :param follow_redirects: Whether or the module should follow redirects. - `all` will follow all redirect. - `none` will not follow any redirect. - `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. - When following a redirected URL, the `Authorization` header and + ``all`` will follow all redirect. + ``none`` will not follow any redirect. + ``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. + When following a redirected URL, the ``Authorization`` header and any credentials set will be dropped and not redirected. :param headers: Extra headers to set on the request. @@ -8874,23 +8916,24 @@ def win_get_url( the value is the value for that header. :param http_agent: Header to identify as, generally appears in web server logs. - This is set to the `User-Agent` header on a HTTP request. + This is set to the ``User-Agent`` header on a HTTP request. :param maximum_redirection: Specify how many times the module will redirect a connection to an alternative URI before the connection fails. - If set to `0` or *follow_redirects* is set to `none`, or `safe` - when not doing a `GET` or `HEAD` it prevents all redirection. + If set to ``0`` or *follow_redirects* is set to ``none``, or + ``safe`` when not doing a ``GET`` or ``HEAD`` it prevents all + redirection. :param validate_certs: - If `False`, SSL certificates will not be validated. + If ``False``, SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates. :param client_cert: The path to the client certificate (.pfx) that is used for X509 - authentication. This path can either be the path to the `pfx` on + authentication. This path can either be the path to the ``pfx`` on the filesystem or the PowerShell certificate path - `Cert:\\CurrentUser\\My\\`. - The WinRM connection must be authenticated with `CredSSP` or - `become` is used on the task if the certificate file is not + ``Cert:\\CurrentUser\\My\\``. + The WinRM connection must be authenticated with ``CredSSP`` or + ``become`` is used on the task if the certificate file is not password protected. Other authentication types can set *client_cert_password* when the cert is password protected. @@ -8909,40 +8952,40 @@ def win_get_url( The password for *url_username*. :param use_default_credential: Uses the current user's credentials when authenticating with a - server protected with `NTLM`, `Kerberos`, or `Negotiate` + server protected with ``NTLM``, ``Kerberos``, or ``Negotiate`` authentication. - Sites that use `Basic` auth will still require explicit + Sites that use ``Basic`` auth will still require explicit credentials through the *url_username* and *url_password* options. The module will only have access to the user's credentials if - using `become` with a password, you are connecting with SSH using - a password, or connecting with WinRM using `CredSSP` or - `Kerberos with delegation`. - If not using `become` or a different auth method to the ones + using ``become`` with a password, you are connecting with SSH + using a password, or connecting with WinRM using ``CredSSP`` or + ``Kerberos with delegation``. + If not using ``become`` or a different auth method to the ones stated above, there will be no default credentials available and no authentication will occur. :param use_proxy: - If `False`, it will not use the proxy defined in IE for the + If ``False``, it will not use the proxy defined in IE for the current user. :param proxy_url: An explicit proxy to use for the request. By default, the request will use the IE defined proxy unless - *use_proxy* is set to `False`. + *use_proxy* is set to ``False``. :param proxy_username: The username to use for proxy authentication. :param proxy_password: The password for *proxy_username*. :param proxy_use_default_credential: Uses the current user's credentials when authenticating with a - proxy host protected with `NTLM`, `Kerberos`, or `Negotiate` + proxy host protected with ``NTLM``, ``Kerberos``, or ``Negotiate`` authentication. - Proxies that use `Basic` auth will still require explicit + Proxies that use ``Basic`` auth will still require explicit credentials through the *proxy_username* and *proxy_password* options. The module will only have access to the user's credentials if - using `become` with a password, you are connecting with SSH using - a password, or connecting with WinRM using `CredSSP` or - `Kerberos with delegation`. - If not using `become` or a different auth method to the ones + using ``become`` with a password, you are connecting with SSH + using a password, or connecting with WinRM using ``CredSSP`` or + ``Kerberos with delegation``. + If not using ``become`` or a different auth method to the ones stated above, there will be no default credentials available and no proxy authentication will occur. """ # noqa: E501 @@ -8995,8 +9038,8 @@ def win_group_membership( favoring domain lookups when in a domain. :param state: Desired state of the members in the group. - When `state` is `pure`, only the members specified will exist, and - all other existing members not specified are removed. + When ``state`` is ``pure``, only the members specified will exist, + and all other existing members not specified are removed. """ # noqa: E501 raise AttributeError('win_group_membership') @@ -9032,17 +9075,17 @@ def win_optional_feature( :param name: The name(s) of the feature to install. - This relates to `FeatureName` in the Powershell cmdlet. + This relates to ``FeatureName`` in the Powershell cmdlet. To list all available features use the PowerShell command - `Get-WindowsOptionalFeature`. + ``Get-WindowsOptionalFeature``. :param state: Whether to ensure the feature is absent or present on the system. :param include_parent: Whether to enable the parent feature and the parent's dependencies. :param source: Specify a source to install the feature from. - Can either be `{driveletter}:\\sources\\sxs` or - `\\{IP}\\share\\sources\\sxs`. + Can either be ``{driveletter}:\\sources\\sxs`` or + ``\\{IP}\\share\\sources\\sxs``. """ # noqa: E501 raise AttributeError('win_optional_feature') @@ -9117,9 +9160,10 @@ def win_package( :param arguments: Any arguments the installer needs to either install or uninstall the package. - If the package is an MSI do not supply the `/qn`, `/log` or - `/norestart` arguments. - This is only used for the `msi`, `msp`, and `registry` providers. + If the package is an MSI do not supply the ``/qn``, ``/log`` or + ``/norestart`` arguments. + This is only used for the ``msi``, ``msp``, and ``registry`` + providers. Can be a list of arguments and the module will escape the arguments as necessary, it is recommended to use a string when dealing with MSI packages due to the unique escaping issues with @@ -9133,133 +9177,135 @@ def win_package( :param chdir: Set the specified path as the current working directory before installing or uninstalling a package. - This is only used for the `msi`, `msp`, and `registry` providers. + This is only used for the ``msi``, ``msp``, and ``registry`` + providers. :param creates_path: Will check the existence of the path specified and use the result to determine whether the package is already installed. - You can use this in conjunction with `product_id` and other - `creates_*`. + You can use this in conjunction with ``product_id`` and other + ``creates_*``. :param creates_service: Will check the existing of the service specified and use the result to determine whether the package is already installed. - You can use this in conjunction with `product_id` and other - `creates_*`. + You can use this in conjunction with ``product_id`` and other + ``creates_*``. :param creates_version: - Will check the file version property of the file at `creates_path` - and use the result to determine whether the package is already - installed. - `creates_path` MUST be set and is a file. - You can use this in conjunction with `product_id` and other - `creates_*`. + Will check the file version property of the file at + ``creates_path`` and use the result to determine whether the + package is already installed. + ``creates_path`` MUST be set and is a file. + You can use this in conjunction with ``product_id`` and other + ``creates_*``. :param expected_return_code: One or more return codes from the package installation that indicates success. The return codes are read as a signed integer, any values greater than 2147483647 need to be represented as the signed equivalent, - i.e. `4294967295` is `-1`. + i.e. ``4294967295`` is ``-1``. To convert a unsigned number to the signed equivalent you can run "[Int32]("0x{0:X}" -f ([UInt32]3221225477))". - A return code of `3010` usually means that a reboot is required, - the `reboot_required` return value is set if the return code is - `3010`. - This is only used for the `msi`, `msp`, and `registry` providers. + A return code of ``3010`` usually means that a reboot is required, + the ``reboot_required`` return value is set if the return code is + ``3010``. + This is only used for the ``msi``, ``msp``, and ``registry`` + providers. :param log_path: Specifies the path to a log file that is persisted after a package is installed or uninstalled. - This is only used for the `msi` or `msp` provider. + This is only used for the ``msi`` or ``msp`` provider. When omitted, a temporary log file is used instead for those providers. - This is only valid for MSI files, use `arguments` for the - `registry` provider. + This is only valid for MSI files, use ``arguments`` for the + ``registry`` provider. :param path: Location of the package to be installed or uninstalled. This package can either be on the local file system, network share or a url. - When `state=present`, `product_id` is not set and the path is a - URL, this file will always be downloaded to a temporary directory - for idempotency checks, otherwise the file will only be downloaded - if the package has not been installed based on the `product_id` - checks. - If `state=present` then this value MUST be set. - If `state=absent` then this value does not need to be set if - `product_id` is. + When ``state=present``, ``product_id`` is not set and the path is + a URL, this file will always be downloaded to a temporary + directory for idempotency checks, otherwise the file will only be + downloaded if the package has not been installed based on the + ``product_id`` checks. + If ``state=present`` then this value MUST be set. + If ``state=absent`` then this value does not need to be set if + ``product_id`` is. :param product_id: The product id of the installed packaged. This is used for checking whether the product is already installed - and getting the uninstall information if `state=absent`. - For msi packages, this is the `ProductCode` (GUID) of the package. - This can be found under the same registry paths as the `registry` - provider. - For msp packages, this is the `PatchCode` (GUID) of the package - which can found under the `Details -> Revision number` of the + and getting the uninstall information if ``state=absent``. + For msi packages, this is the ``ProductCode`` (GUID) of the + package. This can be found under the same registry paths as the + ``registry`` provider. + For msp packages, this is the ``PatchCode`` (GUID) of the package + which can found under the ``Details -> Revision number`` of the file's properties. - For msix packages, this is the `Name` or `PackageFullName` of the - package found under the `Get-AppxPackage` cmdlet. + For msix packages, this is the ``Name`` or ``PackageFullName`` of + the package found under the ``Get-AppxPackage`` cmdlet. For registry (exe) packages, this is the registry key name under the registry paths specified in *provider*. - This value is ignored if `path` is set to a local accesible file - path and the package is not an `exe`. - This SHOULD be set when the package is an `exe`, or the path is a - url or a network share and credential delegation is not being - used. The `creates_*` options can be used instead but is not + This value is ignored if ``path`` is set to a local accesible file + path and the package is not an ``exe``. + This SHOULD be set when the package is an ``exe``, or the path is + a url or a network share and credential delegation is not being + used. The ``creates_*`` options can be used instead but is not recommended. :param provider: Set the package provider to use when searching for a package. - The `auto` provider will select the proper provider if *path* + The ``auto`` provider will select the proper provider if *path* otherwise it scans all the other providers based on the *product_id*. - The `msi` provider scans for MSI packages installed on a machine - wide and current user context based on the `ProductCode` of the + The ``msi`` provider scans for MSI packages installed on a machine + wide and current user context based on the ``ProductCode`` of the MSI. - The `msix` provider is used to install `.appx`, `.msix`, - `.appxbundle`, or `.msixbundle` packages. These packages are only - installed or removed on the current use. The host must be set to - allow sideloaded apps or in developer mode. See the examples for - how to enable this. If a package is already installed but `path` - points to an updated package, this will be installed over the top - of the existing one. - The `msp` provider scans for all MSP patches installed on a - machine wide and current user context based on the `PatchCode` of - the MSP. A `msp` will be applied or removed on all `msi` products - that it applies to and is installed. If the patch is obsoleted or - superseded then no action will be taken. - The `registry` provider is used for traditional `exe` installers - and uses the following registry path to determine if a product was - installed; - `HKLM:\\Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall`, - `HKLM:\\Software\\Wow6432Node\\Microsoft\\Windows\\CurrentVersion\\Uninstall`, - `HKCU:\\Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall`, + The ``msix`` provider is used to install ``.appx``, ``.msix``, + ``.appxbundle``, or ``.msixbundle`` packages. These packages are + only installed or removed on the current use. The host must be set + to allow sideloaded apps or in developer mode. See the examples + for how to enable this. If a package is already installed but + ``path`` points to an updated package, this will be installed over + the top of the existing one. + The ``msp`` provider scans for all MSP patches installed on a + machine wide and current user context based on the ``PatchCode`` + of the MSP. A ``msp`` will be applied or removed on all ``msi`` + products that it applies to and is installed. If the patch is + obsoleted or superseded then no action will be taken. + The ``registry`` provider is used for traditional ``exe`` + installers and uses the following registry path to determine if a + product was installed; + ``HKLM:\\Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall``, + ``HKLM:\\Software\\Wow6432Node\\Microsoft\\Windows\\CurrentVersion\\Uninstall``, + ``HKCU:\\Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall``, and - `HKCU:\\Software\\Wow6432Node\\Microsoft\\Windows\\CurrentVersion\\Uninstall`. + ``HKCU:\\Software\\Wow6432Node\\Microsoft\\Windows\\CurrentVersion\\Uninstall``. :param state: Whether to install or uninstall the package. The module uses *product_id* to determine whether the package is installed or not. - For all providers but `auto`, the *path* can be used for + For all providers but ``auto``, the *path* can be used for idempotency checks if it is locally accesible filesystem path. :param wait_for_children: The module will wait for the process it spawns to finish but any processes spawned in that child process as ignored. - Set to `true` to wait for all descendent processes to finish + Set to ``true`` to wait for all descendent processes to finish before the module returns. This is useful if the install/uninstaller is just a wrapper which then calls the actual installer as its own child process. When - this option is `true` then the module will wait for both processes - to finish before returning. + this option is ``true`` then the module will wait for both + processes to finish before returning. This should not be required for most installers and setting to - `true` could result in the module not returning until the process - it is waiting for has been stopped manually. + ``true`` could result in the module not returning until the + process it is waiting for has been stopped manually. Requires Windows Server 2012 or Windows 8 or newer to use. :param url_method: The HTTP Method of the request. :param follow_redirects: Whether or the module should follow redirects. - `all` will follow all redirect. - `none` will not follow any redirect. - `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. - When following a redirected URL, the `Authorization` header and + ``all`` will follow all redirect. + ``none`` will not follow any redirect. + ``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. + When following a redirected URL, the ``Authorization`` header and any credentials set will be dropped and not redirected. :param headers: Extra headers to set on the request. @@ -9267,27 +9313,28 @@ def win_package( the value is the value for that header. :param http_agent: Header to identify as, generally appears in web server logs. - This is set to the `User-Agent` header on a HTTP request. + This is set to the ``User-Agent`` header on a HTTP request. :param maximum_redirection: Specify how many times the module will redirect a connection to an alternative URI before the connection fails. - If set to `0` or *follow_redirects* is set to `none`, or `safe` - when not doing a `GET` or `HEAD` it prevents all redirection. + If set to ``0`` or *follow_redirects* is set to ``none``, or + ``safe`` when not doing a ``GET`` or ``HEAD`` it prevents all + redirection. :param url_timeout: Specifies how long the request can be pending before it times out (in seconds). - Set to `0` to specify an infinite timeout. + Set to ``0`` to specify an infinite timeout. :param validate_certs: - If `False`, SSL certificates will not be validated. + If ``False``, SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates. :param client_cert: The path to the client certificate (.pfx) that is used for X509 - authentication. This path can either be the path to the `pfx` on + authentication. This path can either be the path to the ``pfx`` on the filesystem or the PowerShell certificate path - `Cert:\\CurrentUser\\My\\`. - The WinRM connection must be authenticated with `CredSSP` or - `become` is used on the task if the certificate file is not + ``Cert:\\CurrentUser\\My\\``. + The WinRM connection must be authenticated with ``CredSSP`` or + ``become`` is used on the task if the certificate file is not password protected. Other authentication types can set *client_cert_password* when the cert is password protected. @@ -9306,40 +9353,40 @@ def win_package( The password for *url_username*. :param use_default_credential: Uses the current user's credentials when authenticating with a - server protected with `NTLM`, `Kerberos`, or `Negotiate` + server protected with ``NTLM``, ``Kerberos``, or ``Negotiate`` authentication. - Sites that use `Basic` auth will still require explicit + Sites that use ``Basic`` auth will still require explicit credentials through the *url_username* and *url_password* options. The module will only have access to the user's credentials if - using `become` with a password, you are connecting with SSH using - a password, or connecting with WinRM using `CredSSP` or - `Kerberos with delegation`. - If not using `become` or a different auth method to the ones + using ``become`` with a password, you are connecting with SSH + using a password, or connecting with WinRM using ``CredSSP`` or + ``Kerberos with delegation``. + If not using ``become`` or a different auth method to the ones stated above, there will be no default credentials available and no authentication will occur. :param use_proxy: - If `False`, it will not use the proxy defined in IE for the + If ``False``, it will not use the proxy defined in IE for the current user. :param proxy_url: An explicit proxy to use for the request. By default, the request will use the IE defined proxy unless - *use_proxy* is set to `False`. + *use_proxy* is set to ``False``. :param proxy_username: The username to use for proxy authentication. :param proxy_password: The password for *proxy_username*. :param proxy_use_default_credential: Uses the current user's credentials when authenticating with a - proxy host protected with `NTLM`, `Kerberos`, or `Negotiate` + proxy host protected with ``NTLM``, ``Kerberos``, or ``Negotiate`` authentication. - Proxies that use `Basic` auth will still require explicit + Proxies that use ``Basic`` auth will still require explicit credentials through the *proxy_username* and *proxy_password* options. The module will only have access to the user's credentials if - using `become` with a password, you are connecting with SSH using - a password, or connecting with WinRM using `CredSSP` or - `Kerberos with delegation`. - If not using `become` or a different auth method to the ones + using ``become`` with a password, you are connecting with SSH + using a password, or connecting with WinRM using ``CredSSP`` or + ``Kerberos with delegation``. + If not using ``become`` or a different auth method to the ones stated above, there will be no default credentials available and no proxy authentication will occur. """ # noqa: E501 @@ -9364,13 +9411,13 @@ def win_path( :param elements: A single path element, or a list of path elements (ie, directories) to add or remove. - When multiple elements are included in the list (and `state` is - `present`), the elements are guaranteed to appear in the same + When multiple elements are included in the list (and ``state`` is + ``present``), the elements are guaranteed to appear in the same relative order in the resultant path value. - Variable expansions (eg, `%VARNAME%`) are allowed, and are stored - unexpanded in the target path element. - Any existing path elements not mentioned in `elements` are always - preserved in their current order. + Variable expansions (eg, ``%VARNAME%``) are allowed, and are + stored unexpanded in the target path element. + Any existing path elements not mentioned in ``elements`` are + always preserved in their current order. New path elements are appended to the path, and existing path elements may be moved closer to the end to satisfy the requested ordering. @@ -9378,10 +9425,10 @@ def win_path( backslashes are ignored for comparison purposes. However, note that trailing backslashes in YAML require quotes. :param state: - Whether the path elements specified in `elements` should be + Whether the path elements specified in ``elements`` should be present or absent. :param scope: - The level at which the environment variable specified by `name` + The level at which the environment variable specified by ``name`` should be managed (either for the current user or global machine scope). """ # noqa: E501 @@ -9400,7 +9447,7 @@ def win_ping( :param data: Alternate data to return instead of 'pong'. - If this parameter is set to `crash`, the module will cause an + If this parameter is set to ``crash``, the module will cause an exception. """ # noqa: E501 raise AttributeError('win_ping') @@ -9443,29 +9490,29 @@ def win_powershell( A path or path filter pattern; when the referenced path exists on the target host, the task will be skipped. :param depth: - How deep the return values are serialized for `result`, `output`, - and `information[x].message_data`. + How deep the return values are serialized for ``result``, + ``output``, and ``information[x].message_data``. This also controls the depth of the diff output set by - `$Ansible.Diff`. + ``$Ansible.Diff``. Setting this to a higher value can dramatically increase the amount of data that needs to be returned. :param error_action: - The `$ErrorActionPreference` to set before executing *script*. - `silently_continue` will ignore any errors and exceptions raised. - `continue` is the default behaviour in PowerShell, errors are + The ``$ErrorActionPreference`` to set before executing *script*. + ``silently_continue`` will ignore any errors and exceptions raised. + ``continue`` is the default behaviour in PowerShell, errors are present in the *error* return value but only terminating exceptions will stop the script from continuing and set it as failed. - `stop` will treat errors like exceptions, will stop the script and - set it as failed. + ``stop`` will treat errors like exceptions, will stop the script + and set it as failed. :param executable: A custom PowerShell executable to run the script in. When not defined the script will run in the current module PowerShell interpreter. Both the remote PowerShell and the one specified by *executable* must be running on PowerShell v5.1 or newer. - Setting this value may change the values returned in the `output` - return value depending on the underlying .NET type. + Setting this value may change the values returned in the + ``output`` return value depending on the underlying .NET type. :param parameters: Parameters to pass into the script as key value pairs. The key corresponds to the parameter name and the value is the @@ -9478,7 +9525,7 @@ def win_powershell( :param sensitive_parameters: Parameters to pass into the script as a SecureString or PSCredential. - Each sensitive value will be marked with `no_log` to ensure they + Each sensitive value will be marked with ``no_log`` to ensure they are not exposed in the module invocation args logs. The *value* suboption can be used to create a SecureString value while *username* and *password* can be used to create a @@ -9506,7 +9553,7 @@ def win_reboot( :param pre_reboot_delay: Seconds to wait before reboot. Passed as a parameter to the reboot command. - The minimum version is `2` seconds and cannot be set lower. + The minimum version is ``2`` seconds and cannot be set lower. :param post_reboot_delay: Seconds to wait after the reboot command was successful before attempting to validate the system rebooted successfully. @@ -9556,7 +9603,7 @@ def win_reg_stat( The registry property name to get information for, the return json will not include the sub_keys and properties entries for the *key* specified. - Set to an empty string to target the registry key's `(Default`) + Set to an empty string to target the registry key's ``(Default``) property value. """ # noqa: E501 raise AttributeError('win_reg_stat') @@ -9591,19 +9638,19 @@ def win_regedit( Should be in one of the following registry hives: HKCC, HKCR, HKCU, HKLM, HKU. :param name: - Name of the registry entry in the above `path` parameters. + Name of the registry entry in the above ``path`` parameters. If not provided, or empty then the '(Default)' property for the key will be used. :param data: - Value of the registry entry `name` in `path`. + Value of the registry entry ``name`` in ``path``. If not specified then the value for the property will be null for - the corresponding `type`. + the corresponding ``type``. Binary and None data should be expressed in a yaml byte array or as comma separated hex values. - An easy way to generate this is to run `regedit.exe` and use the + An easy way to generate this is to run ``regedit.exe`` and use the *export* option to save the registry values to a file. In the exported file, binary value will look like - `hex:be,ef,be,ef`, the `hex:` prefix is optional. + ``hex:be,ef,be,ef``, the ``hex:`` prefix is optional. DWORD and QWORD values should either be represented as a decimal number or a hex value. Multistring values should be passed in as a list. @@ -9613,8 +9660,8 @@ def win_regedit( :param state: The state of the registry entry. :param delete_key: - When `state` is 'absent' then this will delete the entire key. - If `false` then it will only clear out the '(Default)' property + When ``state`` is 'absent' then this will delete the entire key. + If ``false`` then it will only clear out the '(Default)' property for that key. :param hive: A path to a hive key like C:\\Users\\Default\\NTUSER.DAT to load @@ -9624,7 +9671,8 @@ def win_regedit( This can be used to load the default user profile registry hive or any other hive saved as a file. Using this function requires the user to have the - `SeRestorePrivilege` and `SeBackupPrivilege` privileges enabled. + ``SeRestorePrivilege`` and ``SeBackupPrivilege`` privileges + enabled. """ # noqa: E501 raise AttributeError('win_regedit') @@ -9691,20 +9739,20 @@ def win_service( A list of service dependencies to set for this particular service. This should be a list of service names and not the display name of the service. - This works by `dependency_action` to either add/remove or set the - services in this list. + This works by ``dependency_action`` to either add/remove or set + the services in this list. :param dependency_action: - Used in conjunction with `dependency` to either add the + Used in conjunction with ``dependency`` to either add the dependencies to the existing service dependencies. Remove the dependencies to the existing dependencies. Set the dependencies to only the values in the list replacing the existing dependencies. :param desktop_interact: Whether to allow the service user to interact with the desktop. - This can only be set to `true` when using the `LocalSystem` + This can only be set to ``true`` when using the ``LocalSystem`` username. - This can only be set to `true` when the *service_type* is - `win32_own_process` or `win32_share_process`. + This can only be set to ``true`` when the *service_type* is + ``win32_own_process`` or ``win32_share_process``. :param description: The description to set for the service. :param display_name: @@ -9712,14 +9760,14 @@ def win_service( :param error_control: The severity of the error and action token if the service fails to start. - A new service defaults to `normal`. - `critical` will log the error and restart the system with the + A new service defaults to ``normal``. + ``critical`` will log the error and restart the system with the last-known good configuration. If the startup fails on reboot then the system will fail to operate. - `ignore` ignores the error. - `normal` logs the error in the event log but continues. - `severe` is like `critical` but a failure on the last-known good - configuration reboot startup will be ignored. + ``ignore`` ignores the error. + ``normal`` logs the error in the event log but continues. + ``severe`` is like ``critical`` but a failure on the last-known + good configuration reboot startup will be ignored. :param failure_actions: A list of failure actions the service controller should take on each failure of a service. @@ -9738,22 +9786,22 @@ def win_service( Controls whether failure actions will be performed on non crash failures or not. :param failure_command: - The command to run for a `run_command` failure action. + The command to run for a ``run_command`` failure action. Set to an empty string to remove the command. :param failure_reboot_msg: The message to be broadcast to users logged on the host for a - `reboot` failure action. + ``reboot`` failure action. Set to an empty string to remove the message. :param failure_reset_period_sec: The time in seconds after which the failure action list resets back to the start of the list if there are no failures. To set this value, *failure_actions* must have at least 1 action present. - Specify `'0xFFFFFFFF'` to set an infinite reset period. + Specify ``'0xFFFFFFFF'`` to set an infinite reset period. :param force_dependent_services: - If `true`, stopping or restarting a service with dependent + If ``true``, stopping or restarting a service with dependent services will force the dependent services to stop or restart also. - If `false`, stopping or restarting a service with dependent + If ``false``, stopping or restarting a service with dependent services may fail. :param load_order_group: The name of the load ordering group of which this service is a @@ -9768,13 +9816,13 @@ def win_service( The path to the executable to set for the service. :param password: The password to set the service to start as. - This and the `username` argument should be supplied together when - using a local or domain account. + This and the ``username`` argument should be supplied together + when using a local or domain account. If omitted then the password will continue to use the existing value password set. - If specifying `LocalSystem`, `NetworkService`, `LocalService`, the - `NT SERVICE`, or a gMSA this field can be omitted as those - accounts have no password. + If specifying ``LocalSystem``, ``NetworkService``, + ``LocalService``, the ``NT SERVICE``, or a gMSA this field can be + omitted as those accounts have no password. :param pre_shutdown_timeout_ms: The time in which the service manager waits after sending a preshutdown notification to the service until it proceeds to @@ -9794,49 +9842,49 @@ def win_service( for a list of privilege constants that can be used. :param service_type: The type of service. - The default type of a new service is `win32_own_process`. + The default type of a new service is ``win32_own_process``. *desktop_interact* can only be set if the service type is - `win32_own_process` or `win32_share_process`. + ``win32_own_process`` or ``win32_share_process``. :param sid_info: Used to define the behaviour of the service's access token groups. - `none` will not add any groups to the token. - `restricted` will add the `NT SERVICE\\` SID to the - access token's groups and restricted groups. - `unrestricted` will add the `NT SERVICE\\` SID to - the access token's groups. + ``none`` will not add any groups to the token. + ``restricted`` will add the ``NT SERVICE\\`` SID to + the access token's groups and restricted groups. + ``unrestricted`` will add the ``NT SERVICE\\`` SID + to the access token's groups. :param start_mode: Set the startup type for the service. - A newly created service will default to `auto`. + A newly created service will default to ``auto``. :param state: The desired state of the service. - `started`/`stopped`/`absent`/`paused` are idempotent actions that - will not run commands unless necessary. - `restarted` will always bounce the service. + ``started``/``stopped``/``absent``/``paused`` are idempotent + actions that will not run commands unless necessary. + ``restarted`` will always bounce the service. Only services that support the paused state can be paused, you can - check the return value `can_pause_and_continue`. + check the return value ``can_pause_and_continue``. You can only pause a service that is already started. - A newly created service will default to `stopped`. + A newly created service will default to ``stopped``. :param update_password: - When set to `always` and *password* is set, the module will always - report a change and set the password. - Set to `on_create` to only set the password if the module needs to - create the service. + When set to ``always`` and *password* is set, the module will + always report a change and set the password. + Set to ``on_create`` to only set the password if the module needs + to create the service. If *username* was specified and the service changed to that username then *password* will also be changed if specified. - The current default is `on_create` but this behaviour may change + The current default is ``on_create`` but this behaviour may change in the future, it is best to be explicit here. :param username: The username to set the service to start as. - Can also be set to `LocalSystem` or `SYSTEM` to use the SYSTEM + Can also be set to ``LocalSystem`` or ``SYSTEM`` to use the SYSTEM account. - A newly created service will default to `LocalSystem`. + A newly created service will default to ``LocalSystem``. If using a custom user account, it must have the - `SeServiceLogonRight` granted to be able to start up. You can use - the :meth:`ansible.windows.win_user_right` module to grant this - user right for you. - Set to `NT SERVICE\\service name` to run as the NT SERVICE account - for that service. - This can also be a gMSA in the form `DOMAIN\\gMSA$`. + ``SeServiceLogonRight`` granted to be able to start up. You can + use the :meth:`win_user_right` module to grant this user right for + you. + Set to ``NT SERVICE\\service name`` to run as the NT SERVICE + account for that service. + This can also be a gMSA in the form ``DOMAIN\\gMSA$``. """ # noqa: E501 raise AttributeError('win_service') @@ -9852,11 +9900,11 @@ def win_service_info( :ref:`ansible.windows ` :param name: - If specified, this is used to match the `name` or `display_name` - of the Windows service to get the info for. + If specified, this is used to match the ``name`` or + ``display_name`` of the Windows service to get the info for. Can be a wildcard to match multiple services but the wildcard will - only be matched on the `name` of the service and not - `display_name`. + only be matched on the ``name`` of the service and not + ``display_name``. If omitted then all services will returned. """ # noqa: E501 raise AttributeError('win_service_info') @@ -9896,8 +9944,8 @@ def win_share( :param path: Share directory. :param state: - Specify whether to add `present` or remove `absent` the specified - share. + Specify whether to add ``present`` or remove ``absent`` the + specified share. :param description: Share description. :param list: @@ -9962,9 +10010,9 @@ def win_shell(self, *args: Any, **kwargs: Any) -> WinShellResults: Set the specified path as the current working directory before executing a command. :param executable: - Change the shell used to execute the command (eg, `cmd`). - The target shell must accept a `/c` parameter followed by the raw - command line to be executed. + Change the shell used to execute the command (eg, ``cmd``). + The target shell must accept a ``/c`` parameter followed by the + raw command line to be executed. :param stdin: Set the stdin of the command directly to the specified value. :param no_profile: @@ -9975,8 +10023,8 @@ def win_shell(self, *args: Any, **kwargs: Any) -> WinShellResults: You can use this option when you need to run a command which ignore the console's codepage. You should only need to use this option in very rare circumstances. - This value can be any valid encoding `Name` based on the output of - `[System.Text.Encoding]::GetEncodings(`). See + This value can be any valid encoding ``Name`` based on the output + of ``[System.Text.Encoding]::GetEncodings(``). See `reference `__. """ # noqa: E501 raise AttributeError('win_shell') @@ -10015,8 +10063,8 @@ def win_stat( algorithm. :param follow: Whether to follow symlinks or junction points. - In the case of `path` pointing to another link, then that will be - followed until no more links are found. + In the case of ``path`` pointing to another link, then that will + be followed until no more links are found. """ # noqa: E501 raise AttributeError('win_stat') @@ -10071,7 +10119,7 @@ def win_template( :param backup: Determine whether a backup should be created. - When set to `true`, create a backup file including the timestamp + When set to ``true``, create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. :param block_end_string: @@ -10083,32 +10131,32 @@ def win_template( :param force: Determine when the file is being transferred if the destination already exists. - When set to `true`, replace the remote file when contents are + When set to ``true``, replace the remote file when contents are different than the source. - When set to `false`, the file will only be transferred if the + When set to ``false``, the file will only be transferred if the destination does not exist. :param lstrip_blocks: Determine when leading spaces and tabs should be stripped. - When set to `true` leading spaces and tabs are stripped from the + When set to ``true`` leading spaces and tabs are stripped from the start of a line to a block. This functionality requires Jinja 2.7 or newer. :param newline_sequence: Specify the newline sequence to use for templating files. :param output_encoding: Overrides the encoding used to write the template file defined by - `dest`. - It defaults to `utf-8`, but any encoding supported by python can + ``dest``. + It defaults to ``utf-8``, but any encoding supported by python can be used. - The source template file must always be encoded using `utf-8`, for - homogeneity. + The source template file must always be encoded using ``utf-8``, + for homogeneity. :param src: Path of a Jinja2 formatted template on the Ansible controller. This can be a relative or an absolute path. - The file must be encoded with `utf-8` but *output_encoding* can be - used to control the encoding of the output template. + The file must be encoded with ``utf-8`` but *output_encoding* can + be used to control the encoding of the output template. :param trim_blocks: Determine when newlines should be removed from blocks. - When set to `true` the first newline after a block is removed + When set to ``true`` the first newline after a block is removed (block, not variable tag!). :param variable_end_string: The string marking the end of a print statement. @@ -10158,13 +10206,13 @@ def win_updates( update if it was not in the category specified. :param category_names: A scalar or list of categories to install updates from. To get the - list of categories, run the module with `state=searched`. The + list of categories, run the module with ``state=searched``. The category must be the full category string, but is case insensitive. Some possible categories are Application, Connectors, Critical Updates, Definition Updates, Developer Kits, Feature Packs, Guidance, Security Updates, Service Packs, Tools, Update Rollups, Updates, and Upgrades. - Since `v1.7.0` the value `*` will match all categories. + Since ``v1.7.0`` the value ``*`` will match all categories. :param skip_optional: Skip optional updates where the update has BrowseOnly set by Microsoft. @@ -10174,34 +10222,34 @@ def win_updates( :param reboot: Ansible will automatically reboot the remote host if it is required and continue to install updates after the reboot. - This can be used instead of using a - :meth:`ansible.windows.win_reboot` task after this one and ensures - all updates for that category is installed in one go. - Async does not work when `reboot=true`. + This can be used instead of using a :meth:`win_reboot` task after + this one and ensures all updates for that category is installed in + one go. + Async does not work when ``reboot=true``. :param reboot_timeout: The time in seconds to wait until the host is back online from a reboot. - This is only used if `reboot=true` and a reboot is required. + This is only used if ``reboot=true`` and a reboot is required. :param server_selection: Defines the Windows Update source catalog. - `default` Use the default search source. For many systems default - is set to the Microsoft Windows Update catalog. Systems + ``default`` Use the default search source. For many systems + default is set to the Microsoft Windows Update catalog. Systems participating in Windows Server Update Services (WSUS) or similar corporate update server environments may default to those managed update sources instead of the Windows Update catalog. - `managed_server` Use a managed server catalog. For environments + ``managed_server`` Use a managed server catalog. For environments utilizing Windows Server Update Services (WSUS) or similar corporate update servers, this option selects the defined corporate update source. - `windows_update` Use the Microsoft Windows Update catalog. + ``windows_update`` Use the Microsoft Windows Update catalog. :param state: Controls whether found updates are downloaded or installed or listed. This module also supports Ansible check mode, which has the same effect as setting state=searched. :param log_path: - If set, `win_updates` will append update progress to the specified - file. The directory must already exist. + If set, ``win_updates`` will append update progress to the + specified file. The directory must already exist. :param reject_list: A list of update titles or KB numbers that can be used to specify which updates are to be excluded from installation. @@ -10269,7 +10317,7 @@ def win_uri( Whether or not to return the body of the response as a "content" key in the dictionary result. If the reported Content-type is "application/json", then the JSON is additionally loaded into a - key called `json` in the dictionary results. + key called ``json`` in the dictionary results. :param status_code: A valid, numeric, HTTP status code that signifies success of the request. @@ -10279,15 +10327,15 @@ def win_uri( :param url_timeout: Specifies how long the request can be pending before it times out (in seconds). - Set to `0` to specify an infinite timeout. + Set to ``0`` to specify an infinite timeout. :param follow_redirects: Whether or the module should follow redirects. - `all` will follow all redirect. - `none` will not follow any redirect. - `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. - When following a redirected URL, the `Authorization` header and + ``all`` will follow all redirect. + ``none`` will not follow any redirect. + ``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. + When following a redirected URL, the ``Authorization`` header and any credentials set will be dropped and not redirected. :param headers: Extra headers to set on the request. @@ -10295,23 +10343,24 @@ def win_uri( the value is the value for that header. :param http_agent: Header to identify as, generally appears in web server logs. - This is set to the `User-Agent` header on a HTTP request. + This is set to the ``User-Agent`` header on a HTTP request. :param maximum_redirection: Specify how many times the module will redirect a connection to an alternative URI before the connection fails. - If set to `0` or *follow_redirects* is set to `none`, or `safe` - when not doing a `GET` or `HEAD` it prevents all redirection. + If set to ``0`` or *follow_redirects* is set to ``none``, or + ``safe`` when not doing a ``GET`` or ``HEAD`` it prevents all + redirection. :param validate_certs: - If `False`, SSL certificates will not be validated. + If ``False``, SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates. :param client_cert: The path to the client certificate (.pfx) that is used for X509 - authentication. This path can either be the path to the `pfx` on + authentication. This path can either be the path to the ``pfx`` on the filesystem or the PowerShell certificate path - `Cert:\\CurrentUser\\My\\`. - The WinRM connection must be authenticated with `CredSSP` or - `become` is used on the task if the certificate file is not + ``Cert:\\CurrentUser\\My\\``. + The WinRM connection must be authenticated with ``CredSSP`` or + ``become`` is used on the task if the certificate file is not password protected. Other authentication types can set *client_cert_password* when the cert is password protected. @@ -10330,40 +10379,40 @@ def win_uri( The password for *url_username*. :param use_default_credential: Uses the current user's credentials when authenticating with a - server protected with `NTLM`, `Kerberos`, or `Negotiate` + server protected with ``NTLM``, ``Kerberos``, or ``Negotiate`` authentication. - Sites that use `Basic` auth will still require explicit + Sites that use ``Basic`` auth will still require explicit credentials through the *url_username* and *url_password* options. The module will only have access to the user's credentials if - using `become` with a password, you are connecting with SSH using - a password, or connecting with WinRM using `CredSSP` or - `Kerberos with delegation`. - If not using `become` or a different auth method to the ones + using ``become`` with a password, you are connecting with SSH + using a password, or connecting with WinRM using ``CredSSP`` or + ``Kerberos with delegation``. + If not using ``become`` or a different auth method to the ones stated above, there will be no default credentials available and no authentication will occur. :param use_proxy: - If `False`, it will not use the proxy defined in IE for the + If ``False``, it will not use the proxy defined in IE for the current user. :param proxy_url: An explicit proxy to use for the request. By default, the request will use the IE defined proxy unless - *use_proxy* is set to `False`. + *use_proxy* is set to ``False``. :param proxy_username: The username to use for proxy authentication. :param proxy_password: The password for *proxy_username*. :param proxy_use_default_credential: Uses the current user's credentials when authenticating with a - proxy host protected with `NTLM`, `Kerberos`, or `Negotiate` + proxy host protected with ``NTLM``, ``Kerberos``, or ``Negotiate`` authentication. - Proxies that use `Basic` auth will still require explicit + Proxies that use ``Basic`` auth will still require explicit credentials through the *proxy_username* and *proxy_password* options. The module will only have access to the user's credentials if - using `become` with a password, you are connecting with SSH using - a password, or connecting with WinRM using `CredSSP` or - `Kerberos with delegation`. - If not using `become` or a different auth method to the ones + using ``become`` with a password, you are connecting with SSH + using a password, or connecting with WinRM using ``CredSSP`` or + ``Kerberos with delegation``. + If not using ``become`` or a different auth method to the ones stated above, there will be no default credentials available and no proxy authentication will occur. """ # noqa: E501 @@ -10397,17 +10446,17 @@ def win_user( :ref:`ansible.windows ` :param account_disabled: - `true` will disable the user account. - `false` will clear the disabled flag. + ``true`` will disable the user account. + ``false`` will clear the disabled flag. :param account_expires: Set the account expiration date for the user. - This value should be in the format `%Y-%m-%d` or - `%Y-%m-%dT%H:%M:%S%z`. The timezone can be omitted in the long - format and will default to UTC. The format of `%z` is `±HHMM`, - `±HH:MM`, or `Z` for UTC. - Set the value to `never` to remove the account expiration date. + This value should be in the format ``%Y-%m-%d`` or + ``%Y-%m-%dT%H:%M:%S%z``. The timezone can be omitted in the long + format and will default to UTC. The format of ``%z`` is ``±HHMM``, + ``±HH:MM``, or ``Z`` for UTC. + Set the value to ``never`` to remove the account expiration date. :param account_locked: - Only `false` can be set and it will unlock the user account if + Only ``false`` can be set and it will unlock the user account if locked. :param description: Description of the user. @@ -10416,16 +10465,16 @@ def win_user( :param groups: Adds or removes the user from this comma-separated list of groups, depending on the value of *groups_action*. - When *groups_action* is `replace` and *groups* is set to the empty - string ('groups='), the user is removed from all groups. - Since `ansible.windows v1.5.0` it is possible to specify a group + When *groups_action* is ``replace`` and *groups* is set to the + empty string ('groups='), the user is removed from all groups. + Since ``ansible.windows v1.5.0`` it is possible to specify a group using it's security identifier. :param groups_action: - If `add`, the user is added to each group in *groups* where not + If ``add``, the user is added to each group in *groups* where not already a member. - If `replace`, the user is added as a member of each group in + If ``replace``, the user is added as a member of each group in *groups* and removed from any other groups. - If `remove`, the user is removed from each group in *groups*. + If ``remove``, the user is removed from each group in *groups*. :param home_directory: The designated home directory of the user. :param login_script: @@ -10435,25 +10484,25 @@ def win_user( :param password: Optionally set the user's password to this (plain text) value. :param password_expired: - `true` will require the user to change their password at next + ``true`` will require the user to change their password at next login. - `false` will clear the expired password flag. + ``false`` will clear the expired password flag. :param password_never_expires: - `true` will set the password to never expire. - `false` will allow the password to expire. + ``true`` will set the password to never expire. + ``false`` will allow the password to expire. :param profile: The profile path of the user. :param state: - When `absent`, removes the user account if it exists. - When `present`, creates or updates the user account. - When `query`, retrieves the user account details without making + When ``absent``, removes the user account if it exists. + When ``present``, creates or updates the user account. + When ``query``, retrieves the user account details without making any changes. :param update_password: - `always` will update passwords if they differ. - `on_create` will only set the password for newly created users. + ``always`` will update passwords if they differ. + ``on_create`` will only set the password for newly created users. :param user_cannot_change_password: - `true` will prevent the user from changing their password. - `false` will allow the user to change their password. + ``true`` will prevent the user from changing their password. + ``false`` will allow the user to change their password. """ # noqa: E501 raise AttributeError('win_user') @@ -10471,7 +10520,7 @@ def win_user_right( :ref:`ansible.windows ` :param name: - The name of the User Right as shown by the `Constant Name` value + The name of the User Right as shown by the ``Constant Name`` value from `reference `__. The module will return an error if the right is invalid. @@ -10482,16 +10531,16 @@ def win_user_right( For local users/groups it can be in the form user-group, .\\user-group, SERVERNAME\\user-group where SERVERNAME is the name of the remote server. - It is highly recommended to use the `.\\` or `SERVERNAME\\` prefix - to avoid any ambiguity with domain account names or errors trying - to lookup an account on a domain controller. + It is highly recommended to use the ``.\\`` or ``SERVERNAME\\`` + prefix to avoid any ambiguity with domain account names or errors + trying to lookup an account on a domain controller. You can also add special local accounts like SYSTEM and others. Can be set to an empty list with *action=set* to remove all accounts from the right. :param action: - `add` will add the users/groups to the existing right. - `remove` will remove the users/groups from the existing right. - `set` will replace the users/groups of the existing right. + ``add`` will add the users/groups to the existing right. + ``remove`` will remove the users/groups from the existing right. + ``set`` will replace the users/groups of the existing right. """ # noqa: E501 raise AttributeError('win_user_right') @@ -10528,35 +10577,36 @@ def win_wait_for( The number of seconds to wait before starting to poll. :param exclude_hosts: The list of hosts or IPs to ignore when looking for active TCP - connections when `state=drained`. + connections when ``state=drained``. :param host: A resolvable hostname or IP address to wait for. - If `state=drained` then it will only check for connections on the - IP specified, you can use '0.0.0.0' to use all host IPs. + If ``state=drained`` then it will only check for connections on + the IP specified, you can use '0.0.0.0' to use all host IPs. :param path: The path to a file on the filesystem to check. - If `state` is present or started then it will wait until the file - exists. - If `state` is absent then it will wait until the file does not + If ``state`` is present or started then it will wait until the + file exists. + If ``state`` is absent then it will wait until the file does not exist. :param port: - The port number to poll on `host`. + The port number to poll on ``host``. :param regex: Can be used to match a string in a file. - If `state` is present or started then it will wait until the regex - matches. - If `state` is absent then it will wait until the regex does not + If ``state`` is present or started then it will wait until the + regex matches. + If ``state`` is absent then it will wait until the regex does not match. Defaults to a multiline regex. :param sleep: Number of seconds to sleep between checks. :param state: - When checking a port, `started` will ensure the port is open, - `stopped` will check that is it closed and `drained` will check - for active connections. - When checking for a file or a search string `present` or `started` - will ensure that the file or string is present, `absent` will - check that the file or search string is absent or removed. + When checking a port, ``started`` will ensure the port is open, + ``stopped`` will check that is it closed and ``drained`` will + check for active connections. + When checking for a file or a search string ``present`` or + ``started`` will ensure that the file or string is present, + ``absent`` will check that the file or search string is absent or + removed. :param timeout: The maximum number of seconds to wait for. """ # noqa: E501 diff --git a/src/suitable/api.py b/src/suitable/api.py index 580297d..a8057b2 100644 --- a/src/suitable/api.py +++ b/src/suitable/api.py @@ -137,12 +137,12 @@ def __init__( collections when loading/hooking the modules. Ansible only initializes the module loader once, so it's not - possible to have multiple `Api` instances with different + possible to have multiple ``Api`` instances with different values for this parameter. The first one will always be the one that matters. Additionally if the loader has already been initialized prior - to the creation of the Api instance, then this parameter has + to the creation of the ``Api`` instance, then this parameter has no effect at all. Requires ansible-core >= 2.15