habsi/ansible
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs adjustments (#83369)

Browse Source
This commit is contained in:
Alexei Znamensky
2024-06-11 14:16:59 +12:00
committed by GitHub
parent 531bc9891f
commit 4f73d2ff7a
10 changed files with 70 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
lib/ansible/modules/deb822_repository.py
View File

@ -8,28 +8,28 @@ DOCUMENTATION = '''
author: 'Ansible Core Team (@ansible)'
short_description: 'Add and remove deb822 formatted repositories'
description:
- 'Add and remove deb822 formatted repositories in Debian based distributions'
- 'Add and remove deb822 formatted repositories in Debian based distributions.'
module: deb822_repository
notes:
- This module will not automatically update caches, call the apt module based
- This module will not automatically update caches, call the M(ansible.builtin.apt) module based
on the changed state.
options:
allow_downgrade_to_insecure:
description:
- Allow downgrading a package that was previously authenticated but
is no longer authenticated
is no longer authenticated.
type: bool
allow_insecure:
description:
- Allow insecure repositories
- Allow insecure repositories.
type: bool
allow_weak:
description:
- Allow repositories signed with a key using a weak digest algorithm
- Allow repositories signed with a key using a weak digest algorithm.
type: bool
architectures:
description:
- 'Architectures to search within repository'
- Architectures to search within repository.
type: list
elements: str
by_hash:
@ -51,7 +51,7 @@ options:
components:
description:
- Components specify different sections of one distribution version
present in a Suite.
present in a C(Suite).
type: list
elements: str
date_max_future:
@ -64,8 +64,8 @@ options:
type: bool
inrelease_path:
description:
- Determines the path to the InRelease file, relative to the normal
position of an InRelease file.
- Determines the path to the C(InRelease) file, relative to the normal
position of an C(InRelease) file.
type: str
languages:
description:
@ -81,8 +81,8 @@ options:
type: str
pdiffs:
description:
- Controls if APT should try to use PDiffs to update old indexes
instead of downloading the new indexes entirely
- Controls if APT should try to use C(PDiffs) to update old indexes
instead of downloading the new indexes entirely.
type: bool
signed_by:
description:
@ -97,21 +97,20 @@ options:
Suite can specify an exact path in relation to the URI(s) provided,
in which case the Components: must be omitted and suite must end
with a slash (C(/)). Alternatively, it may take the form of a
distribution version (e.g. a version codename like disco or artful).
distribution version (for example a version codename like C(disco) or C(artful)).
If the suite does not specify a path, at least one component must
be present.
type: list
elements: str
targets:
description:
- Defines which download targets apt will try to acquire from this
source.
- Defines which download targets apt will try to acquire from this source.
type: list
elements: str
trusted:
description:
- Decides if a source is considered trusted or if warnings should be
raised before e.g. packages are installed from this source.
raised before, for example packages are installed from this source.
type: bool
types:
choices:
@ -123,7 +122,7 @@ options:
elements: str
description:
- Which types of packages to look for from a given source; either
binary V(deb) or source code V(deb-src)
binary V(deb) or source code V(deb-src).
uris:
description:
- The URIs must specify the base of the Debian distribution archive,
@ -132,7 +131,7 @@ options:
elements: str
mode:
description:
- The octal mode for newly created files in sources.list.d.
- The octal mode for newly created files in C(sources.list.d).
type: raw
default: '0644'
state:

18
lib/ansible/modules/debconf.py
View File

@ -29,24 +29,24 @@ notes:
- Several questions have to be answered (depending on the package).
Use 'debconf-show <package>' on any Debian or derivative with the package
installed to see questions/settings available.
- Some distros will always record tasks involving the setting of passwords as changed. This is due to debconf-get-selections masking passwords.
- Some distros will always record tasks involving the setting of passwords as changed. This is due to C(debconf-get-selections) masking passwords.
- It is highly recommended to add C(no_log=True) to the task while handling sensitive information using this module.
- The debconf module does not reconfigure packages, it just updates the debconf database.
- The M(ansible.builtin.debconf) module does not reconfigure packages, it just updates the debconf database.
An additional step is needed (typically with C(notify) if debconf makes a change)
to reconfigure the package and apply the changes.
debconf is extensively used for pre-seeding configuration prior to installation
C(debconf) is extensively used for pre-seeding configuration prior to installation
rather than modifying configurations.
So, while dpkg-reconfigure does use debconf data, it is not always authoritative
So, while C(dpkg-reconfigure) does use debconf data, it is not always authoritative
and you may need to check how your package is handled.
- Also note dpkg-reconfigure is a 3-phase process. It invokes the
- Also note C(dpkg-reconfigure) is a 3-phase process. It invokes the
control scripts from the C(/var/lib/dpkg/info) directory with the
C(<package>.prerm reconfigure <version>),
C(<package>.config reconfigure <version>) and C(<package>.postinst control <version>) arguments.
- The main issue is that the C(<package>.config reconfigure) step for many packages
will first reset the debconf database (overriding changes made by this module) by
checking the on-disk configuration. If this is the case for your package then
dpkg-reconfigure will effectively ignore changes made by debconf.
- However as dpkg-reconfigure only executes the C(<package>.config) step if the file
C(dpkg-reconfigure) will effectively ignore changes made by debconf.
- However as C(dpkg-reconfigure) only executes the C(<package>.config) step if the file
exists, it is possible to rename it to C(/var/lib/dpkg/info/<package>.config.ignore)
before executing C(dpkg-reconfigure -f noninteractive <package>) and then restore it.
This seems to be compliant with Debian policy for the .config file.
@ -76,12 +76,12 @@ options:
value:
description:
- Value to set the configuration to.
- After Ansible 2.17, C(value) is of type 'raw'.
- After Ansible 2.17, C(value) is of type C(raw).
type: raw
aliases: [ answer ]
unseen:
description:
- Do not set 'seen' flag when pre-seeding.
- Do not set C(seen) flag when pre-seeding.
type: bool
default: false
author:

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

@ -14,7 +14,7 @@ description:
- This module prints statements during execution and can be useful
for debugging variables or expressions without necessarily halting
the playbook.
- Useful for debugging together with the 'when:' directive.
- Useful for debugging together with the C(when:) directive.
- This module is also supported for Windows targets.
version_added: '0.8'
options:

39
lib/ansible/modules/dnf.py
View File

@ -49,14 +49,14 @@ options:
state:
description:
- Whether to install (V(present), V(latest)), or remove (V(absent)) a package.
- Default is V(None), however in effect the default action is V(present) unless the O(autoremove) option is
enabled for this module, then V(absent) is inferred.
- Default is V(None), however in effect the default action is V(present) unless the O(autoremove=true),
then V(absent) is inferred.
choices: ['absent', 'present', 'installed', 'removed', 'latest']
type: str
enablerepo:
description:
- I(Repoid) of repositories to enable for the install/update operation.
- C(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 ",".
type: list
@ -65,9 +65,9 @@ options:
disablerepo:
description:
- I(Repoid) of repositories to disable for the install/update operation.
- C(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 C(,).
type: list
elements: str
default: []
@ -80,7 +80,7 @@ options:
disable_gpg_check:
description:
- Whether to disable the GPG checking of signatures of packages being
installed. Has an effect only if O(state) is V(present) or V(latest).
installed. Has an effect only if O(state=present) or O(state=latest).
- This setting affects packages installed from a repository as well as
"local" packages installed from the filesystem or a URL.
type: bool
@ -105,13 +105,13 @@ options:
description:
- If V(true), removes all "leaf" packages from the system that were originally
installed as dependencies of user-installed packages but which are no longer
required by any such package. Should be used alone or when O(state) is V(absent)
required by any such package. Should be used alone or when O(state=absent).
type: bool
default: "no"
version_added: "2.4"
exclude:
description:
- Package name(s) to exclude when state=present, or latest. This can be a
- Package name(s) to exclude when O(state=present), or latest. This can be a
list or a comma separated string.
version_added: "2.7"
type: list
@ -120,14 +120,14 @@ options:
skip_broken:
description:
- Skip all unavailable packages or packages with broken dependencies
without raising an error. Equivalent to passing the --skip-broken option.
without raising an error. Equivalent to passing the C(--skip-broken) option.
type: bool
default: "no"
version_added: "2.7"
update_cache:
description:
- Force dnf to check if cache is out of date and redownload if needed.
Has an effect only if O(state) is V(present) or V(latest).
Has an effect only if O(state=present) or O(state=latest).
type: bool
default: "no"
aliases: [ expire-cache ]
@ -135,7 +135,7 @@ options:
update_only:
description:
- When using latest, only update installed packages. Do not install packages.
- Has an effect only if O(state) is V(latest)
- Has an effect only if O(state=present) or O(state=latest).
default: "no"
type: bool
version_added: "2.7"
@ -155,7 +155,7 @@ options:
version_added: "2.7"
enable_plugin:
description:
- I(Plugin) name to enable for the install/update operation.
- C(Plugin) name to enable for the install/update operation.
The enabled plugin will not persist beyond the transaction.
version_added: "2.7"
type: list
@ -163,7 +163,7 @@ options:
default: []
disable_plugin:
description:
- I(Plugin) name to disable for the install/update operation.
- C(Plugin) name to disable for the install/update operation.
The disabled plugins will not persist beyond the transaction.
version_added: "2.7"
type: list
@ -173,13 +173,14 @@ options:
description:
- Disable the excludes defined in DNF config files.
- If set to V(all), disables all excludes.
- If set to V(main), disable excludes defined in [main] in dnf.conf.
- If set to V(main), disable excludes defined in C([main]) in C(dnf.conf).
- If set to V(repoid), disable excludes defined for given repo id.
version_added: "2.7"
type: str
validate_certs:
description:
- This only applies if using a https url as the source of the rpm. e.g. for localinstall. If set to V(false), the SSL certificates will not be validated.
- This only applies if using a https url as the source of the rpm. For example, for localinstall.
If set to V(false), the SSL certificates will not be validated.
- This should only set to V(false) used on personally controlled sites using self-signed certificates as it avoids verifying the source site.
type: bool
default: "yes"
@ -195,7 +196,7 @@ options:
description:
- Specify if the named package and version is allowed to downgrade
a maybe already installed higher version of that package.
Note that setting allow_downgrade=True can make this module
Note that setting O(allow_downgrade=true) can make this module
behave in a non-idempotent way. The task could end up with a set
of packages that does not match the complete list of specified
packages to install (because dependencies between the downgraded
@ -238,7 +239,7 @@ options:
version_added: "2.8"
allowerasing:
description:
- If V(true) it allows erasing of installed packages to resolve dependencies.
- If V(true) it allows erasing of installed packages to resolve dependencies.
required: false
type: bool
default: "no"
@ -282,11 +283,11 @@ attributes:
platform:
platforms: rhel
notes:
- When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly to the I(name) option.
- When used with a C(loop:) each package will be processed individually, it is much more efficient to pass the list directly to the O(name) option.
- Group removal doesn't work if the group was installed with Ansible because
upstream dnf's API doesn't properly mark groups as installed, therefore upon
removal the module is unable to detect that the group is installed
(https://bugzilla.redhat.com/show_bug.cgi?id=1620324)
U(https://bugzilla.redhat.com/show_bug.cgi?id=1620324).
requirements:
- python3-dnf
- for the autoremove option you need dnf >= 2.0.1"

24
lib/ansible/modules/dnf5.py
View File

@ -17,7 +17,7 @@ options:
name:
description:
- "A package name or package specifier with version, like C(name-1.0).
When using state=latest, this can be '*' which means run: dnf -y update.
When using O(state=latest), this can be C(*) which means run: C(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 C(>), C(<), C(>=), C(<=). Example - C(name >= 1.0).
@ -37,15 +37,15 @@ options:
state:
description:
- Whether to install (V(present), V(latest)), or remove (V(absent)) a package.
- Default is V(None), however in effect the default action is V(present) unless the V(autoremove) option is
enabled for this module, then V(absent) is inferred.
- Default is V(None), however in effect the default action is V(present) unless the O(autoremove=true),
then V(absent) is inferred.
choices: ['absent', 'present', 'installed', 'removed', 'latest']
type: str
enablerepo:
description:
- I(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 C(,).
type: list
elements: str
default: []
@ -53,7 +53,7 @@ options:
description:
- I(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 C(,).
type: list
elements: str
default: []
@ -84,12 +84,12 @@ options:
description:
- If V(true), removes all "leaf" packages from the system that were originally
installed as dependencies of user-installed packages but which are no longer
required by any such package. Should be used alone or when O(state) is V(absent)
required by any such package. Should be used alone or when O(state=absent).
type: bool
default: "no"
exclude:
description:
- Package name(s) to exclude when state=present, or latest. This can be a
- Package name(s) to exclude when O(state=present) or O(state=latest). This can be a
list or a comma separated string.
type: list
elements: str
@ -97,20 +97,20 @@ options:
skip_broken:
description:
- Skip all unavailable packages or packages with broken dependencies
without raising an error. Equivalent to passing the --skip-broken option.
without raising an error. Equivalent to passing the C(--skip-broken) option.
type: bool
default: "no"
update_cache:
description:
- Force dnf to check if cache is out of date and redownload if needed.
Has an effect only if O(state) is V(present) or V(latest).
Has an effect only if O(state=present) or O(state=latest).
type: bool
default: "no"
aliases: [ expire-cache ]
update_only:
description:
- When using latest, only update installed packages. Do not install packages.
- Has an effect only if O(state) is V(latest)
- Has an effect only if O(state=present) or O(state=latest).
default: "no"
type: bool
security:
@ -147,7 +147,7 @@ options:
description:
- Disable the excludes defined in DNF config files.
- If set to V(all), disables all excludes.
- If set to V(main), disable excludes defined in [main] in dnf.conf.
- If set to V(main), disable excludes defined in C([main]) in C(dnf.conf).
- If set to V(repoid), disable excludes defined for given repo id.
type: str
validate_certs:
@ -166,7 +166,7 @@ options:
description:
- Specify if the named package and version is allowed to downgrade
a maybe already installed higher version of that package.
Note that setting allow_downgrade=True can make this module
Note that setting O(allow_downgrade=true) can make this module
behave in a non-idempotent way. The task could end up with a set
of packages that does not match the complete list of specified
packages to install (because dependencies between the downgraded

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

@ -11,7 +11,7 @@ DOCUMENTATION = '''
module: dpkg_selections
short_description: Dpkg package selection selections
description:
- Change dpkg package selection state via --get-selections and --set-selections.
- Change dpkg package selection state via C(--get-selections) and C(--set-selections).
version_added: "2.0"
author:
- Brian Brazil (@brian-brazil) <brian.brazil@boxever.com>

4
lib/ansible/modules/expect.py
View File

@ -70,10 +70,10 @@ notes:
- If you want to run a command through the shell (say you are using C(<),
C(>), C(|), and so on), you must specify a shell in the command such as
C(/bin/bash -c "/path/to/something | grep else").
- Case insensitive searches are indicated with a prefix of C(?i).
- Case insensitive searches are indicated with a prefix of C((?i)).
- The C(pexpect) library used by this module operates with a search window
of 2000 bytes, and does not use a multiline regex match. To perform a
start of line bound match, use a pattern like ``(?m)^pattern``
start of line bound match, use a pattern like C((?m)^pattern).
- The M(ansible.builtin.expect) module is designed for simple scenarios.
For more complex needs, consider the use of expect code with the M(ansible.builtin.shell)
or M(ansible.builtin.script) modules. (An example is part of the M(ansible.builtin.shell) module documentation).

4
lib/ansible/modules/fetch.py
View File

@ -28,8 +28,8 @@ options:
dest:
description:
- A directory to save the file into.
- For example, if the O(dest) directory is C(/backup) a O(src) file named C(/etc/profile) on host
C(host.example.com), would be saved into C(/backup/host.example.com/etc/profile).
- For example, if O(dest=/backup), then O(src=/etc/profile) on host
C(host.example.com), would save the file into C(/backup/host.example.com/etc/profile).
The host name is based on the inventory name.
required: yes
fail_on_missing:

2
lib/ansible/modules/file.py
View File

@ -73,7 +73,7 @@ options:
- This flag indicates that filesystem links, if they exist, should be followed.
- O(follow=yes) and O(state=link) can modify O(src) when combined with parameters such as O(mode).
- Previous to Ansible 2.5, this was V(false) by default.
- While creating a symlink with a non-existent destination, set O(follow) to V(false) to avoid a warning message related to permission issues.
- While creating a symlink with a non-existent destination, set O(follow=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.
type: bool
default: yes

12
lib/ansible/modules/find.py
View File

@ -58,8 +58,8 @@ options:
contains:
description:
- A regular expression or pattern which should be matched against the file content.
- If O(read_whole_file) is V(false) it matches against the beginning of the line (uses
V(re.match(\))). If O(read_whole_file) is V(true), it searches anywhere for that pattern
- If O(read_whole_file=false) it matches against the beginning of the line (uses
V(re.match(\))). If O(read_whole_file=true), it searches anywhere for that pattern
(uses V(re.search(\))).
- Works only when O(file_type) is V(file).
type: str
@ -82,7 +82,7 @@ options:
file_type:
description:
- Type of file to select.
- The 'link' and 'any' choices were added in Ansible 2.3.
- The V(link) and V(any) choices were added in Ansible 2.3.
type: str
choices: [ any, directory, file, link ]
default: file
@ -116,7 +116,7 @@ options:
restricted to modes that can be applied using the python
C(os.chmod) function.
- The mode can be provided as an octal such as V("0644") or
as symbolic such as V(u=rw,g=r,o=r)
as symbolic such as V(u=rw,g=r,o=r).
type: raw
version_added: '2.16'
exact_mode:
@ -145,13 +145,13 @@ options:
depth:
description:
- Set the maximum number of levels to descend into.
- Setting recurse to V(false) will override this value, which is effectively depth 1.
- Setting O(recurse=false) will override this value, which is effectively depth 1.
- Default is unlimited depth.
type: int
version_added: "2.6"
encoding:
description:
- When doing a C(contains) search, determine the encoding of the files to be searched.
- When doing a O(contains) search, determine the encoding of the files to be searched.
type: str
version_added: "2.17"
extends_documentation_fragment: action_common_attributes