ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-04-06 02:30:32 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

[PR #9528/838cdaab backport][stable-10] lmn*: style adjustments (#9543)

Browse source 
lmn*: style adjustments (#9528)

* lmn*: style adjustments

* Apply suggestions from code review

* Apply suggestions from code review

Co-authored-by: Felix Fontein <felix@fontein.de>

---------

Co-authored-by: Felix Fontein <felix@fontein.de>
(cherry picked from commit 838cdaab42)

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>
This commit is contained in:
patchback[bot] 2025-01-07 18:45:30 +01:00 • committed by GitHub
parent 1f29fa2e39
commit 75f649648e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
43 changed files with 440 additions and 378 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
plugins/modules/launchd.py
View file

@ -38,10 +38,11 @@ options:
state:
description:
- V(started)/V(stopped) are idempotent actions that will not run commands unless necessary.
- Launchd does not support V(restarted) nor V(reloaded) natively. These will trigger a stop/start (restarted) or an unload/load (reloaded).
- Launchd does not support V(restarted) nor V(reloaded) natively. These will trigger a stop/start (restarted) or an
unload/load (reloaded).
- V(restarted) unloads and loads the service before start to ensure that the latest job definition (plist) is used.
- V(reloaded) unloads and loads the service to ensure that the latest job definition (plist) is used. Whether a service is started or stopped
depends on the content of the definition file.
- V(reloaded) unloads and loads the service to ensure that the latest job definition (plist) is used. Whether a service
is started or stopped depends on the content of the definition file.
type: str
choices: [reloaded, restarted, started, stopped, unloaded]
enabled:
@ -52,8 +53,8 @@ options:
force_stop:
description:
- Whether the service should not be restarted automatically by launchd.
- Services might have the 'KeepAlive' attribute set to true in a launchd configuration. In case this is set to true, stopping a service
will cause that launchd starts the service again.
- Services might have the 'KeepAlive' attribute set to true in a launchd configuration. In case this is set to true,
stopping a service will cause that launchd starts the service again.
- Set this option to V(true) to let this module change the C(KeepAlive) attribute to V(false).
type: bool
default: false

14
plugins/modules/layman.py
View file

@ -15,8 +15,8 @@ module: layman
author: "Jakub Jirutka (@jirutka)"
short_description: Manage Gentoo overlays
description:
- Uses Layman to manage an additional repositories for the Portage package manager on Gentoo Linux. Please note that Layman must be installed
on a managed node prior using this module.
- Uses Layman to manage an additional repositories for the Portage package manager on Gentoo Linux. Please note that Layman
must be installed on a managed node prior using this module.
requirements:
- layman python module
extends_documentation_fragment:
@ -29,13 +29,14 @@ attributes:
options:
name:
description:
- The overlay id to install, synchronize, or uninstall. Use V(ALL) to sync all of the installed overlays (can be used only when O(state=updated)).
- The overlay ID to install, synchronize, or uninstall. Use V(ALL) to sync all of the installed overlays (can be used
only when O(state=updated)).
required: true
type: str
list_url:
description:
- An URL of the alternative overlays list that defines the overlay to install. This list will be fetched and saved under C(${overlay_defs}/${name}.xml),
where C(overlay_defs) is read from the Layman's configuration.
- An URL of the alternative overlays list that defines the overlay to install. This list will be fetched and saved under
C(${overlay_defs}/${name}.xml), where C(overlay_defs) is read from the Layman's configuration.
aliases: [url]
type: str
state:
@ -46,8 +47,7 @@ options:
type: str
validate_certs:
description:
- If V(false), SSL certificates will not be validated. This should only be set to V(false) when no other option exists. Prior to 1.9.3 the
code defaulted to V(false).
- If V(false), SSL certificates will not be validated. This should only be set to V(false) when no other option exists.
type: bool
default: true
"""

26
plugins/modules/ldap_attrs.py
View file

@ -19,9 +19,10 @@ description:
- Add or remove multiple LDAP attribute values.
notes:
- This only deals with attributes on existing entries. To add or remove whole entries, see M(community.general.ldap_entry).
- For O(state=present) and O(state=absent), all value comparisons are performed on the server for maximum accuracy. For O(state=exact), values
have to be compared in Python, which obviously ignores LDAP matching rules. This should work out in most cases, but it is theoretically possible
to see spurious changes when target and actual values are semantically identical but lexically distinct.
- For O(state=present) and O(state=absent), all value comparisons are performed on the server for maximum accuracy. For
O(state=exact), values have to be compared in Python, which obviously ignores LDAP matching rules. This should work out
in most cases, but it is theoretically possible to see spurious changes when target and actual values are semantically
identical but lexically distinct.
version_added: '0.2.0'
author:
- Jiri Tyr (@jtyr)
@ -42,26 +43,27 @@ options:
choices: [present, absent, exact]
default: present
description:
- The state of the attribute values. If V(present), all given attribute values will be added if they are missing. If V(absent), all given
attribute values will be removed if present. If V(exact), the set of attribute values will be forced to exactly those provided and no
others. If O(state=exact) and the attribute value is empty, all values for this attribute will be removed.
- The state of the attribute values. If V(present), all given attribute values will be added if they are missing. If
V(absent), all given attribute values will be removed if present. If V(exact), the set of attribute values will be
forced to exactly those provided and no others. If O(state=exact) and the attribute value is empty, all values for
this attribute will be removed.
attributes:
required: true
type: dict
description:
- The attribute(s) and value(s) to add or remove.
- Each attribute value can be a string for single-valued attributes or a list of strings for multi-valued attributes.
- If you specify values for this option in YAML, please note that you can improve readability for long string values by using YAML block
modifiers as seen in the examples for this module.
- Note that when using values that YAML/ansible-core interprets as other types, like V(yes), V(no) (booleans), or V(2.10) (float), make
sure to quote them if these are meant to be strings. Otherwise the wrong values may be sent to LDAP.
- If you specify values for this option in YAML, please note that you can improve readability for long string values
by using YAML block modifiers as seen in the examples for this module.
- Note that when using values that YAML/ansible-core interprets as other types, like V(yes), V(no) (booleans), or V(2.10)
(float), make sure to quote them if these are meant to be strings. Otherwise the wrong values may be sent to LDAP.
ordered:
required: false
type: bool
default: false
description:
- If V(true), prepend list values with X-ORDERED index numbers in all attributes specified in the current task. This is useful mostly with
C(olcAccess) attribute to easily manage LDAP Access Control Lists.
- If V(true), prepend list values with X-ORDERED index numbers in all attributes specified in the current task. This
is useful mostly with C(olcAccess) attribute to easily manage LDAP Access Control Lists.
extends_documentation_fragment:
- community.general.ldap.documentation
- community.general.attributes

19
plugins/modules/ldap_entry.py
View file

@ -15,8 +15,8 @@ DOCUMENTATION = r"""
module: ldap_entry
short_description: Add or remove LDAP entries
description:
- Add or remove LDAP entries. This module only asserts the existence or non-existence of an LDAP entry, not its attributes. To assert the attribute
values of an entry, see M(community.general.ldap_attrs).
- Add or remove LDAP entries. This module only asserts the existence or non-existence of an LDAP entry, not its attributes.
To assert the attribute values of an entry, see M(community.general.ldap_attrs).
author:
- Jiri Tyr (@jtyr)
requirements:
@ -29,18 +29,19 @@ attributes:
options:
attributes:
description:
- If O(state=present), attributes necessary to create an entry. Existing entries are never modified. To assert specific attribute values
on an existing entry, use M(community.general.ldap_attrs) module instead.
- If O(state=present), attributes necessary to create an entry. Existing entries are never modified. To assert specific
attribute values on an existing entry, use M(community.general.ldap_attrs) module instead.
- Each attribute value can be a string for single-valued attributes or a list of strings for multi-valued attributes.
- If you specify values for this option in YAML, please note that you can improve readability for long string values by using YAML block
modifiers as seen in the examples for this module.
- Note that when using values that YAML/ansible-core interprets as other types, like V(yes), V(no) (booleans), or V(2.10) (float), make
sure to quote them if these are meant to be strings. Otherwise the wrong values may be sent to LDAP.
- If you specify values for this option in YAML, please note that you can improve readability for long string values
by using YAML block modifiers as seen in the examples for this module.
- Note that when using values that YAML/ansible-core interprets as other types, like V(yes), V(no) (booleans), or V(2.10)
(float), make sure to quote them if these are meant to be strings. Otherwise the wrong values may be sent to LDAP.
type: dict
default: {}
objectClass:
description:
- If O(state=present), value or list of values to use when creating the entry. It can either be a string or an actual list of strings.
- If O(state=present), value or list of values to use when creating the entry. It can either be a string or an actual
list of strings.
type: list
elements: str
state:

33
plugins/modules/ldap_inc.py
View file

@ -15,25 +15,21 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: ldap_inc
short_description: Use the Modify-Increment LDAP V3 feature to increment an attribute value
version_added: 10.2.0
description:
- Atomically increments the value of an attribute and return its new value.
notes:
- When implemented by the directory server, the module uses the ModifyIncrement extension
defined in L(RFC4525, https://www.rfc-editor.org/rfc/rfc4525.html) and the control PostRead. This extension and the control are
implemented in OpenLdap but not all directory servers implement them. In this case, the
module automatically uses a more classic method based on two phases, first the current
value is read then the modify operation remove the old value and add the new one in a
single request. If the value has changed by a concurrent call then the remove action will
fail. Then the sequence is retried 3 times before raising an error to the playbook. In an
heavy modification environment, the module does not guarante to be systematically successful.
- This only deals with integer attribute of an existing entry. To modify attributes
of an entry, see M(community.general.ldap_attrs) or to add or remove whole entries,
see M(community.general.ldap_entry).
- When implemented by the directory server, the module uses the ModifyIncrement extension defined in L(RFC4525, https://www.rfc-editor.org/rfc/rfc4525.html)
and the control PostRead. This extension and the control are implemented in OpenLdap but not all directory servers implement
them. In this case, the module automatically uses a more classic method based on two phases, first the current value is
read then the modify operation remove the old value and add the new one in a single request. If the value has changed
by a concurrent call then the remove action will fail. Then the sequence is retried 3 times before raising an error to
the playbook. In an heavy modification environment, the module does not guarante to be systematically successful.
- This only deals with integer attribute of an existing entry. To modify attributes of an entry, see M(community.general.ldap_attrs)
or to add or remove whole entries, see M(community.general.ldap_entry).
author:
- Philippe Duveau (@pduveau)
requirements:
@ -71,11 +67,10 @@ options:
extends_documentation_fragment:
- community.general.ldap.documentation
- community.general.attributes
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Increments uidNumber 1 Number for example.com
community.general.ldap_inc:
dn: "cn=uidNext,ou=unix-management,dc=example,dc=com"
@ -90,10 +85,10 @@ EXAMPLES = r'''
attributes:
- uidNumber: "{{ ldap_uidNumber_sequence.value }}"
when: ldap_uidNumber_sequence.incremented
'''
"""
RETURN = r'''
RETURN = r"""
incremented:
description:
- It is set to V(true) if the attribute value has changed.
@ -121,7 +116,7 @@ rfc4525:
returned: success
type: bool
sample: true
'''
"""
from ansible.module_utils.basic import AnsibleModule, missing_required_lib
from ansible.module_utils.common.text.converters import to_native, to_bytes

4
plugins/modules/ldap_passwd.py
View file

@ -13,8 +13,8 @@ DOCUMENTATION = r"""
module: ldap_passwd
short_description: Set passwords in LDAP
description:
- Set a password for an LDAP entry. This module only asserts that a given password is valid for a given entry. To assert the existence of an
entry, see M(community.general.ldap_entry).
- Set a password for an LDAP entry. This module only asserts that a given password is valid for a given entry. To assert
the existence of an entry, see M(community.general.ldap_entry).
author:
- Keller Fuchs (@KellerFuchs)
requirements:

23
plugins/modules/ldap_search.py
View file

@ -52,21 +52,22 @@ options:
default: false
type: bool
description:
- Set to V(true) to return the full attribute schema of entries, not their attribute values. Overrides O(attrs) when provided.
- Set to V(true) to return the full attribute schema of entries, not their attribute values. Overrides O(attrs) when
provided.
page_size:
default: 0
type: int
description:
- The page size when performing a simple paged result search (RFC 2696). This setting can be tuned to reduce issues with timeouts and server
limits.
- The page size when performing a simple paged result search (RFC 2696). This setting can be tuned to reduce issues
with timeouts and server limits.
- Setting the page size to V(0) (default) disables paged searching.
version_added: 7.1.0
base64_attributes:
description:
- If provided, all attribute values returned that are listed in this option will be Base64 encoded.
- If the special value V(*) appears in this list, all attributes will be Base64 encoded.
- All other attribute values will be converted to UTF-8 strings. If they contain binary data, please note that invalid UTF-8 bytes will
be omitted.
- All other attribute values will be converted to UTF-8 strings. If they contain binary data, please note that invalid
UTF-8 bytes will be omitted.
type: list
elements: str
version_added: 7.0.0
@ -90,17 +91,15 @@ EXAMPLES = r"""
register: ldap_group_gids
"""
RESULTS = """
RESULTS = r"""
results:
description:
- For every entry found, one dictionary will be returned.
- Every dictionary contains a key C(dn) with the entry's DN as a value.
- Every attribute of the entry found is added to the dictionary. If the key
has precisely one value, that value is taken directly, otherwise the key's
value is a list.
- Note that all values (for single-element lists) and list elements (for multi-valued
lists) will be UTF-8 strings. Some might contain Base64-encoded binary data; which
ones is determined by the O(base64_attributes) option.
- Every attribute of the entry found is added to the dictionary. If the key has precisely one value, that value is taken
directly, otherwise the key's value is a list.
- Note that all values (for single-element lists) and list elements (for multi-valued lists) will be UTF-8 strings. Some
might contain Base64-encoded binary data; which ones is determined by the O(base64_attributes) option.
type: list
elements: dict
"""

9
plugins/modules/librato_annotation.py
View file

@ -13,7 +13,8 @@ DOCUMENTATION = r"""
module: librato_annotation
short_description: Create an annotation in Librato
description:
- Create an annotation event on the given annotation stream :name. If the annotation stream does not exist, it will be created automatically.
- Create an annotation event on the given annotation stream :name. If the annotation stream does not exist, it will be created
automatically.
author: "Seth Edwards (@Sedward)"
requirements: []
extends_documentation_fragment:
@ -49,13 +50,15 @@ options:
source:
type: str
description:
- A string which describes the originating source of an annotation when that annotation is tracked across multiple members of a population.
- A string which describes the originating source of an annotation when that annotation is tracked across multiple members
of a population.
required: false
description:
type: str
description:
- The description contains extra metadata about a particular annotation.
- The description should contain specifics on the individual annotation for example V(Deployed 9b562b2 shipped new feature foo!).
- The description should contain specifics on the individual annotation for example V(Deployed 9b562b2 shipped new feature
foo!).
required: false
start_time:
type: int

5
plugins/modules/linode.py
View file

@ -46,8 +46,9 @@ options:
default: ''
linode_id:
description:
- Unique ID of a linode server. This value is read-only in the sense that if you specify it on creation of a Linode it will not be used.
The Linode API generates these IDs and we can those generated value here to reference a Linode more specifically. This is useful for idempotence.
- Unique ID of a Linode server. This value is read-only in the sense that if you specify it on creation of a Linode
it will not be used. The Linode API generates these IDs and we can those generated value here to reference a Linode
more specifically. This is useful for idempotence.
aliases: [lid]
type: int
additional_disks:

16
plugins/modules/linode_v4.py
View file

@ -17,8 +17,8 @@ requirements:
author:
- Luke Murphy (@decentral1se)
notes:
- No Linode resizing is currently implemented. This module will, in time, replace the current Linode module which uses deprecated API bindings
on the Linode side.
- No Linode resizing is currently implemented. This module will, in time, replace the current Linode module which uses deprecated
API bindings on the Linode side.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -48,8 +48,8 @@ options:
required: true
group:
description:
- The group that the instance should be marked under. Please note, that group labelling is deprecated but still supported. The encouraged
method for marking instances is to use tags.
- The group that the instance should be marked under. Please note, that group labelling is deprecated but still supported.
The encouraged method for marking instances is to use tags.
type: str
private_ip:
description:
@ -65,8 +65,8 @@ options:
elements: str
root_pass:
description:
- The password for the root user. If not specified, one will be generated. This generated password will be available in the task success
JSON.
- The password for the root user. If not specified, one will be generated. This generated password will be available
in the task success JSON.
type: str
authorized_keys:
description:
@ -95,8 +95,8 @@ options:
version_added: 1.3.0
stackscript_data:
description:
- An object containing arguments to any User Defined Fields present in the StackScript used when creating the instance. Only valid when
a O(stackscript_id) is provided.
- An object containing arguments to any User Defined Fields present in the StackScript used when creating the instance.
Only valid when a O(stackscript_id) is provided.
- See U(https://www.linode.com/docs/api/stackscripts/).
type: dict
version_added: 1.3.0

6
plugins/modules/locale_gen.py
View file

@ -42,9 +42,9 @@ notes:
- When using glibc mechanism, it will manage locales by editing C(/etc/locale.gen) and running C(locale-gen).
- When using ubuntu_legacy mechanism, it will manage locales by editing C(/var/lib/locales/supported.d/local) and then running
C(locale-gen).
- Please note that the code path that uses ubuntu_legacy mechanism has not been tested for a while, because Ubuntu is already using
the glibc mechanism. There is no support for that, given our inability to test it. Therefore, that mechanism is B(deprecated)
and will be removed in community.general 13.0.0.
- Please note that the code path that uses ubuntu_legacy mechanism has not been tested for a while, because Ubuntu is already
using the glibc mechanism. There is no support for that, given our inability to test it. Therefore, that mechanism is
B(deprecated) and will be removed in community.general 13.0.0.
- Currently the module is B(only supported for Debian and Ubuntu) systems.
- This module requires the package C(locales) installed in Debian and Ubuntu systems.
"""

9
plugins/modules/lvg.py
View file

@ -38,8 +38,8 @@ options:
elements: str
pesize:
description:
- The size of the physical extent. O(pesize) must be a power of 2 of at least 1 sector (where the sector size is the largest sector size
of the PVs currently used in the VG), or at least 128KiB.
- The size of the physical extent. O(pesize) must be a power of 2 of at least 1 sector (where the sector size is the
largest sector size of the PVs currently used in the VG), or at least 128KiB.
- O(pesize) can be optionally suffixed by a UNIT (k/K/m/M/g/G), default unit is megabyte.
type: str
default: "4"
@ -63,8 +63,9 @@ options:
description:
- Control if the volume group exists and its state.
- The states V(active) and V(inactive) implies V(present) state. Added in 7.1.0.
- If V(active) or V(inactive), the module manages the VG's logical volumes current state. The module also handles the VG's autoactivation
state if supported unless when creating a volume group and the autoactivation option specified in O(vg_options).
- If V(active) or V(inactive), the module manages the VG's logical volumes current state. The module also handles the
VG's autoactivation state if supported unless when creating a volume group and the autoactivation option specified
in O(vg_options).
type: str
choices: [absent, present, active, inactive]
default: present

22
plugins/modules/lvol.py
View file

@ -38,16 +38,19 @@ options:
size:
type: str
description:
- The size of the logical volume, according to lvcreate(8) C(--size), by default in megabytes or optionally with one of [bBsSkKmMgGtTpPeE]
units; or according to lvcreate(8) --extents as a percentage of [VG|PVS|FREE|ORIGIN]; Float values must begin with a digit.
- When resizing, apart from specifying an absolute size you may, according to lvextend(8)|lvreduce(8) C(--size), specify the amount to extend
the logical volume with the prefix V(+) or the amount to reduce the logical volume by with prefix V(-).
- The size of the logical volume, according to lvcreate(8) C(--size), by default in megabytes or optionally with one
of [bBsSkKmMgGtTpPeE] units; or according to lvcreate(8) C(--extents) as a percentage of [VG|PVS|FREE|ORIGIN]; Float
values must begin with a digit.
- When resizing, apart from specifying an absolute size you may, according to lvextend(8)|lvreduce(8) C(--size), specify
the amount to extend the logical volume with the prefix V(+) or the amount to reduce the logical volume by with prefix
V(-).
- Resizing using V(+) or V(-) was not supported prior to community.general 3.0.0.
- Please note that when using V(+), V(-), or percentage of FREE, the module is B(not idempotent).
state:
type: str
description:
- Control if the logical volume exists. If V(present) and the volume does not already exist then the O(size) option is required.
- Control if the logical volume exists. If V(present) and the volume does not already exist then the O(size) option
is required.
choices: [absent, present]
default: present
active:
@ -57,7 +60,8 @@ options:
default: true
force:
description:
- Shrink or remove operations of volumes requires this switch. Ensures that that filesystems get never corrupted/destroyed by mistake.
- Shrink or remove operations of volumes requires this switch. Ensures that that filesystems get never corrupted/destroyed
by mistake.
type: bool
default: false
opts:
@ -67,7 +71,8 @@ options:
snapshot:
type: str
description:
- The name of a snapshot volume to be configured. When creating a snapshot volume, the O(lv) parameter specifies the origin volume.
- The name of a snapshot volume to be configured. When creating a snapshot volume, the O(lv) parameter specifies the
origin volume.
pvs:
type: list
elements: str
@ -85,7 +90,8 @@ options:
resizefs:
description:
- Resize the underlying filesystem together with the logical volume.
- Supported for C(ext2), C(ext3), C(ext4), C(reiserfs) and C(XFS) filesystems. Attempts to resize other filesystem types will fail.
- Supported for C(ext2), C(ext3), C(ext4), C(reiserfs) and C(XFS) filesystems. Attempts to resize other filesystem types
result in failure.
type: bool
default: false
notes:

27
plugins/modules/lxc_container.py
View file

@ -157,8 +157,8 @@ options:
description:
- Define the state of a container.
- If you clone a container using O(clone_name) the newly cloned container created in a stopped state.
- The running container will be stopped while the clone operation is happening and upon completion of the clone the original container state
will be restored.
- The running container will be stopped while the clone operation is happening and upon completion of the clone the
original container state will be restored.
type: str
default: started
container_config:
@ -171,17 +171,18 @@ requirements:
- 'python3 >= 3.5 # OS Package'
- 'python3-lxc # OS Package'
notes:
- Containers must have a unique name. If you attempt to create a container with a name that already exists in the users namespace the module
will simply return as "unchanged".
- The O(container_command) can be used with any state except V(absent). If used with state V(stopped) the container will be V(started), the
command executed, and then the container V(stopped) again. Likewise if O(state=stopped) and the container does not exist it will be first
created, V(started), the command executed, and then V(stopped). If you use a C(|) in the variable you can use common script formatting within
the variable itself. The O(container_command) option will always execute as C(bash). When using O(container_command), a log file is created in
the C(/tmp/) directory which contains both C(stdout) and C(stderr) of any command executed.
- If O(archive=true) the system will attempt to create a compressed tarball of the running container. The O(archive) option supports LVM backed
containers and will create a snapshot of the running container when creating the archive.
- If your distro does not have a package for C(python3-lxc), which is a requirement for this module, it can be installed from source at
U(https://github.com/lxc/python3-lxc) or installed using C(pip install lxc).
- Containers must have a unique name. If you attempt to create a container with a name that already exists in the users
namespace the module will simply return as "unchanged".
- The O(container_command) can be used with any state except V(absent). If used with state V(stopped) the container will
be V(started), the command executed, and then the container V(stopped) again. Likewise if O(state=stopped) and the container
does not exist it will be first created, V(started), the command executed, and then V(stopped). If you use a C(|) in the
variable you can use common script formatting within the variable itself. The O(container_command) option will always
execute as C(bash). When using O(container_command), a log file is created in the C(/tmp/) directory which contains both
C(stdout) and C(stderr) of any command executed.
- If O(archive=true) the system will attempt to create a compressed tarball of the running container. The O(archive) option
supports LVM backed containers and will create a snapshot of the running container when creating the archive.
- If your distro does not have a package for C(python3-lxc), which is a requirement for this module, it can be installed
from source at U(https://github.com/lxc/python3-lxc) or installed using C(pip install lxc).
"""
EXAMPLES = r"""

46
plugins/modules/lxd_container.py
View file

@ -45,8 +45,8 @@ options:
required: false
config:
description:
- 'The config for the instance (for example V({"limits.cpu": "2"})).
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).'
- 'The config for the instance (for example V({"limits.cpu": "2"})).'
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).
- If the instance already exists and its "config" values in metadata obtained from the LXD API
U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get)
are different, then this module tries to apply the configurations U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_put).
@ -69,8 +69,8 @@ options:
elements: str
devices:
description:
- 'The devices for the instance (for example V({ "rootfs": { "path": "/dev/kvm", "type": "unix-char" }})).
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).'
- 'The devices for the instance (for example V({ "rootfs": { "path": "/dev/kvm", "type": "unix-char" }})).'
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).
type: dict
required: false
ephemeral:
@ -101,16 +101,17 @@ options:
type: str
target:
description:
- For cluster deployments. Will attempt to create an instance on a target node. If the instance exists elsewhere in a cluster, then it will
not be replaced or moved. The name should respond to same name of the node you see in C(lxc cluster list).
- For cluster deployments. Will attempt to create an instance on a target node. If the instance exists elsewhere in
a cluster, then it will not be replaced or moved. The name should respond to same name of the node you see in C(lxc
cluster list).
type: str
required: false
version_added: 1.0.0
timeout:
description:
- A timeout for changing the state of the instance.
- This is also used as a timeout for waiting until IPv4 addresses are set to the all network interfaces in the instance after starting or
restarting.
- This is also used as a timeout for waiting until IPv4 addresses are set to the all network interfaces in the instance
after starting or restarting.
required: false
default: 30
type: int
@ -126,8 +127,8 @@ options:
version_added: 4.1.0
wait_for_ipv4_addresses:
description:
- If this is V(true), the C(lxd_container) waits until IPv4 addresses are set to the all network interfaces in the instance after starting
or restarting.
- If this is V(true), the C(lxd_container) waits until IPv4 addresses are set to the all network interfaces in the instance
after starting or restarting.
required: false
default: false
type: bool
@ -172,20 +173,21 @@ options:
trust_password:
description:
- The client trusted password.
- 'You need to set this password on the LXD server before running this module using the following command: C(lxc config set core.trust_password
<some random password>). See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).'
- 'You need to set this password on the LXD server before running this module using the following command: C(lxc config
set core.trust_password <some random password>). See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).'
- If trust_password is set, this module send a request for authentication before sending any requests.
required: false
type: str
notes:
- Instances can be a container or a virtual machine, both of them must have unique name. If you attempt to create an instance with a name that
already existed in the users namespace the module will simply return as "unchanged".
- There are two ways to run commands inside a container or virtual machine, using the command module or using the ansible lxd connection plugin
bundled in Ansible >= 2.1, the later requires python to be installed in the instance which can be done with the command module.
- You can copy a file from the host to the instance with the Ansible M(ansible.builtin.copy) and M(ansible.builtin.template) module and the
P(community.general.lxd#connection) connection plugin. See the example below.
- You can copy a file in the created instance to the localhost with C(command=lxc file pull instance_name/dir/filename filename). See the first
example below.
- Instances can be a container or a virtual machine, both of them must have unique name. If you attempt to create an instance
with a name that already existed in the users namespace the module will simply return as "unchanged".
- There are two ways to run commands inside a container or virtual machine, using the command module or using the ansible
lxd connection plugin bundled in Ansible >= 2.1, the later requires python to be installed in the instance which can be
done with the command module.
- You can copy a file from the host to the instance with the Ansible M(ansible.builtin.copy) and M(ansible.builtin.template)
module and the P(community.general.lxd#connection) connection plugin. See the example below.
- You can copy a file in the created instance to the localhost with C(command=lxc file pull instance_name/dir/filename filename).
See the first example below.
- Linuxcontainers.org has phased out LXC/LXD support with March 2024
(U(https://discuss.linuxcontainers.org/t/important-notice-for-lxd-users-image-server/18479)).
Currently only Ubuntu is still providing images.
@ -316,8 +318,8 @@ EXAMPLES = r"""
community.general.lxd_container:
url: https://127.0.0.1:8443
# These client_cert and client_key values are equal to the default values.
#client_cert: "{{ lookup('env', 'HOME') }}/.config/lxc/client.crt"
#client_key: "{{ lookup('env', 'HOME') }}/.config/lxc/client.key"
# client_cert: "{{ lookup('env', 'HOME') }}/.config/lxc/client.crt"
# client_key: "{{ lookup('env', 'HOME') }}/.config/lxc/client.key"
trust_password: mypassword
name: mycontainer
state: restarted

22
plugins/modules/lxd_profile.py
View file

@ -40,8 +40,8 @@ options:
type: str
config:
description:
- 'The config for the instance (for example V({"limits.memory": "4GB"})).
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get).'
- 'The config for the instance (for example V({"limits.memory": "4GB"})).'
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get).
- If the profile already exists and its C(config) value in metadata obtained from GET /1.0/profiles/<name>
U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get)
are different, then this module tries to apply the configurations U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_put).
@ -50,8 +50,8 @@ options:
type: dict
devices:
description:
- 'The devices for the profile (for example V({"rootfs": {"path": "/dev/kvm", "type": "unix-char"})).
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get).'
- 'The devices for the profile (for example V({"rootfs": {"path": "/dev/kvm", "type": "unix-char"})).'
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get).
required: false
type: dict
new_name:
@ -106,14 +106,14 @@ options:
trust_password:
description:
- The client trusted password.
- You need to set this password on the LXD server before running this module using the following command. lxc config set core.trust_password
<some random password> See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).
- If trust_password is set, this module send a request for authentication before sending any requests.
- 'You need to set this password on the LXD server before running this module using the following command: C(lxc config
set core.trust_password <some random password>). See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).'
- If O(trust_password) is set, this module send a request for authentication before sending any requests.
required: false
type: str
notes:
- Profiles must have a unique name. If you attempt to create a profile with a name that already existed in the users namespace the module will
simply return as "unchanged".
- Profiles must have a unique name. If you attempt to create a profile with a name that already existed in the users namespace
the module will simply return as "unchanged".
"""
EXAMPLES = r"""
@ -154,8 +154,8 @@ EXAMPLES = r"""
community.general.lxd_profile:
url: https://127.0.0.1:8443
# These client_cert and client_key values are equal to the default values.
#client_cert: "{{ lookup('env', 'HOME') }}/.config/lxc/client.crt"
#client_key: "{{ lookup('env', 'HOME') }}/.config/lxc/client.key"
# client_cert: "{{ lookup('env', 'HOME') }}/.config/lxc/client.crt"
# client_key: "{{ lookup('env', 'HOME') }}/.config/lxc/client.key"
trust_password: mypassword
name: macvlan
state: present

16
plugins/modules/lxd_project.py
View file

@ -33,8 +33,8 @@ options:
type: str
config:
description:
- 'The config for the project (for example V({"features.profiles": "true"})).
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_get).'
- 'The config for the project (for example V({"features.profiles": "true"})).'
- See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_get).
- If the project already exists and its "config" value in metadata obtained from C(GET /1.0/projects/<name>)
U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_get)
are different, then this module tries to apply the configurations U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_put).
@ -48,8 +48,8 @@ options:
type: str
merge_project:
description:
- Merge the configuration of the present project with the new desired configuration, instead of replacing it. If configuration is the same
after merged, no change will be made.
- Merge the configuration of the present project with the new desired configuration, instead of replacing it. If configuration
is the same after merged, no change will be made.
required: false
default: false
type: bool
@ -91,14 +91,14 @@ options:
trust_password:
description:
- The client trusted password.
- 'You need to set this password on the LXD server before running this module using the following command: C(lxc config set core.trust_password
<some random password>) See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).'
- 'You need to set this password on the LXD server before running this module using the following command: C(lxc config
set core.trust_password <some random password>) See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).'
- If O(trust_password) is set, this module send a request for authentication before sending any requests.
required: false
type: str
notes:
- Projects must have a unique name. If you attempt to create a project with a name that already existed in the users namespace the module will
simply return as "unchanged".
- Projects must have a unique name. If you attempt to create a project with a name that already existed in the users namespace
the module will simply return as "unchanged".
"""
EXAMPLES = r"""

19
plugins/modules/mail.py
View file

@ -16,12 +16,12 @@ module: mail
short_description: Send an email
description:
- This module is useful for sending emails from playbooks.
- One may wonder why automate sending emails? In complex environments there are from time to time processes that cannot be automated, either
because you lack the authority to make it so, or because not everyone agrees to a common approach.
- If you cannot automate a specific step, but the step is non-blocking, sending out an email to the responsible party to make them perform their
part of the bargain is an elegant way to put the responsibility in someone else's lap.
- Of course sending out a mail can be equally useful as a way to notify one or more people in a team that a specific action has been (successfully)
taken.
- One may wonder why automate sending emails? In complex environments there are from time to time processes that cannot
be automated, either because you lack the authority to make it so, or because not everyone agrees to a common approach.
- If you cannot automate a specific step, but the step is non-blocking, sending out an email to the responsible party to
make them perform their part of the bargain is an elegant way to put the responsibility in someone else's lap.
- Of course sending out a mail can be equally useful as a way to notify one or more people in a team that a specific action
has been (successfully) taken.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -115,11 +115,12 @@ options:
default: plain
secure:
description:
- If V(always), the connection will only send email if the connection is Encrypted. If the server does not accept the encrypted connection
it will fail.
- If V(always), the connection will only send email if the connection is Encrypted. If the server does not accept the
encrypted connection it will fail.
- If V(try), the connection will attempt to setup a secure SSL/TLS session, before trying to send.
- If V(never), the connection will not attempt to setup a secure SSL/TLS session, before sending.
- If V(starttls), the connection will try to upgrade to a secure SSL/TLS connection, before sending. If it is unable to do so it will fail.
- If V(starttls), the connection will try to upgrade to a secure SSL/TLS connection, before sending. If it is unable
to do so it will fail.
type: str
choices: [always, never, starttls, try]
default: try

6
plugins/modules/manageiq_group.py
View file

@ -44,7 +44,7 @@ options:
role_id:
type: int
description:
- The the group role id.
- The the group role ID.
required: false
role:
type: str
@ -56,7 +56,7 @@ options:
tenant_id:
type: int
description:
- The tenant for the group identified by the tenant id.
- The tenant for the group identified by the tenant ID.
required: false
default:
tenant:
@ -172,7 +172,7 @@ group:
returned: success
type: str
id:
description: The group id.
description: The group ID.
returned: success
type: int
group_type:

8
plugins/modules/manageiq_policies.py
View file

@ -45,8 +45,8 @@ options:
description:
- The type of the resource to which the profile should be [un]assigned.
required: true
choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster', 'data store', 'group', 'resource pool', 'service', 'service template',
'template', 'tenant', 'user']
choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster', 'data store', 'group', 'resource pool', 'service',
'service template', 'template', 'tenant', 'user']
resource_name:
type: str
description:
@ -93,7 +93,7 @@ manageiq_policies:
- List current policy_profile and policies for a provider in ManageIQ.
returned: always
type: dict
sample: '{
sample: {
"changed": false,
"profiles": [
{
@ -118,7 +118,7 @@ manageiq_policies:
"profile_name": "openscap profile"
}
]
}'
}
"""
from ansible.module_utils.basic import AnsibleModule

4
plugins/modules/manageiq_policies_info.py
View file

@ -29,8 +29,8 @@ options:
description:
- The type of the resource to obtain the profile for.
required: true
choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster', 'data store', 'group', 'resource pool', 'service', 'service template',
'template', 'tenant', 'user']
choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster', 'data store', 'group', 'resource pool', 'service',
'service template', 'template', 'tenant', 'user']
resource_name:
type: str
description:

4
plugins/modules/manageiq_tags.py
View file

@ -45,8 +45,8 @@ options:
description:
- The relevant resource type in manageiq.
required: true
choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster', 'data store', 'group', 'resource pool', 'service', 'service template',
'template', 'tenant', 'user']
choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster', 'data store', 'group', 'resource pool', 'service',
'service template', 'template', 'tenant', 'user']
resource_name:
type: str
description:

4
plugins/modules/manageiq_tags_info.py
View file

@ -27,8 +27,8 @@ options:
description:
- The relevant resource type in ManageIQ.
required: true
choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster', 'data store', 'group', 'resource pool', 'service', 'service template',
'template', 'tenant', 'user']
choices: ['provider', 'host', 'vm', 'blueprint', 'category', 'cluster', 'data store', 'group', 'resource pool', 'service',
'service template', 'template', 'tenant', 'user']
resource_name:
type: str
description:

6
plugins/modules/manageiq_tenant.py
View file

@ -49,7 +49,7 @@ options:
parent_id:
type: int
description:
- The id of the parent tenant. If not supplied the root tenant is used.
- The ID of the parent tenant. If not supplied the root tenant is used.
- The O(parent_id) takes president over O(parent) when supplied.
required: false
default:
@ -140,7 +140,7 @@ tenant:
type: complex
contains:
id:
description: The tenant id.
description: The tenant ID.
returned: success
type: int
name:
@ -152,7 +152,7 @@ tenant:
returned: success
type: str
parent_id:
description: The id of the parent tenant.
description: The ID of the parent tenant.
returned: success
type: int
quotas:

2
plugins/modules/matrix.py
View file

@ -49,7 +49,7 @@ options:
user_id:
type: str
description:
- The user id of the user.
- The user ID of the user.
password:
type: str
description:

9
plugins/modules/mattermost.py
View file

@ -32,13 +32,13 @@ options:
url:
type: str
description:
- Mattermost url (for example V(http://mattermost.yourcompany.com)).
- Mattermost URL (for example V(http://mattermost.yourcompany.com)).
required: true
api_key:
type: str
description:
- Mattermost webhook API key. Log into your Mattermost site, go to Menu -> Integration -> Incoming Webhook -> Add Incoming Webhook. This
will give you full URL. O(api_key) is the last part. U(http://mattermost.example.com/hooks/API_KEY).
- Mattermost webhook API key. Log into your Mattermost site, go to Menu -> Integration -> Incoming Webhook -> Add Incoming
Webhook. This will give you full URL. O(api_key) is the last part. U(http://mattermost.example.com/hooks/API_KEY).
required: true
text:
type: str
@ -75,7 +75,8 @@ options:
version_added: 10.0.0
validate_certs:
description:
- If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates.
- If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using
self-signed certificates.
default: true
type: bool
"""

28
plugins/modules/maven_artifact.py
View file

@ -16,7 +16,8 @@ module: maven_artifact
short_description: Downloads an Artifact from a Maven Repository
description:
- Downloads an artifact from a maven repository given the maven coordinates provided to the module.
- Can retrieve snapshots or release versions of the artifact and will resolve the latest available version if one is not available.
- Can retrieve snapshots or release versions of the artifact and will resolve the latest available version if one is not
available.
author: "Chris Schmidt (@chrisisbeef)"
requirements:
- lxml
@ -75,7 +76,8 @@ options:
password:
type: str
description:
- The password to authenticate with to the Maven Repository. Use AWS secret access key of the repository is hosted on S3.
- The password to authenticate with to the Maven Repository. Use AWS secret access key of the repository is hosted on
S3.
aliases: ["aws_secret_access_key"]
headers:
description:
@ -83,9 +85,9 @@ options:
type: dict
force_basic_auth:
description:
- Httplib2, the library used by the uri module only sends authentication information when a webservice responds to an initial request with
a 401 status. Since some basic auth services do not properly send a 401, logins will fail. This option forces the sending of the Basic
authentication header upon initial request.
- C(httplib2), the library used by the URI module only sends authentication information when a webservice responds to an
initial request with a 401 status. Since some basic auth services do not properly send a 401, logins will fail. This
option forces the sending of the Basic authentication header upon initial request.
default: false
type: bool
version_added: '0.2.0'
@ -126,7 +128,8 @@ options:
keep_name:
description:
- If V(true), the downloaded artifact's name is preserved, in other words the version number remains part of it.
- This option only has effect when O(dest) is a directory and O(version) is set to V(latest) or O(version_by_spec) is defined.
- This option only has effect when O(dest) is a directory and O(version) is set to V(latest) or O(version_by_spec) is
defined.
type: bool
default: false
verify_checksum:
@ -134,10 +137,11 @@ options:
description:
- If V(never), the MD5/SHA1 checksum will never be downloaded and verified.
- If V(download), the MD5/SHA1 checksum will be downloaded and verified only after artifact download. This is the default.
- If V(change), the MD5/SHA1 checksum will be downloaded and verified if the destination already exist, to verify if they are identical.
This was the behaviour before 2.6. Since it downloads the checksum before (maybe) downloading the artifact, and since some repository
software, when acting as a proxy/cache, return a 404 error if the artifact has not been cached yet, it may fail unexpectedly. If you still
need it, you should consider using V(always) instead - if you deal with a checksum, it is better to use it to verify integrity after download.
- If V(change), the MD5/SHA1 checksum will be downloaded and verified if the destination already exist, to verify if
they are identical. This was the behaviour before 2.6. Since it downloads the checksum before (maybe) downloading
the artifact, and since some repository software, when acting as a proxy/cache, return a 404 error if the artifact
has not been cached yet, it may fail unexpectedly. If you still need it, you should consider using V(always) instead
- if you deal with a checksum, it is better to use it to verify integrity after download.
- V(always) combines V(download) and V(change).
required: false
default: 'download'
@ -146,8 +150,8 @@ options:
type: str
description:
- If V(md5), checksums will use the MD5 algorithm. This is the default.
- If V(sha1), checksums will use the SHA1 algorithm. This can be used on systems configured to use FIPS-compliant algorithms, since MD5
will be blocked on such systems.
- If V(sha1), checksums will use the SHA1 algorithm. This can be used on systems configured to use FIPS-compliant algorithms,
since MD5 will be blocked on such systems.
default: 'md5'
choices: ['md5', 'sha1']
version_added: 3.2.0

13
plugins/modules/memset_dns_reload.py
View file

@ -13,10 +13,10 @@ module: memset_dns_reload
author: "Simon Weald (@glitchcrab)"
short_description: Request reload of Memset's DNS infrastructure,
notes:
- DNS reload requests are a best-effort service provided by Memset; these generally happen every 15 minutes by default, however you can request
an immediate reload if later tasks rely on the records being created. An API key generated using the Memset customer control panel is required
with the following minimum scope - C(dns.reload). If you wish to poll the job status to wait until the reload has completed, then C(job.status)
is also required.
- DNS reload requests are a best-effort service provided by Memset; these generally happen every 15 minutes by default,
however you can request an immediate reload if later tasks rely on the records being created. An API key generated using
the Memset customer control panel is required with the following minimum scope - C(dns.reload). If you wish to poll the
job status to wait until the reload has completed, then C(job.status) is also required.
description:
- Request a reload of Memset's DNS infrastructure, and optionally poll until it finishes.
extends_documentation_fragment:
@ -36,8 +36,9 @@ options:
default: false
type: bool
description:
- Boolean value, if set will poll the reload job's status and return when the job has completed (unless the 30 second timeout is reached
first). If the timeout is reached then the task will not be marked as failed, but stderr will indicate that the polling failed.
- Boolean value, if set will poll the reload job's status and return when the job has completed (unless the 30 second
timeout is reached first). If the timeout is reached then the task will not be marked as failed, but stderr will indicate
that the polling failed.
"""
EXAMPLES = r"""

7
plugins/modules/memset_zone.py
View file

@ -13,8 +13,9 @@ module: memset_zone
author: "Simon Weald (@glitchcrab)"
short_description: Creates and deletes Memset DNS zones
notes:
- Zones can be thought of as a logical group of domains, all of which share the same DNS records (in other words they point to the same IP). An API key
generated using the Memset customer control panel is needed with the following minimum scope - C(dns.zone_create), C(dns.zone_delete), C(dns.zone_list).
- Zones can be thought of as a logical group of domains, all of which share the same DNS records (in other words they point
to the same IP). An API key generated using the Memset customer control panel is needed with the following minimum scope
- C(dns.zone_create), C(dns.zone_delete), C(dns.zone_list).
description:
- Manage DNS zones in a Memset account.
extends_documentation_fragment:
@ -88,7 +89,7 @@ memset_api:
type: list
sample: []
id:
description: Zone id.
description: Zone ID.
returned: always
type: str
sample: "b0bb1ce851aeea6feeb2dc32fe83bf9c"

6
plugins/modules/memset_zone_domain.py
View file

@ -13,9 +13,9 @@ module: memset_zone_domain
author: "Simon Weald (@glitchcrab)"
short_description: Create and delete domains in Memset DNS zones
notes:
- Zone domains can be thought of as a collection of domains, all of which share the same DNS records (in other words, they point to the same IP). An API
key generated using the Memset customer control panel is needed with the following minimum scope - C(dns.zone_domain_create), C(dns.zone_domain_delete),
C(dns.zone_domain_list).
- Zone domains can be thought of as a collection of domains, all of which share the same DNS records (in other words, they
point to the same IP). An API key generated using the Memset customer control panel is needed with the following minimum
scope - C(dns.zone_domain_create), C(dns.zone_domain_delete), C(dns.zone_domain_list).
- Currently this module can only create one domain at a time. Multiple domains should be created using C(loop).
description:
- Manage DNS zone domains in a Memset account.

5
plugins/modules/memset_zone_record.py
View file

@ -13,8 +13,9 @@ module: memset_zone_record
author: "Simon Weald (@glitchcrab)"
short_description: Create and delete records in Memset DNS zones
notes:
- Zones can be thought of as a logical group of domains, all of which share the same DNS records (in other words they point to the same IP). An API key
generated using the Memset customer control panel is needed with the following minimum scope - C(dns.zone_create), C(dns.zone_delete), C(dns.zone_list).
- Zones can be thought of as a logical group of domains, all of which share the same DNS records (in other words they point
to the same IP). An API key generated using the Memset customer control panel is needed with the following minimum scope
- C(dns.zone_create), C(dns.zone_delete), C(dns.zone_list).
- Currently this module can only create one DNS record at a time. Multiple records should be created using C(loop).
description:
- Manage DNS records in a Memset account.

14
plugins/modules/modprobe.py
View file

@ -48,13 +48,15 @@ options:
version_added: 7.0.0
description:
- Persistency between reboots for configured module.
- This option creates files in C(/etc/modules-load.d/) and C(/etc/modprobe.d/) that make your module configuration persistent during reboots.
- If V(present), adds module name to C(/etc/modules-load.d/) and params to C(/etc/modprobe.d/) so the module will be loaded on next reboot.
- If V(absent), will comment out module name from C(/etc/modules-load.d/) and comment out params from C(/etc/modprobe.d/) so the module
will not be loaded on next reboot.
- This option creates files in C(/etc/modules-load.d/) and C(/etc/modprobe.d/) that make your module configuration persistent
during reboots.
- If V(present), adds module name to C(/etc/modules-load.d/) and params to C(/etc/modprobe.d/) so the module will be
loaded on next reboot.
- If V(absent), will comment out module name from C(/etc/modules-load.d/) and comment out params from C(/etc/modprobe.d/)
so the module will not be loaded on next reboot.
- If V(disabled), will not touch anything and leave C(/etc/modules-load.d/) and C(/etc/modprobe.d/) as it is.
- Note that it is usually a better idea to rely on the automatic module loading by PCI IDs, USB IDs, DMI IDs or similar triggers encoded
in the kernel modules themselves instead of configuration like this.
- Note that it is usually a better idea to rely on the automatic module loading by PCI IDs, USB IDs, DMI IDs or similar
triggers encoded in the kernel modules themselves instead of configuration like this.
- In fact, most modern kernel modules are prepared for automatic loading already.
- B(Note:) This option works only with distributions that use C(systemd) when set to values other than V(disabled).
"""

4
plugins/modules/monit.py
View file

@ -35,8 +35,8 @@ options:
type: str
timeout:
description:
- If there are pending actions for the service monitored by monit, then Ansible will check for up to this many seconds to verify the requested
action has been performed. Ansible will sleep for five seconds between each check.
- If there are pending actions for the service monitored by monit, then Ansible will check for up to this many seconds
to verify the requested action has been performed. Ansible will sleep for five seconds between each check.
default: 300
type: int
author:

25
plugins/modules/mqtt.py
View file

@ -53,8 +53,8 @@ options:
payload:
type: str
description:
- Payload. The special string V("None") may be used to send a NULL (that is, empty) payload which is useful to simply notify with the O(topic)
or to clear previously retained messages.
- Payload. The special string V("None") may be used to send a NULL (that is, empty) payload which is useful to simply
notify with the O(topic) or to clear previously retained messages.
required: true
qos:
type: str
@ -64,29 +64,30 @@ options:
choices: ["0", "1", "2"]
retain:
description:
- Setting this flag causes the broker to retain (in other words keep) the message so that applications that subsequently subscribe to the topic can
received the last retained message immediately.
- Setting this flag causes the broker to retain (in other words keep) the message so that applications that subsequently
subscribe to the topic can received the last retained message immediately.
type: bool
default: false
ca_cert:
type: path
description:
- The path to the Certificate Authority certificate files that are to be treated as trusted by this client. If this is the only option given
then the client will operate in a similar manner to a web browser. That is to say it will require the broker to have a certificate signed
by the Certificate Authorities in ca_certs and will communicate using TLS v1, but will not attempt any form of authentication. This provides
basic network encryption but may not be sufficient depending on how the broker is configured.
- The path to the Certificate Authority certificate files that are to be treated as trusted by this client. If this
is the only option given then the client will operate in a similar manner to a web browser. That is to say it will
require the broker to have a certificate signed by the Certificate Authorities in ca_certs and will communicate using
TLS v1, but will not attempt any form of authentication. This provides basic network encryption but may not be sufficient
depending on how the broker is configured.
aliases: [ca_certs]
client_cert:
type: path
description:
- The path pointing to the PEM encoded client certificate. If this is not None it will be used as client information for TLS based authentication.
Support for this feature is broker dependent.
- The path pointing to the PEM encoded client certificate. If this is not None it will be used as client information
for TLS based authentication. Support for this feature is broker dependent.
aliases: [certfile]
client_key:
type: path
description:
- The path pointing to the PEM encoded client private key. If this is not None it will be used as client information for TLS based authentication.
Support for this feature is broker dependent.
- The path pointing to the PEM encoded client private key. If this is not None it will be used as client information
for TLS based authentication. Support for this feature is broker dependent.
aliases: [keyfile]
tls_version:
description:

7
plugins/modules/mssql_db.py
View file

@ -57,12 +57,13 @@ options:
type: str
target:
description:
- Location, on the remote host, of the dump file to read from or write to. Uncompressed SQL files (C(.sql)) files are supported.
- Location, on the remote host, of the dump file to read from or write to. Uncompressed SQL files (C(.sql)) files are
supported.
type: str
autocommit:
description:
- Automatically commit the change only if the import succeed. Sometimes it is necessary to use autocommit=true, since some content can not
be changed within a transaction.
- Automatically commit the change only if the import succeed. Sometimes it is necessary to use autocommit=true, since
some content can not be changed within a transaction.
type: bool
default: false
notes:

7
plugins/modules/mssql_script.py
View file

@ -56,7 +56,8 @@ options:
type: str
transaction:
description:
- If transactional mode is requested, start a transaction and commit the change only if the script succeed. Otherwise, rollback the transaction.
- If transactional mode is requested, start a transaction and commit the change only if the script succeed. Otherwise,
rollback the transaction.
- If transactional mode is not requested (default), automatically commit the change.
type: bool
default: false
@ -201,8 +202,8 @@ query_results_dict:
queries:
description:
- List of result sets of each query.
- If a query returns no results, the results of this and all the following queries will not be included in the output. Use 'GO' keyword
to separate queries.
- If a query returns no results, the results of this and all the following queries will not be included in the output.
Use V(GO) keyword to separate queries.
type: list
elements: list
contains:

16
plugins/modules/nagios.py
View file

@ -20,13 +20,13 @@ short_description: Perform common tasks in Nagios related to downtime and notifi
description:
- 'The C(nagios) module has two basic functions: scheduling downtime and toggling alerts for services or hosts.'
- The C(nagios) module is not idempotent.
- All actions require the O(host) parameter to be given explicitly. In playbooks you can use the C({{inventory_hostname}}) variable to refer
to the host the playbook is currently running on.
- All actions require the O(host) parameter to be given explicitly. In playbooks you can use the C({{inventory_hostname}})
variable to refer to the host the playbook is currently running on.
- You can specify multiple services at once by separating them with commas, for example O(services=httpd,nfs,puppet).
- When specifying what service to handle there is a special service value, O(host), which will handle alerts/downtime/acknowledge for the I(host
itself), for example O(services=host). This keyword may not be given with other services at the same time. B(Setting alerts/downtime/acknowledge
for a host does not affect alerts/downtime/acknowledge for any of the services running on it.) To schedule downtime for all services on particular
host use keyword "all", for example O(services=all).
- When specifying what service to handle there is a special service value, O(host), which will handle alerts/downtime/acknowledge
for the I(host itself), for example O(services=host). This keyword may not be given with other services at the same time.
B(Setting alerts/downtime/acknowledge for a host does not affect alerts/downtime/acknowledge for any of the services running
on it.) To schedule downtime for all services on particular host use keyword "all", for example O(services=all).
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -40,8 +40,8 @@ options:
- Action to take.
- The V(acknowledge) and V(forced_check) actions were added in community.general 1.2.0.
required: true
choices: ["downtime", "delete_downtime", "enable_alerts", "disable_alerts", "silence", "unsilence", "silence_nagios", "unsilence_nagios",
"command", "servicegroup_service_downtime", "servicegroup_host_downtime", "acknowledge", "forced_check"]
choices: ["downtime", "delete_downtime", "enable_alerts", "disable_alerts", "silence", "unsilence", "silence_nagios",
"unsilence_nagios", "command", "servicegroup_service_downtime", "servicegroup_host_downtime", "acknowledge", "forced_check"]
type: str
host:
description:

4
plugins/modules/netcup_dns.py
View file

@ -35,7 +35,7 @@ options:
type: str
customer_id:
description:
- Netcup customer id.
- Netcup customer ID.
required: true
type: int
domain:
@ -184,7 +184,7 @@ records:
type: int
sample: 0
id:
description: Internal id of the record.
description: Internal ID of the record.
returned: success
type: int
sample: 12345

7
plugins/modules/newrelic_deployment.py
View file

@ -62,15 +62,16 @@ options:
required: false
validate_certs:
description:
- If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates.
- If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using
self-signed certificates.
required: false
default: true
type: bool
app_name_exact_match:
type: bool
description:
- If this flag is set to V(true) then the application ID lookup by name would only work for an exact match. If set to V(false) it returns
the first result.
- If this flag is set to V(true) then the application ID lookup by name would only work for an exact match. If set to
V(false) it returns the first result.
required: false
default: false
version_added: 7.5.0

3
plugins/modules/nexmo.py
View file

@ -49,7 +49,8 @@ options:
required: true
validate_certs:
description:
- If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates.
- If V(false), SSL certificates will not be validated. This should only be used on personally controlled sites using
self-signed certificates.
type: bool
default: true
extends_documentation_fragment:

4
plugins/modules/nginx_status_info.py
View file

@ -62,8 +62,8 @@ accepts:
type: int
sample: 81769947
handled:
description: The total number of handled connections. Generally, the parameter value is the same as accepts unless some resource limits have
been reached.
description: The total number of handled connections. Generally, the parameter value is the same as accepts unless some
resource limits have been reached.
returned: success
type: int
sample: 81769947

287
plugins/modules/nmcli.py
View file

@ -19,7 +19,8 @@ requirements:
extends_documentation_fragment:
- community.general.attributes
description:
- Manage the network devices. Create, modify and manage various connection and device type, for example V(ethernet), V(team), V(bond), V(vlan) and so on.
- Manage the network devices. Create, modify and manage various connection and device type, for example V(ethernet), V(team),
V(bond), V(vlan) and so on.
- 'On CentOS 8 and Fedora >=29 like systems, the requirements can be met by installing the following packages: NetworkManager.'
- 'On CentOS 7 and Fedora <=28 like systems, the requirements can be met by installing the following packages: NetworkManager-tui.'
- 'On Ubuntu and Debian like systems, the requirements can be met by installing the following packages: network-manager.'
@ -34,8 +35,8 @@ options:
description:
- Whether the device should exist or not, taking action if the state is different from what is stated.
- Using O(state=present) to create connection will automatically bring connection up.
- Using O(state=up) and O(state=down) will not modify connection with other parameters. These states have been added in community.general
9.5.0.
- Using O(state=up) and O(state=down) will not modify connection with other parameters. These states have been added
in community.general 9.5.0.
type: str
required: true
choices: [absent, present, up, down]
@ -78,11 +79,13 @@ options:
- Type V(ovs-port) is added in community.general 8.6.0.
- Type V(wireguard) is added in community.general 4.3.0.
- Type V(vpn) is added in community.general 5.1.0.
- Using V(bond-slave), V(bridge-slave), or V(team-slave) implies V(ethernet) connection type with corresponding O(slave_type) option.
- If you want to control non-ethernet connection attached to V(bond), V(bridge), or V(team) consider using O(slave_type) option.
- Using V(bond-slave), V(bridge-slave), or V(team-slave) implies V(ethernet) connection type with corresponding O(slave_type)
option.
- If you want to control non-ethernet connection attached to V(bond), V(bridge), or V(team) consider using O(slave_type)
option.
type: str
choices: [bond, bond-slave, bridge, bridge-slave, dummy, ethernet, generic, gre, infiniband, ipip, macvlan, sit, team, team-slave, vlan, vxlan,
wifi, gsm, wireguard, ovs-bridge, ovs-port, ovs-interface, vpn, loopback]
choices: [bond, bond-slave, bridge, bridge-slave, dummy, ethernet, generic, gre, infiniband, ipip, macvlan, sit, team,
team-slave, vlan, vxlan, wifi, gsm, wireguard, ovs-bridge, ovs-port, ovs-interface, vpn, loopback]
mode:
description:
- This is the type of device or network connection that you wish to create for a bond or bridge.
@ -344,7 +347,8 @@ options:
version_added: 4.2.0
mtu:
description:
- The connection MTU, for example V(9000). This can not be applied when creating the interface and is done once the interface has been created.
- The connection MTU, for example V(9000). This can not be applied when creating the interface and is done once the
interface has been created.
- Can be used when modifying Team, VLAN, Ethernet (Future plans to implement wifi, gsm, pppoe, infiniband).
- This parameter defaults to V(1500) when unset.
type: int
@ -354,7 +358,8 @@ options:
type: str
primary:
description:
- This is only used with bond and is the primary interface name (for "active-backup" mode), this is the usually the 'ifname'.
- This is only used with bond and is the primary interface name (for "active-backup" mode), this is the usually the
'ifname'.
type: str
miimon:
description:
@ -429,8 +434,8 @@ options:
default: 100
hairpin:
description:
- This is only used with 'bridge-slave' - 'hairpin mode' for the slave, which allows frames to be sent back out through the slave the frame
was received on.
- This is only used with 'bridge-slave' - 'hairpin mode' for the slave, which allows frames to be sent back out through
the slave the frame was received on.
- The default change to V(false) in community.general 7.0.0. It used to be V(true) before.
type: bool
default: false
@ -449,8 +454,8 @@ options:
version_added: 3.4.0
runner_fast_rate:
description:
- Option specifies the rate at which our link partner is asked to transmit LACPDU packets. If this is V(true) then packets will be sent
once per second. Otherwise they will be sent every 30 seconds.
- Option specifies the rate at which our link partner is asked to transmit LACPDU packets. If this is V(true) then packets
will be sent once per second. Otherwise they will be sent every 30 seconds.
- Only allowed for O(runner=lacp).
type: bool
version_added: 6.5.0
@ -519,33 +524,34 @@ options:
wifi_sec:
description:
- The security configuration of the WiFi connection.
- Note the list of suboption attributes may vary depending on which version of NetworkManager/nmcli is installed on the host.
- Note the list of suboption attributes may vary depending on which version of NetworkManager/nmcli is installed on
the host.
- 'An up-to-date list of supported attributes can be found here: U(https://networkmanager.dev/docs/api/latest/settings-802-11-wireless-security.html).'
- 'For instance to use common WPA-PSK auth with a password: V({key-mgmt: wpa-psk, psk: my_password}).'
type: dict
suboptions:
auth-alg:
description:
- When WEP is used (that is, if O(wifi_sec.key-mgmt) is V(none) or V(ieee8021x)) indicate the 802.11 authentication algorithm required
by the AP here.
- When WEP is used (that is, if O(wifi_sec.key-mgmt) is V(none) or V(ieee8021x)) indicate the 802.11 authentication
algorithm required by the AP here.
- One of V(open) for Open System, V(shared) for Shared Key, or V(leap) for Cisco LEAP.
- When using Cisco LEAP (that is, if O(wifi_sec.key-mgmt=ieee8021x) and O(wifi_sec.auth-alg=leap)) the O(wifi_sec.leap-username) and
O(wifi_sec.leap-password) properties must be specified.
- When using Cisco LEAP (that is, if O(wifi_sec.key-mgmt=ieee8021x) and O(wifi_sec.auth-alg=leap)) the O(wifi_sec.leap-username)
and O(wifi_sec.leap-password) properties must be specified.
type: str
choices: [open, shared, leap]
fils:
description:
- Indicates whether Fast Initial Link Setup (802.11ai) must be enabled for the connection.
- One of V(0) (use global default value), V(1) (disable FILS), V(2) (enable FILS if the supplicant and the access point support it)
or V(3) (enable FILS and fail if not supported).
- One of V(0) (use global default value), V(1) (disable FILS), V(2) (enable FILS if the supplicant and the access
point support it) or V(3) (enable FILS and fail if not supported).
- When set to V(0) and no global default is set, FILS will be optionally enabled.
type: int
choices: [0, 1, 2, 3]
default: 0
group:
description:
- A list of group/broadcast encryption algorithms which prevents connections to Wi-Fi networks that do not utilize one of the algorithms
in the list.
- A list of group/broadcast encryption algorithms which prevents connections to Wi-Fi networks that do not utilize
one of the algorithms in the list.
- For maximum compatibility leave this property empty.
type: list
elements: str
@ -553,9 +559,9 @@ options:
key-mgmt:
description:
- Key management used for the connection.
- One of V(none) (WEP or no password protection), V(ieee8021x) (Dynamic WEP), V(owe) (Opportunistic Wireless Encryption), V(wpa-psk)
(WPA2 + WPA3 personal), V(sae) (WPA3 personal only), V(wpa-eap) (WPA2 + WPA3 enterprise) or V(wpa-eap-suite-b-192) (WPA3 enterprise
only).
- One of V(none) (WEP or no password protection), V(ieee8021x) (Dynamic WEP), V(owe) (Opportunistic Wireless Encryption),
V(wpa-psk) (WPA2 + WPA3 personal), V(sae) (WPA3 personal only), V(wpa-eap) (WPA2 + WPA3 enterprise) or V(wpa-eap-suite-b-192)
(WPA3 enterprise only).
- This property must be set for any Wi-Fi connection that uses security.
type: str
choices: [none, ieee8021x, owe, wpa-psk, sae, wpa-eap, wpa-eap-suite-b-192]
@ -571,8 +577,8 @@ options:
type: str
pairwise:
description:
- A list of pairwise encryption algorithms which prevents connections to Wi-Fi networks that do not utilize one of the algorithms in
the list.
- A list of pairwise encryption algorithms which prevents connections to Wi-Fi networks that do not utilize one
of the algorithms in the list.
- For maximum compatibility leave this property empty.
type: list
elements: str
@ -580,8 +586,8 @@ options:
pmf:
description:
- Indicates whether Protected Management Frames (802.11w) must be enabled for the connection.
- One of V(0) (use global default value), V(1) (disable PMF), V(2) (enable PMF if the supplicant and the access point support it) or
V(3) (enable PMF and fail if not supported).
- One of V(0) (use global default value), V(1) (disable PMF), V(2) (enable PMF if the supplicant and the access
point support it) or V(3) (enable PMF and fail if not supported).
- When set to V(0) and no global default is set, PMF will be optionally enabled.
type: int
choices: [0, 1, 2, 3]
@ -601,21 +607,22 @@ options:
psk:
description:
- Pre-Shared-Key for WPA networks.
- For WPA-PSK, it is either an ASCII passphrase of 8 to 63 characters that is (as specified in the 802.11i standard) hashed to derive
the actual key, or the key in form of 64 hexadecimal character.
- For WPA-PSK, it is either an ASCII passphrase of 8 to 63 characters that is (as specified in the 802.11i standard)
hashed to derive the actual key, or the key in form of 64 hexadecimal character.
- The WPA3-Personal networks use a passphrase of any length for SAE authentication.
type: str
wep-key-flags:
description:
- Flags indicating how to handle the O(wifi_sec.wep-key0), O(wifi_sec.wep-key1), O(wifi_sec.wep-key2), and O(wifi_sec.wep-key3) properties.
- Flags indicating how to handle the O(wifi_sec.wep-key0), O(wifi_sec.wep-key1), O(wifi_sec.wep-key2), and O(wifi_sec.wep-key3)
properties.
type: list
elements: int
wep-key-type:
description:
- Controls the interpretation of WEP keys.
- Allowed values are V(1), in which case the key is either a 10- or 26-character hexadecimal string, or a 5- or 13-character ASCII password;
or V(2), in which case the passphrase is provided as a string and will be hashed using the de-facto MD5 method to derive the actual
WEP key.
- Allowed values are V(1), in which case the key is either a 10- or 26-character hexadecimal string, or a 5- or
13-character ASCII password; or V(2), in which case the passphrase is provided as a string and will be hashed
using the de-facto MD5 method to derive the actual WEP key.
type: int
choices: [1, 2]
wep-key0:
@ -640,8 +647,8 @@ options:
type: str
wep-tx-keyidx:
description:
- When static WEP is used (that is, if O(wifi_sec.key-mgmt=none)) and a non-default WEP key index is used by the AP, put that WEP key
index here.
- When static WEP is used (that is, if O(wifi_sec.key-mgmt=none)) and a non-default WEP key index is used by the
AP, put that WEP key index here.
- Valid values are V(0) (default key) through V(3).
- Note that some consumer access points (like the Linksys WRT54G) number the keys V(1) to V(4).
type: int
@ -650,8 +657,8 @@ options:
wps-method:
description:
- Flags indicating which mode of WPS is to be used if any.
- There is little point in changing the default setting as NetworkManager will automatically determine whether it is feasible to start
WPS enrollment from the Access Point capabilities.
- There is little point in changing the default setting as NetworkManager will automatically determine whether it
is feasible to start WPS enrollment from the Access Point capabilities.
- WPS can be disabled by setting this property to a value of V(1).
type: int
default: 0
@ -664,7 +671,8 @@ options:
wifi:
description:
- The configuration of the WiFi connection.
- Note the list of suboption attributes may vary depending on which version of NetworkManager/nmcli is installed on the host.
- Note the list of suboption attributes may vary depending on which version of NetworkManager/nmcli is installed on
the host.
- 'An up-to-date list of supported attributes can be found here: U(https://networkmanager.dev/docs/api/latest/settings-802-11-wireless.html).'
- 'For instance to create a hidden AP mode WiFi connection: V({hidden: true, mode: ap}).'
type: dict
@ -673,9 +681,9 @@ options:
description:
- Configures AP isolation, which prevents communication between wireless devices connected to this AP.
- This property can be set to a value different from V(-1) only when the interface is configured in AP mode.
- If set to V(1), devices are not able to communicate with each other. This increases security because it protects devices against attacks
from other clients in the network. At the same time, it prevents devices to access resources on the same wireless networks as file
shares, printers, and so on.
- If set to V(1), devices are not able to communicate with each other. This increases security because it protects
devices against attacks from other clients in the network. At the same time, it prevents devices to access resources
on the same wireless networks as file shares, printers, and so on.
- If set to V(0), devices can talk to each other.
- When set to V(-1), the global default is used; in case the global default is unspecified it is assumed to be V(0).
type: int
@ -684,17 +692,18 @@ options:
assigned-mac-address:
description:
- The new field for the cloned MAC address.
- It can be either a hardware address in ASCII representation, or one of the special values V(preserve), V(permanent), V(random) or
V(stable).
- This field replaces the deprecated O(wifi.cloned-mac-address) on D-Bus, which can only contain explicit hardware addresses.
- It can be either a hardware address in ASCII representation, or one of the special values V(preserve), V(permanent),
V(random) or V(stable).
- This field replaces the deprecated O(wifi.cloned-mac-address) on D-Bus, which can only contain explicit hardware
addresses.
- Note that this property only exists in D-Bus API. libnm and nmcli continue to call this property C(cloned-mac-address).
type: str
band:
description:
- 802.11 frequency band of the network.
- One of V(a) for 5GHz 802.11a or V(bg) for 2.4GHz 802.11.
- This will lock associations to the Wi-Fi network to the specific band, so for example, if V(a) is specified, the device will not associate
with the same network in the 2.4GHz band even if the network's settings are compatible.
- This will lock associations to the Wi-Fi network to the specific band, so for example, if V(a) is specified, the
device will not associate with the same network in the 2.4GHz band even if the network's settings are compatible.
- This setting depends on specific driver capability and may not work with all drivers.
type: str
choices: [a, bg]
@ -713,39 +722,42 @@ options:
default: 0
cloned-mac-address:
description:
- This D-Bus field is deprecated in favor of O(wifi.assigned-mac-address) which is more flexible and allows specifying special variants
like V(random).
- This D-Bus field is deprecated in favor of O(wifi.assigned-mac-address) which is more flexible and allows specifying
special variants like V(random).
- For libnm and nmcli, this field is called C(cloned-mac-address).
type: str
generate-mac-address-mask:
description:
- With O(wifi.cloned-mac-address) setting V(random) or V(stable), by default all bits of the MAC address are scrambled and a locally-administered,
unicast MAC address is created. This property allows to specify that certain bits are fixed.
- With O(wifi.cloned-mac-address) setting V(random) or V(stable), by default all bits of the MAC address are scrambled
and a locally-administered, unicast MAC address is created. This property allows to specify that certain bits
are fixed.
- Note that the least significant bit of the first MAC address will always be unset to create a unicast MAC address.
- If the property is V(null), it is eligible to be overwritten by a default connection setting.
- If the value is still V(null) or an empty string, the default is to create a locally-administered, unicast MAC address.
- If the value contains one MAC address, this address is used as mask. The set bits of the mask are to be filled with the current MAC
address of the device, while the unset bits are subject to randomization.
- Setting V(FE:FF:FF:00:00:00) means to preserve the OUI of the current MAC address and only randomize the lower 3 bytes using the V(random)
or V(stable) algorithm.
- If the value contains one additional MAC address after the mask, this address is used instead of the current MAC address to fill the
bits that shall not be randomized.
- For example, a value of V(FE:FF:FF:00:00:00 68:F7:28:00:00:00) will set the OUI of the MAC address to 68:F7:28, while the lower bits
are randomized.
- A value of V(02:00:00:00:00:00 00:00:00:00:00:00) will create a fully scrambled globally-administered, burned-in MAC address.
- If the value contains more than one additional MAC addresses, one of them is chosen randomly. For example, V(02:00:00:00:00:00 00:00:00:00:00:00
02:00:00:00:00:00) will create a fully scrambled MAC address, randomly locally or globally administered.
- If the value is still V(null) or an empty string, the default is to create a locally-administered, unicast MAC
address.
- If the value contains one MAC address, this address is used as mask. The set bits of the mask are to be filled
with the current MAC address of the device, while the unset bits are subject to randomization.
- Setting V(FE:FF:FF:00:00:00) means to preserve the OUI of the current MAC address and only randomize the lower
3 bytes using the V(random) or V(stable) algorithm.
- If the value contains one additional MAC address after the mask, this address is used instead of the current MAC
address to fill the bits that shall not be randomized.
- For example, a value of V(FE:FF:FF:00:00:00 68:F7:28:00:00:00) will set the OUI of the MAC address to 68:F7:28,
while the lower bits are randomized.
- A value of V(02:00:00:00:00:00 00:00:00:00:00:00) will create a fully scrambled globally-administered, burned-in
MAC address.
- If the value contains more than one additional MAC addresses, one of them is chosen randomly. For example, V(02:00:00:00:00:00
00:00:00:00:00:00 02:00:00:00:00:00) will create a fully scrambled MAC address, randomly locally or globally administered.
type: str
hidden:
description:
- If V(true), indicates that the network is a non-broadcasting network that hides its SSID. This works both in infrastructure and AP
mode.
- In infrastructure mode, various workarounds are used for a more reliable discovery of hidden networks, such as probe-scanning the
SSID. However, these workarounds expose inherent insecurities with hidden SSID networks, and thus hidden SSID networks should be used
with caution.
- If V(true), indicates that the network is a non-broadcasting network that hides its SSID. This works both in infrastructure
and AP mode.
- In infrastructure mode, various workarounds are used for a more reliable discovery of hidden networks, such as
probe-scanning the SSID. However, these workarounds expose inherent insecurities with hidden SSID networks, and
thus hidden SSID networks should be used with caution.
- In AP mode, the created network does not broadcast its SSID.
- Note that marking the network as hidden may be a privacy issue for you (in infrastructure mode) or client stations (in AP mode), as
the explicit probe-scans are distinctly recognizable on the air.
- Note that marking the network as hidden may be a privacy issue for you (in infrastructure mode) or client stations
(in AP mode), as the explicit probe-scans are distinctly recognizable on the air.
type: bool
default: false
mac-address-blacklist:
@ -756,8 +768,8 @@ options:
elements: str
mac-address-randomization:
description:
- One of V(0) (never randomize unless the user has set a global default to randomize and the supplicant supports randomization), V(1)
(never randomize the MAC address), or V(2) (always randomize the MAC address).
- One of V(0) (never randomize unless the user has set a global default to randomize and the supplicant supports
randomization), V(1) (never randomize the MAC address), or V(2) (always randomize the MAC address).
- This property is deprecated for O(wifi.cloned-mac-address).
type: int
default: 0
@ -773,13 +785,14 @@ options:
choices: [infrastructure, mesh, adhoc, ap]
default: infrastructure
mtu:
description: If non-zero, only transmit packets of the specified size or smaller, breaking larger packets up into multiple Ethernet frames.
description: If non-zero, only transmit packets of the specified size or smaller, breaking larger packets up into
multiple Ethernet frames.
type: int
default: 0
powersave:
description:
- One of V(2) (disable Wi-Fi power saving), V(3) (enable Wi-Fi power saving), V(1) (do not touch currently configure setting) or V(0)
(use the globally configured value).
- One of V(2) (disable Wi-Fi power saving), V(3) (enable Wi-Fi power saving), V(1) (do not touch currently configure
setting) or V(0) (use the globally configured value).
- All other values are reserved.
type: int
default: 0
@ -801,11 +814,12 @@ options:
wake-on-wlan:
description:
- The NMSettingWirelessWakeOnWLan options to enable. Not all devices support all options.
- May be any combination of C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_ANY) (V(0x2)), C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_DISCONNECT) (V(0x4)),
C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_MAGIC) (V(0x8)), C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_GTK_REKEY_FAILURE) (V(0x10)),
C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_EAP_IDENTITY_REQUEST) (V(0x20)), C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_4WAY_HANDSHAKE) (V(0x40)),
C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_RFKILL_RELEASE) (V(0x80)), C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_TCP) (V(0x100)) or the special values V(0x1)
(to use global settings) and V(0x8000) (to disable management of Wake-on-LAN in NetworkManager).
- May be any combination of C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_ANY) (V(0x2)), C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_DISCONNECT)
(V(0x4)), C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_MAGIC) (V(0x8)), C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_GTK_REKEY_FAILURE)
(V(0x10)), C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_EAP_IDENTITY_REQUEST) (V(0x20)), C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_4WAY_HANDSHAKE)
(V(0x40)), C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_RFKILL_RELEASE) (V(0x80)), C(NM_SETTING_WIRELESS_WAKE_ON_WLAN_TCP)
(V(0x100)) or the special values V(0x1) (to use global settings) and V(0x8000) (to disable management of Wake-on-LAN
in NetworkManager).
- Note the option values' sum must be specified in order to combine multiple options.
type: int
default: 1
@ -820,22 +834,25 @@ options:
gsm:
description:
- The configuration of the GSM connection.
- Note the list of suboption attributes may vary depending on which version of NetworkManager/nmcli is installed on the host.
- Note the list of suboption attributes may vary depending on which version of NetworkManager/nmcli is installed on
the host.
- 'An up-to-date list of supported attributes can be found here: U(https://networkmanager.dev/docs/api/latest/settings-gsm.html).'
- 'For instance to use apn, pin, username and password: V({apn: provider.apn, pin: 1234, username: apn.username, password: apn.password}).'
- 'For instance to use apn, pin, username and password: V({apn: provider.apn, pin: 1234, username: apn.username, password:
apn.password}).'
type: dict
version_added: 3.7.0
suboptions:
apn:
description:
- The GPRS Access Point Name specifying the APN used when establishing a data session with the GSM-based network.
- The APN often determines how the user will be billed for their network usage and whether the user has access to the Internet or just
a provider-specific walled-garden, so it is important to use the correct APN for the user's mobile broadband plan.
- The APN often determines how the user will be billed for their network usage and whether the user has access to
the Internet or just a provider-specific walled-garden, so it is important to use the correct APN for the user's
mobile broadband plan.
- The APN may only be composed of the characters a-z, 0-9, ., and - per GSM 03.60 Section 14.9.
type: str
auto-config:
description: When V(true), the settings such as O(gsm.apn), O(gsm.username), or O(gsm.password) will default to values that match the
network the modem will register to in the Mobile Broadband Provider database.
description: When V(true), the settings such as O(gsm.apn), O(gsm.username), or O(gsm.password) will default to values
that match the network the modem will register to in the Mobile Broadband Provider database.
type: bool
default: false
device-id:
@ -850,14 +867,17 @@ options:
type: bool
default: false
mtu:
description: If non-zero, only transmit packets of the specified size or smaller, breaking larger packets up into multiple Ethernet frames.
description: If non-zero, only transmit packets of the specified size or smaller, breaking larger packets up into
multiple Ethernet frames.
type: int
default: 0
network-id:
description:
- The Network ID (GSM LAI format, ie MCC-MNC) to force specific network registration.
- If the Network ID is specified, NetworkManager will attempt to force the device to register only on the specified network.
- This can be used to ensure that the device does not roam when direct roaming control of the device is not otherwise possible.
- If the Network ID is specified, NetworkManager will attempt to force the device to register only on the specified
network.
- This can be used to ensure that the device does not roam when direct roaming control of the device is not otherwise
possible.
type: str
number:
description: Legacy setting that used to help establishing PPP data sessions for GSM-based modems.
@ -871,11 +891,12 @@ options:
password-flags:
description:
- NMSettingSecretFlags indicating how to handle the O(gsm.password) property.
- 'Following choices are allowed: V(0) B(NONE): The system is responsible for providing and storing this secret (default), V(1) B(AGENT_OWNED):
A user secret agent is responsible for providing and storing this secret; when it is required agents will be asked to retrieve it
V(2) B(NOT_SAVED): This secret should not be saved, but should be requested from the user each time it is needed V(4) B(NOT_REQUIRED):
In situations where it cannot be automatically determined that the secret is required (some VPNs and PPP providers do not require
all secrets) this flag indicates that the specific secret is not required.'
- 'Following choices are allowed: V(0) B(NONE): The system is responsible for providing and storing this secret
(default), V(1) B(AGENT_OWNED): A user secret agent is responsible for providing and storing this secret; when
it is required agents will be asked to retrieve it V(2) B(NOT_SAVED): This secret should not be saved, but should
be requested from the user each time it is needed V(4) B(NOT_REQUIRED): In situations where it cannot be automatically
determined that the secret is required (some VPNs and PPP providers do not require all secrets) this flag indicates
that the specific secret is not required.'
type: int
choices: [0, 1, 2, 4]
default: 0
@ -894,13 +915,15 @@ options:
sim-id:
description:
- The SIM card unique identifier (as given by the C(WWAN) management service) which this connection applies to.
- If given, the connection will apply to any device also allowed by O(gsm.device-id) which contains a SIM card matching the given identifier.
- If given, the connection will apply to any device also allowed by O(gsm.device-id) which contains a SIM card matching
the given identifier.
type: str
sim-operator-id:
description:
- A MCC/MNC string like V(310260) or V(21601I) identifying the specific mobile network operator which this connection applies to.
- If given, the connection will apply to any device also allowed by O(gsm.device-id) and O(gsm.sim-id) which contains a SIM card provisioned
by the given operator.
- A MCC/MNC string like V(310260) or V(21601I) identifying the specific mobile network operator which this connection
applies to.
- If given, the connection will apply to any device also allowed by O(gsm.device-id) and O(gsm.sim-id) which contains
a SIM card provisioned by the given operator.
type: str
username:
description:
@ -910,7 +933,8 @@ options:
macvlan:
description:
- The configuration of the MAC VLAN connection.
- Note the list of suboption attributes may vary depending on which version of NetworkManager/nmcli is installed on the host.
- Note the list of suboption attributes may vary depending on which version of NetworkManager/nmcli is installed on
the host.
- 'An up-to-date list of supported attributes can be found here: U(https://networkmanager.dev/docs/api/latest/settings-macvlan.html).'
type: dict
version_added: 6.6.0
@ -924,8 +948,9 @@ options:
required: true
parent:
description:
- If given, specifies the parent interface name or parent connection UUID from which this MAC-VLAN interface should be created. If this
property is not specified, the connection must contain an "802-3-ethernet" setting with a "mac-address" property.
- If given, specifies the parent interface name or parent connection UUID from which this MAC-VLAN interface should
be created. If this property is not specified, the connection must contain an "802-3-ethernet" setting with a
"mac-address" property.
type: str
required: true
promiscuous:
@ -939,7 +964,8 @@ options:
wireguard:
description:
- The configuration of the Wireguard connection.
- Note the list of suboption attributes may vary depending on which version of NetworkManager/nmcli is installed on the host.
- Note the list of suboption attributes may vary depending on which version of NetworkManager/nmcli is installed on
the host.
- 'An up-to-date list of supported attributes can be found here: U(https://networkmanager.dev/docs/api/latest/settings-wireguard.html).'
- 'For instance to configure a listen port: V({listen-port: 12345}).'
type: dict
@ -949,38 +975,42 @@ options:
description:
- The 32-bit fwmark for outgoing packets.
- The use of fwmark is optional and is by default off. Setting it to 0 disables it.
- Note that O(wireguard.ip4-auto-default-route) or O(wireguard.ip6-auto-default-route) enabled, implies to automatically choose a fwmark.
- Note that O(wireguard.ip4-auto-default-route) or O(wireguard.ip6-auto-default-route) enabled, implies to automatically
choose a fwmark.
type: int
ip4-auto-default-route:
description:
- Whether to enable special handling of the IPv4 default route.
- If enabled, the IPv4 default route from O(wireguard.peer-routes) will be placed to a dedicated routing-table and two policy routing
rules will be added.
- The fwmark number is also used as routing-table for the default-route, and if fwmark is zero, an unused fwmark/table is chosen automatically.
This corresponds to what wg-quick does with Table=auto and what WireGuard calls "Improved Rule-based Routing".
- If enabled, the IPv4 default route from O(wireguard.peer-routes) will be placed to a dedicated routing-table and
two policy routing rules will be added.
- The fwmark number is also used as routing-table for the default-route, and if fwmark is zero, an unused fwmark/table
is chosen automatically. This corresponds to what wg-quick does with Table=auto and what WireGuard calls "Improved
Rule-based Routing".
type: bool
ip6-auto-default-route:
description:
- Like O(wireguard.ip4-auto-default-route), but for the IPv6 default route.
type: bool
listen-port:
description: The WireGuard connection listen-port. If not specified, the port will be chosen randomly when the interface comes up.
description: The WireGuard connection listen-port. If not specified, the port will be chosen randomly when the interface
comes up.
type: int
mtu:
description:
- If non-zero, only transmit packets of the specified size or smaller, breaking larger packets up into multiple fragments.
- If zero a default MTU is used. Note that contrary to wg-quick's MTU setting, this does not take into account the current routes at
the time of activation.
- If non-zero, only transmit packets of the specified size or smaller, breaking larger packets up into multiple
fragments.
- If zero a default MTU is used. Note that contrary to wg-quick's MTU setting, this does not take into account the
current routes at the time of activation.
type: int
peer-routes:
description:
- Whether to automatically add routes for the AllowedIPs ranges of the peers.
- If V(true) (the default), NetworkManager will automatically add routes in the routing tables according to C(ipv4.route-table) and
C(ipv6.route-table). Usually you want this automatism enabled.
- If V(false), no such routes are added automatically. In this case, the user may want to configure static routes in C(ipv4.routes)
and C(ipv6.routes), respectively.
- Note that if the peer's AllowedIPs is V(0.0.0.0/0) or V(::/0) and the profile's C(ipv4.never-default) or C(ipv6.never-default) setting
is enabled, the peer route for this peer will not be added automatically.
- If V(true) (the default), NetworkManager will automatically add routes in the routing tables according to C(ipv4.route-table)
and C(ipv6.route-table). Usually you want this automatism enabled.
- If V(false), no such routes are added automatically. In this case, the user may want to configure static routes
in C(ipv4.routes) and C(ipv6.routes), respectively.
- Note that if the peer's AllowedIPs is V(0.0.0.0/0) or V(::/0) and the profile's C(ipv4.never-default) or C(ipv6.never-default)
setting is enabled, the peer route for this peer will not be added automatically.
type: bool
private-key:
description: The 256 bit private-key in base64 encoding.
@ -992,8 +1022,8 @@ options:
vpn:
description:
- Configuration of a VPN connection (PPTP and L2TP).
- In order to use L2TP you need to be sure that C(network-manager-l2tp) - and C(network-manager-l2tp-gnome) if host has UI - are installed
on the host.
- In order to use L2TP you need to be sure that C(network-manager-l2tp) - and C(network-manager-l2tp-gnome) if host
has UI - are installed on the host.
type: dict
version_added: 5.1.0
suboptions:
@ -1006,17 +1036,19 @@ options:
type: str
required: true
gateway:
description: The gateway to connection. It can be an IP address (for example V(192.0.2.1)) or a FQDN address (for example V(vpn.example.com)).
description: The gateway to connection. It can be an IP address (for example V(192.0.2.1)) or a FQDN address (for
example V(vpn.example.com)).
type: str
required: true
password-flags:
description:
- NMSettingSecretFlags indicating how to handle the C(vpn.password) property.
- 'Following choices are allowed: V(0) B(NONE): The system is responsible for providing and storing this secret (default); V(1) B(AGENT_OWNED):
A user secret agent is responsible for providing and storing this secret; when it is required agents will be asked to retrieve it;
V(2) B(NOT_SAVED): This secret should not be saved, but should be requested from the user each time it is needed; V(4) B(NOT_REQUIRED):
In situations where it cannot be automatically determined that the secret is required (some VPNs and PPP providers do not require
all secrets) this flag indicates that the specific secret is not required.'
- 'Following choices are allowed: V(0) B(NONE): The system is responsible for providing and storing this secret
(default); V(1) B(AGENT_OWNED): A user secret agent is responsible for providing and storing this secret; when
it is required agents will be asked to retrieve it; V(2) B(NOT_SAVED): This secret should not be saved, but should
be requested from the user each time it is needed; V(4) B(NOT_REQUIRED): In situations where it cannot be automatically
determined that the secret is required (some VPNs and PPP providers do not require all secrets) this flag indicates
that the specific secret is not required.'
type: int
choices: [0, 1, 2, 4]
default: 0
@ -1065,7 +1097,8 @@ options:
vfs:
description:
- 'Virtual function descriptors in the form: V(INDEX [ATTR=VALUE[ ATTR=VALUE]...]).'
- Multiple VFs can be specified using a comma as separator, for example V(2 mac=00:11:22:33:44:55 spoof-check=true,3 vlans=100).
- Multiple VFs can be specified using a comma as separator, for example V(2 mac=00:11:22:33:44:55 spoof-check=true,3
vlans=100).
type: str
"""

11
plugins/modules/nosh.py
View file

@ -43,14 +43,14 @@ options:
required: false
type: bool
description:
- Enable or disable the service, independently of C(*.preset) file preference or running state. Mutually exclusive with O(preset). Will
take effect prior to O(state=reset).
- Enable or disable the service, independently of C(*.preset) file preference or running state. Mutually exclusive with
O(preset). Will take effect prior to O(state=reset).
preset:
required: false
type: bool
description:
- Enable or disable the service according to local preferences in C(*.preset) files. Mutually exclusive with O(enabled). Only has an effect
if set to true. Will take effect prior to O(state=reset).
- Enable or disable the service according to local preferences in C(*.preset) files. Mutually exclusive with O(enabled).
Only has an effect if set to true. Will take effect prior to O(state=reset).
user:
required: false
default: false
@ -145,7 +145,8 @@ state:
type: str
sample: "reloaded"
status:
description: A dictionary with the key=value pairs returned by C(system-control show-json) or V(none) if the service is not loaded.
description: A dictionary with the key=value pairs returned by C(system-control show-json) or V(none) if the service is
not loaded.
returned: success
type: complex
contains: