a-c-m
/
community.general
mirror of https://github.com/ansible-collections/community.general.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[def]*.py: normalize docs (#9401) 

* [def]*.py: normalize docs

* Update plugins/modules/datadog_monitor.py

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

---------

Co-authored-by: Felix Fontein <felix@fontein.de>
pull/9420/head
Alexei Znamensky 2024-12-27 09:53:20 +13:00 committed by GitHub
parent 84655b0d0f
commit df42f29e53
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
30 changed files with 1300 additions and 1431 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
plugins/modules/datadog_downtime.py
View File

@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = """
---
DOCUMENTATION = r"""
module: datadog_downtime
short_description: Manages Datadog downtimes
version_added: 2.0.0
@ -96,15 +95,15 @@ options:
rrule:
description:
- The C(RRULE) standard for defining recurring events.
- For example, to have a recurring event on the first day of each month,
select a type of rrule and set the C(FREQ) to C(MONTHLY) and C(BYMONTHDAY) to C(1).
- For example, to have a recurring event on the first day of each month, select a type of rrule and set the C(FREQ)
to C(MONTHLY) and C(BYMONTHDAY) to C(1).
- Most common rrule options from the iCalendar Spec are supported.
- Attributes specifying the duration in C(RRULE) are not supported (for example C(DTSTART), C(DTEND), C(DURATION)).
type: str
"""
EXAMPLES = """
- name: Create a downtime
EXAMPLES = r"""
- name: Create a downtime
register: downtime_var
community.general.datadog_downtime:
state: present
@ -116,14 +115,14 @@ EXAMPLES = """
app_key: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
# Lookup the id in the file and ignore errors if the file doesn't exits, so downtime gets created
id: "{{ lookup('file', inventory_hostname ~ '_downtime_id.txt', errors='ignore') }}"
- name: Save downtime id to file for later updates and idempotence
- name: Save downtime id to file for later updates and idempotence
delegate_to: localhost
copy:
content: "{{ downtime.downtime.id }}"
dest: "{{ inventory_hostname ~ '_downtime_id.txt' }}"
"""
RETURN = """
RETURN = r"""
# Returns the downtime JSON dictionary from the API response under the C(downtime) key.
# See https://docs.datadoghq.com/api/v1/downtimes/#schedule-a-downtime for more details.
downtime:

42
plugins/modules/datadog_event.py
View File

@ -14,13 +14,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: datadog_event
short_description: Posts events to Datadog service
description:
- "Allows to post events to Datadog (www.datadoghq.com) service."
- "Uses http://docs.datadoghq.com/api/#events API."
- Allows to post events to Datadog (www.datadoghq.com) service.
- Uses http://docs.datadoghq.com/api/#events API.
author:
- "Artūras 'arturaz' Šlajus (@arturaz)"
- "Naoya Nakazawa (@n0ts)"
@ -34,19 +33,23 @@ attributes:
options:
api_key:
type: str
description: ["Your DataDog API key."]
description:
- Your DataDog API key.
required: true
app_key:
type: str
description: ["Your DataDog app key."]
description:
- Your DataDog app key.
required: true
title:
type: str
description: ["The event title."]
description:
- The event title.
required: true
text:
type: str
description: ["The body of the event."]
description:
- The body of the event.
required: true
date_happened:
type: int
@ -55,7 +58,8 @@ options:
- Default value is now.
priority:
type: str
description: ["The priority of the event."]
description:
- The priority of the event.
default: normal
choices: [normal, low]
host:
@ -71,24 +75,27 @@ options:
tags:
type: list
elements: str
description: ["Comma separated list of tags to apply to the event."]
description:
- Comma separated list of tags to apply to the event.
alert_type:
type: str
description: ["Type of alert."]
description:
- Type of alert.
default: info
choices: ['error', 'warning', 'info', 'success']
aggregation_key:
type: str
description: ["An arbitrary string to use for aggregation."]
description:
- An arbitrary string to use for aggregation.
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
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Post an event with low priority
community.general.datadog_event:
title: Testing from ansible
@ -116,8 +123,7 @@ EXAMPLES = '''
- aa
- b
- '#host:{{ inventory_hostname }}'
'''
"""
import platform
import traceback

18
plugins/modules/datadog_monitor.py
View File

@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: datadog_monitor
short_description: Manages Datadog monitors
description:
@ -87,7 +86,7 @@ options:
description:
- A message to include with notifications for this monitor.
- Email notifications can be sent to specific users by using the same '@username' notation as events.
- Monitor message template variables can be accessed by using double square brackets, i.e '[[' and ']]'.
- Monitor message template variables can be accessed by using double square brackets, in other words C([[) and C(]]).
type: str
silenced:
type: dict
@ -164,7 +163,7 @@ options:
version_added: 1.3.0
priority:
description:
- Integer from 1 (high) to 5 (low) indicating alert severity.
- Integer from V(1) (high) to V(5) (low) indicating alert severity.
type: int
version_added: 4.6.0
notification_preset_name:
@ -179,7 +178,8 @@ options:
version_added: 7.1.0
renotify_occurrences:
description:
- The number of times re-notification messages should be sent on the current status at the provided re-notification interval.
- The number of times re-notification messages should be sent on the current status at the provided re-notification
interval.
type: int
version_added: 7.1.0
renotify_statuses:
@ -192,10 +192,9 @@ options:
type: list
elements: str
version_added: 7.1.0
"""
'''
EXAMPLES = '''
EXAMPLES = r"""
- name: Create a metric monitor
community.general.datadog_monitor:
type: "metric alert"
@ -239,7 +238,8 @@ EXAMPLES = '''
api_host: https://api.datadoghq.eu
api_key: "9775a026f1ca7d1c6c5af9d94d9595a4"
app_key: "87ce4a24b5553d2e482ea8a8500e71b8ad4554ff"
'''
"""
import traceback
# Import Datadog

85
plugins/modules/dconf.py
View File

@ -9,53 +9,39 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
DOCUMENTATION = r"""
module: dconf
author:
- "Branko Majic (@azaghal)"
short_description: Modify and read dconf database
description:
- This module allows modifications and reading of C(dconf) database. The module
is implemented as a wrapper around C(dconf) tool. Please see the dconf(1) man
page for more details.
- Since C(dconf) requires a running D-Bus session to change values, the module
will try to detect an existing session and reuse it, or run the tool via
C(dbus-run-session).
- This module allows modifications and reading of C(dconf) database. The module is implemented as a wrapper around C(dconf)
tool. Please see the dconf(1) man page for more details.
- Since C(dconf) requires a running D-Bus session to change values, the module will try to detect an existing session and
reuse it, or run the tool using C(dbus-run-session).
requirements:
- Optionally the C(gi.repository) Python library (usually included in the OS
on hosts which have C(dconf)); this will become a non-optional requirement
in a future major release of community.general.
- Optionally the C(gi.repository) Python library (usually included in the OS on hosts which have C(dconf)); this will become
a non-optional requirement in a future major release of community.general.
notes:
- This module depends on C(psutil) Python library (version 4.0.0 and upwards),
C(dconf), C(dbus-send), and C(dbus-run-session) binaries. Depending on
distribution you are using, you may need to install additional packages to
have these available.
- This module uses the C(gi.repository) Python library when available for
accurate comparison of values in C(dconf) to values specified in Ansible
code. C(gi.repository) is likely to be present on most systems which have
C(dconf) but may not be present everywhere. When it is missing, a simple
string comparison between values is used, and there may be false positives,
that is, Ansible may think that a value is being changed when it is not.
This fallback will be removed in a future version of this module, at which
point the module will stop working on hosts without C(gi.repository).
- Detection of existing, running D-Bus session, required to change settings
via C(dconf), is not 100% reliable due to implementation details of D-Bus
daemon itself. This might lead to running applications not picking-up
changes on the fly if options are changed via Ansible and
C(dbus-run-session).
- Keep in mind that the C(dconf) CLI tool, which this module wraps around,
utilises an unusual syntax for the values (GVariant). For example, if you
wanted to provide a string value, the correct syntax would be
O(value="'myvalue'") - with single quotes as part of the Ansible parameter
value.
- When using loops in combination with a value like
V("[('xkb', 'us'\), ('xkb', 'se'\)]"), you need to be aware of possible
type conversions. Applying a filter V({{ item.value | string }})
to the parameter variable can avoid potential conversion problems.
- The easiest way to figure out exact syntax/value you need to provide for a
key is by making the configuration change in application affected by the
key, and then having a look at value set via commands C(dconf dump
/path/to/dir/) or C(dconf read /path/to/key).
- This module depends on C(psutil) Python library (version 4.0.0 and upwards), C(dconf), C(dbus-send), and C(dbus-run-session)
binaries. Depending on distribution you are using, you may need to install additional packages to have these available.
- This module uses the C(gi.repository) Python library when available for accurate comparison of values in C(dconf) to values
specified in Ansible code. C(gi.repository) is likely to be present on most systems which have C(dconf) but may not be
present everywhere. When it is missing, a simple string comparison between values is used, and there may be false positives,
that is, Ansible may think that a value is being changed when it is not. This fallback will be removed in a future version
of this module, at which point the module will stop working on hosts without C(gi.repository).
- Detection of existing, running D-Bus session, required to change settings using C(dconf), is not 100% reliable due to implementation
details of D-Bus daemon itself. This might lead to running applications not picking-up changes on-the-fly if options are
changed using Ansible and C(dbus-run-session).
- Keep in mind that the C(dconf) CLI tool, which this module wraps around, utilises an unusual syntax for the values (GVariant).
For example, if you wanted to provide a string value, the correct syntax would be O(value="'myvalue'") - with single quotes
as part of the Ansible parameter value.
- When using loops in combination with a value like V("[('xkb', 'us'\), ('xkb', 'se'\)]"), you need to be aware of possible
type conversions. Applying a filter V({{ item.value | string }}) to the parameter variable can avoid potential conversion
problems.
- The easiest way to figure out exact syntax/value you need to provide for a key is by making the configuration change in
application affected by the key, and then having a look at value set using commands C(dconf dump /path/to/dir/) or C(dconf
read /path/to/key).
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -73,27 +59,24 @@ options:
type: raw
required: false
description:
- Value to set for the specified dconf key. Value should be specified in
GVariant format. Due to complexity of this format, it is best to have a
look at existing values in the dconf database.
- Value to set for the specified dconf key. Value should be specified in GVariant format. Due to complexity of this
format, it is best to have a look at existing values in the dconf database.
- Required for O(state=present).
- Although the type is specified as "raw", it should typically be
specified as a string. However, boolean values in particular are
handled properly even when specified as booleans rather than strings
(in fact, handling booleans properly is why the type of this parameter
is "raw").
- Although the type is specified as "raw", it should typically be specified as a string. However, boolean values in
particular are handled properly even when specified as booleans rather than strings (in fact, handling booleans properly
is why the type of this parameter is "raw").
state:
type: str
required: false
default: present
choices: [ 'read', 'present', 'absent' ]
choices: ['read', 'present', 'absent']
description:
- The action to take upon the key/value.
'''
"""
RETURN = r"""
value:
description: value associated with the requested key
description: Value associated with the requested key.
returned: success, state was "read"
type: str
sample: "'Default'"

30
plugins/modules/decompress.py
View File

@ -9,8 +9,7 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: decompress
short_description: Decompresses compressed files
version_added: 10.1.0
@ -36,17 +35,17 @@ options:
description:
- The file name of the destination file where the compressed file will be decompressed.
- If the destination file exists, it will be truncated and overwritten.
- If not specified, the destination filename will be derived from O(src) by removing the compression format
extension. For example, if O(src) is V(/path/to/file.txt.gz) and O(format) is V(gz), O(dest) will be
V(/path/to/file.txt). If the O(src) file does not have an extension for the current O(format), the O(dest)
filename will be made by appending C(_decompressed) to the O(src) filename. For instance, if O(src) is
V(/path/to/file.myextension), the (dest) filename will be V(/path/to/file.myextension_decompressed).
- If not specified, the destination filename will be derived from O(src) by removing the compression format extension.
For example, if O(src) is V(/path/to/file.txt.gz) and O(format) is V(gz), O(dest) will be V(/path/to/file.txt). If
the O(src) file does not have an extension for the current O(format), the O(dest) filename will be made by appending
C(_decompressed) to the O(src) filename. For instance, if O(src) is V(/path/to/file.myextension), the (dest) filename
will be V(/path/to/file.myextension_decompressed).
type: path
format:
description:
- The type of compression to use to decompress.
type: str
choices: [ gz, bz2, xz ]
choices: [gz, bz2, xz]
default: gz
remove:
description:
@ -54,12 +53,13 @@ options:
type: bool
default: false
requirements:
- Requires C(lzma) (standard library of Python 3) or L(backports.lzma, https://pypi.org/project/backports.lzma/) (Python 2) if using C(xz) format.
- Requires C(lzma) (standard library of Python 3) or L(backports.lzma, https://pypi.org/project/backports.lzma/) (Python
2) if using C(xz) format.
author:
- Stanislav Shamilov (@shamilovstas)
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Decompress file /path/to/file.txt.gz into /path/to/file.txt (gz compression is used by default)
community.general.decompress:
src: /path/to/file.txt.gz
@ -80,15 +80,15 @@ EXAMPLES = r'''
src: /path/to/file.txt.gz
dest: /path/to/file.txt
remove: true
'''
"""
RETURN = r'''
RETURN = r"""
dest:
description: Path to decompressed file
description: Path to decompressed file.
type: str
returned: success
sample: /path/to/file.txt
'''
"""
import bz2
import filecmp

77
plugins/modules/deploy_helper.py
View File

@ -11,27 +11,19 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: deploy_helper
author: "Ramon de la Fuente (@ramondelafuente)"
short_description: Manages some of the steps common in deploying projects
description:
- The Deploy Helper manages some of the steps common in deploying software.
It creates a folder structure, manages a symlink for the current release
and cleans up old releases.
# TODO: convert below to RETURN documentation!
- "Running it with the O(state=query) or O(state=present) will return the C(deploy_helper) fact.
C(project_path), whatever you set in the O(path) parameter,
C(current_path), the path to the symlink that points to the active release,
C(releases_path), the path to the folder to keep releases in,
C(shared_path), the path to the folder to keep shared resources in,
C(unfinished_filename), the file to check for to recognize unfinished builds,
C(previous_release), the release the 'current' symlink is pointing to,
C(previous_release_path), the full path to the 'current' symlink target,
C(new_release), either the 'release' parameter or a generated timestamp,
C(new_release_path), the path to the new release folder (not created by the module)."
- The Deploy Helper manages some of the steps common in deploying software. It creates a folder structure, manages a symlink
for the current release and cleans up old releases.
- Running it with the O(state=query) or O(state=present) will return the C(deploy_helper) fact. C(project_path), whatever
you set in the O(path) parameter, C(current_path), the path to the symlink that points to the active release, C(releases_path),
the path to the folder to keep releases in, C(shared_path), the path to the folder to keep shared resources in, C(unfinished_filename),
the file to check for to recognize unfinished builds, C(previous_release), the release the 'current' symlink is pointing
to, C(previous_release_path), the full path to the 'current' symlink target, C(new_release), either the O(release) parameter
or a generated timestamp, C(new_release_path), the path to the new release folder (not created by the module).
attributes:
check_mode:
support: full
@ -44,42 +36,38 @@ options:
required: true
aliases: ['dest']
description:
- The root path of the project.
Returned in the C(deploy_helper.project_path) fact.
- The root path of the project. Returned in the C(deploy_helper.project_path) fact.
state:
type: str
description:
- The state of the project.
- V(query) will only gather facts.
- V(present) will create the project C(root) folder, and in it the C(releases) and C(shared) folders.
- V(finalize) will remove the unfinished_filename file, create a symlink to the newly
deployed release and optionally clean old releases.
- V(finalize) will remove the unfinished_filename file, create a symlink to the newly deployed release and optionally
clean old releases.
- V(clean) will remove failed & old releases.
- V(absent) will remove the project folder (synonymous to the M(ansible.builtin.file) module with O(state=absent)).
choices: [ present, finalize, absent, clean, query ]
choices: [present, finalize, absent, clean, query]
default: present
release:
type: str
description:
- The release version that is being deployed. Defaults to a timestamp format C(%Y%m%d%H%M%S) (for example V(20141119223359)).
This parameter is optional during O(state=present), but needs to be set explicitly for O(state=finalize).
You can use the generated fact C(release={{ deploy_helper.new_release }}).
This parameter is optional during O(state=present), but needs to be set explicitly for O(state=finalize). You can
use the generated fact C(release={{ deploy_helper.new_release }}).
releases_path:
type: str
description:
- The name of the folder that will hold the releases. This can be relative to O(path) or absolute.
Returned in the C(deploy_helper.releases_path) fact.
- The name of the folder that will hold the releases. This can be relative to O(path) or absolute. Returned in the C(deploy_helper.releases_path)
fact.
default: releases
shared_path:
type: path
description:
- The name of the folder that will hold the shared resources. This can be relative to O(path) or absolute.
If this is set to an empty string, no shared folder will be created.
Returned in the C(deploy_helper.shared_path) fact.
- The name of the folder that will hold the shared resources. This can be relative to O(path) or absolute. If this is
set to an empty string, no shared folder will be created. Returned in the C(deploy_helper.shared_path) fact.
default: shared
current_path:
@ -92,9 +80,9 @@ options:
unfinished_filename:
type: str
description:
- The name of the file that indicates a deploy has not finished. All folders in the O(releases_path) that
contain this file will be deleted on O(state=finalize) with O(clean=true), or O(state=clean). This file is
automatically deleted from the C(new_release_path) during O(state=finalize).
- The name of the file that indicates a deploy has not finished. All folders in the O(releases_path) that contain this
file will be deleted on O(state=finalize) with O(clean=true), or O(state=clean). This file is automatically deleted
from the C(new_release_path) during O(state=finalize).
default: DEPLOY_UNFINISHED
clean:
@ -111,20 +99,18 @@ options:
default: 5
notes:
- Facts are only returned for O(state=query) and O(state=present). If you use both, you should pass any overridden
parameters to both calls, otherwise the second call will overwrite the facts of the first one.
- When using O(state=clean), the releases are ordered by I(creation date). You should be able to switch to a
new naming strategy without problems.
- Because of the default behaviour of generating the C(new_release) fact, this module will not be idempotent
unless you pass your own release name with O(release). Due to the nature of deploying software, this should not
be much of a problem.
- Facts are only returned for O(state=query) and O(state=present). If you use both, you should pass any overridden parameters
to both calls, otherwise the second call will overwrite the facts of the first one.
- When using O(state=clean), the releases are ordered by I(creation date). You should be able to switch to a new naming
strategy without problems.
- Because of the default behaviour of generating the C(new_release) fact, this module will not be idempotent unless you
pass your own release name with O(release). Due to the nature of deploying software, this should not be much of a problem.
extends_documentation_fragment:
- ansible.builtin.files
- community.general.attributes
'''
EXAMPLES = '''
"""
EXAMPLES = r"""
# General explanation, starting with an example folder structure for a project:
# root:
@ -277,7 +263,8 @@ EXAMPLES = '''
path: /path/to/root
- ansible.builtin.debug:
var: deploy_helper
'''
"""
import os
import shutil
import time

21
plugins/modules/dimensiondata_network.py
View File

@ -14,8 +14,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: dimensiondata_network
short_description: Create, update, and delete MCP 1.0 & 2.0 networks
extends_documentation_fragment:
@ -24,7 +23,7 @@ extends_documentation_fragment:
- community.general.attributes
description:
- Create, update, and delete MCP 1.0 & 2.0 networks
- Create, update, and delete MCP 1.0 & 2.0 networks.
author: 'Aimon Bustardo (@aimonb)'
attributes:
check_mode:
@ -55,9 +54,9 @@ options:
choices: [present, absent]
default: present
type: str
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Create an MCP 1.0 network
community.general.dimensiondata_network:
region: na
@ -79,9 +78,9 @@ EXAMPLES = '''
location: NA1
name: mynet
state: absent
'''
"""
RETURN = '''
RETURN = r"""
network:
description: Dictionary describing the network.
returned: On success when O(state=present).
@ -104,18 +103,18 @@ network:
type: str
sample: NA3
status:
description: Network status. (MCP 2.0 only)
description: Network status. (MCP 2.0 only).
type: str
sample: NORMAL
private_net:
description: Private network subnet. (MCP 1.0 only)
description: Private network subnet. (MCP 1.0 only).
type: str
sample: "10.2.3.0"
multicast:
description: Multicast enabled? (MCP 1.0 only)
description: Multicast enabled? (MCP 1.0 only).
type: bool
sample: false
'''
"""
import traceback
from ansible.module_utils.basic import AnsibleModule

23
plugins/modules/dimensiondata_vlan.py
View File

@ -10,8 +10,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: dimensiondata_vlan
short_description: Manage a VLAN in a Cloud Control network domain
extends_documentation_fragment:
@ -45,32 +44,34 @@ options:
type: str
private_ipv4_base_address:
description:
- The base address for the VLAN's IPv4 network (e.g. 192.168.1.0).
- The base address for the VLAN's IPv4 network (for example V(192.168.1.0)).
type: str
default: ''
private_ipv4_prefix_size:
description:
- The size of the IPv4 address space, e.g 24.
- The size of the IPv4 address space, for example V(24).
- Required, if O(private_ipv4_base_address) is specified.
type: int
default: 0
state:
description:
- The desired state for the target VLAN.
- V(readonly) ensures that the state is only ever read, not modified (the module will fail if the resource does not exist).
- V(readonly) ensures that the state is only ever read, not modified (the module will fail if the resource does not
exist).
choices: [present, absent, readonly]
default: present
type: str
allow_expand:
description:
- Permit expansion of the target VLAN's network if the module parameters specify a larger network than the VLAN currently possesses.
- Permit expansion of the target VLAN's network if the module parameters specify a larger network than the VLAN currently
possesses.
- If V(false), the module will fail under these conditions.
- This is intended to prevent accidental expansion of a VLAN's network (since this operation is not reversible).
type: bool
default: false
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Add or update VLAN
community.general.dimensiondata_vlan:
region: na
@ -100,9 +101,9 @@ EXAMPLES = '''
name: my_vlan_1
state: absent
wait: true
'''
"""
RETURN = '''
RETURN = r"""
vlan:
description: Dictionary describing the VLAN.
returned: On success when O(state=present)
@ -152,7 +153,7 @@ vlan:
description: VLAN status.
type: str
sample: NORMAL
'''
"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.dimensiondata import DimensionDataModule, UnknownNetworkError

17
plugins/modules/discord.py
View File

@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: discord
short_description: Send Discord messages
version_added: 3.1.0
@ -18,7 +17,7 @@ description:
author: Christian Wollinger (@cwollinger)
seealso:
- name: API documentation
description: Documentation for Discord API
description: Documentation for Discord API.
link: https://discord.com/developers/docs/resources/webhook#execute-webhook
extends_documentation_fragment:
- community.general.attributes
@ -31,13 +30,13 @@ options:
webhook_id:
description:
- The webhook ID.
- "Format from Discord webhook URL: C(/webhooks/{webhook.id}/{webhook.token})."
- 'Format from Discord webhook URL: C(/webhooks/{webhook.id}/{webhook.token}).'
required: true
type: str
webhook_token:
description:
- The webhook token.
- "Format from Discord webhook URL: C(/webhooks/{webhook.id}/{webhook.token})."
- 'Format from Discord webhook URL: C(/webhooks/{webhook.id}/{webhook.token}).'
required: true
type: str
content:
@ -62,13 +61,13 @@ options:
description:
- Send messages as Embeds to the Discord channel.
- Embeds can have a colored border, embedded images, text fields and more.
- "Allowed parameters are described in the Discord Docs: U(https://discord.com/developers/docs/resources/channel#embed-object)"
- 'Allowed parameters are described in the Discord Docs: U(https://discord.com/developers/docs/resources/channel#embed-object).'
- At least one of O(content) and O(embeds) must be specified.
type: list
elements: dict
'''
"""
EXAMPLES = """
EXAMPLES = r"""
- name: Send a message to the Discord channel
community.general.discord:
webhook_id: "00000"
@ -119,7 +118,7 @@ EXAMPLES = """
timestamp: "{{ ansible_date_time.iso8601 }}"
"""
RETURN = """
RETURN = r"""
http_code:
description:
- Response Code returned by Discord API.

21
plugins/modules/django_check.py
View File

@ -7,18 +7,17 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = """
---
DOCUMENTATION = r"""
module: django_check
author:
- Alexei Znamensky (@russoz)
- Alexei Znamensky (@russoz)
short_description: Wrapper for C(django-admin check)
version_added: 9.1.0
description:
- This module is a wrapper for the execution of C(django-admin check).
- This module is a wrapper for the execution of C(django-admin check).
extends_documentation_fragment:
- community.general.attributes
- community.general.django
- community.general.attributes
- community.general.django
options:
database:
description:
@ -49,8 +48,8 @@ options:
type: list
elements: str
notes:
- The outcome of the module is found in the common return values RV(ignore:stdout), RV(ignore:stderr), RV(ignore:rc).
- The module will fail if RV(ignore:rc) is not zero.
- The outcome of the module is found in the common return values RV(ignore:stdout), RV(ignore:stderr), RV(ignore:rc).
- The module will fail if RV(ignore:rc) is not zero.
attributes:
check_mode:
support: full
@ -58,8 +57,7 @@ attributes:
support: none
"""
EXAMPLES = """
---
EXAMPLES = r"""
- name: Check the entire project
community.general.django_check:
settings: myproject.settings
@ -74,8 +72,7 @@ EXAMPLES = """
venv: /home/joedoe/project/fancysite/venv
"""
RETURN = """
---
RETURN = r"""
run_info:
description: Command-line execution information.
type: dict

17
plugins/modules/django_command.py
View File

@ -7,18 +7,17 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = """
---
DOCUMENTATION = r"""
module: django_command
author:
- Alexei Znamensky (@russoz)
- Alexei Znamensky (@russoz)
short_description: Run Django admin commands
version_added: 9.0.0
description:
- This module allows the execution of arbitrary Django admin commands.
- This module allows the execution of arbitrary Django admin commands.
extends_documentation_fragment:
- community.general.attributes
- community.general.django
- community.general.attributes
- community.general.django
attributes:
check_mode:
support: none
@ -37,8 +36,7 @@ options:
- List of extra arguments passed to the django admin command.
"""
EXAMPLES = """
---
EXAMPLES = r"""
- name: Check the project
community.general.django_command:
command: check
@ -52,8 +50,7 @@ EXAMPLES = """
venv: /home/joedoe/project/fancysite/venv
"""
RETURN = """
---
RETURN = r"""
run_info:
description: Command-line execution information.
type: dict

19
plugins/modules/django_createcachetable.py
View File

@ -7,19 +7,18 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = """
---
DOCUMENTATION = r"""
module: django_createcachetable
author:
- Alexei Znamensky (@russoz)
- Alexei Znamensky (@russoz)
short_description: Wrapper for C(django-admin createcachetable)
version_added: 9.1.0
description:
- This module is a wrapper for the execution of C(django-admin createcachetable).
- This module is a wrapper for the execution of C(django-admin createcachetable).
extends_documentation_fragment:
- community.general.attributes
- community.general.django
- community.general.django.database
- community.general.attributes
- community.general.django
- community.general.django.database
attributes:
check_mode:
support: full
@ -27,8 +26,7 @@ attributes:
support: none
"""
EXAMPLES = """
---
EXAMPLES = r"""
- name: Create cache table in the default database
community.general.django_createcachetable:
settings: myproject.settings
@ -41,8 +39,7 @@ EXAMPLES = """
venv: /home/joedoe/project/fancysite/venv
"""
RETURN = """
---
RETURN = r"""
run_info:
description: Command-line execution information.
type: dict

57
plugins/modules/django_manage.py
View File

@ -10,13 +10,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: django_manage
short_description: Manages a Django application
description:
- Manages a Django application using the C(manage.py) application frontend to C(django-admin). With the
O(virtualenv) parameter, all management commands will be executed by the given C(virtualenv) installation.
- Manages a Django application using the C(manage.py) application frontend to C(django-admin). With the O(virtualenv) parameter,
all management commands will be executed by the given C(virtualenv) installation.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -27,17 +26,18 @@ attributes:
options:
command:
description:
- The name of the Django management command to run. The commands listed below are built in this module and have some basic parameter validation.
- The name of the Django management command to run. The commands listed below are built in this module and have some
basic parameter validation.
- V(collectstatic) - Collects the static files into C(STATIC_ROOT).
- V(createcachetable) - Creates the cache tables for use with the database cache backend.
- V(flush) - Removes all data from the database.
- V(loaddata) - Searches for and loads the contents of the named O(fixtures) into the database.
- V(migrate) - Synchronizes the database state with models and migrations.
- V(test) - Runs tests for all installed apps.
- Other commands can be entered, but will fail if they are unknown to Django. Other commands that may
prompt for user input should be run with the C(--noinput) flag.
- Support for the values V(cleanup), V(syncdb), V(validate) was removed in community.general 9.0.0.
See note about supported versions of Django.
- Other commands can be entered, but will fail if they are unknown to Django. Other commands that may prompt for user
input should be run with the C(--noinput) flag.
- Support for the values V(cleanup), V(syncdb), V(validate) was removed in community.general 9.0.0. See note about supported
versions of Django.
type: str
required: true
project_path:
@ -53,8 +53,8 @@ options:
required: false
pythonpath:
description:
- A directory to add to the Python path. Typically used to include the settings module if it is located
external to the application directory.
- A directory to add to the Python path. Typically used to include the settings module if it is located external to
the application directory.
- This would be equivalent to adding O(pythonpath)'s value to the E(PYTHONPATH) environment variable.
type: path
required: false
@ -84,8 +84,7 @@ options:
type: bool
database:
description:
- The database to target. Used by the V(createcachetable), V(flush), V(loaddata), V(syncdb),
and V(migrate) commands.
- The database to target. Used by the V(createcachetable), V(flush), V(loaddata), V(syncdb), and V(migrate) commands.
type: str
required: false
failfast:
@ -107,14 +106,13 @@ options:
type: bool
merge:
description:
- Will run out-of-order or missing migrations as they are not rollback migrations, you can only use this
parameter with V(migrate) command.
- Will run out-of-order or missing migrations as they are not rollback migrations, you can only use this parameter with
V(migrate) command.
required: false
type: bool
link:
description:
- Will create links to the files instead of copying them, you can only use this parameter with
V(collectstatic) command.
- Will create links to the files instead of copying them, you can only use this parameter with V(collectstatic) command.
required: false
type: bool
testrunner:
@ -132,20 +130,17 @@ options:
version_added: 5.8.0
notes:
- >
B(ATTENTION): Support for Django releases older than 4.1 has been removed in
community.general version 9.0.0. While the module allows for free-form commands
does not verify the version of Django being used, it is B(strongly recommended)
to use a more recent version of Django.
- 'B(ATTENTION): Support for Django releases older than 4.1 has been removed in community.general version 9.0.0. While the
module allows for free-form commands, not verifying the version of Django being used, it is B(strongly recommended) to
use a more recent version of the framework.'
- Please notice that Django 4.1 requires Python 3.8 or greater.
- This module will not create a virtualenv if the O(virtualenv) parameter is specified and a virtual environment
does not already exist at the given location. This behavior changed in community.general version 9.0.0.
- This module will not create a virtualenv if the O(virtualenv) parameter is specified and a virtual environment does not
already exist at the given location. This behavior changed in community.general version 9.0.0.
- The recommended way to create a virtual environment in Ansible is by using M(ansible.builtin.pip).
- This module assumes English error messages for the V(createcachetable) command to detect table existence,
unfortunately.
- This module assumes English error messages for the V(createcachetable) command to detect table existence, unfortunately.
- To be able to use the V(collectstatic) command, you must have enabled C(staticfiles) in your settings.
- Your C(manage.py) application must be executable (C(rwxr-xr-x)), and must have a valid shebang,
for example C(#!/usr/bin/env python), for invoking the appropriate Python interpreter.
- Your C(manage.py) application must be executable (C(rwxr-xr-x)), and must have a valid shebang, for example C(#!/usr/bin/env
python), for invoking the appropriate Python interpreter.
seealso:
- name: django-admin and manage.py Reference
description: Reference for C(django-admin) or C(manage.py) commands.
@ -156,13 +151,13 @@ seealso:
- name: What Python version can I use with Django?
description: From the Django FAQ, the response to Python requirements for the framework.
link: https://docs.djangoproject.com/en/dev/faq/install/#what-python-version-can-i-use-with-django
requirements: [ "django >= 4.1" ]
requirements: ["django >= 4.1"]
author:
- Alexei Znamensky (@russoz)
- Scott Anderson (@tastychutney)
'''
"""
EXAMPLES = """
EXAMPLES = r"""
- name: Run cleanup on the application installed in django_dir
community.general.django_manage:
command: clearsessions

15
plugins/modules/dnf_config_manager.py
View File

@ -7,8 +7,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: dnf_config_manager
short_description: Enable or disable dnf repositories using config-manager
version_added: 8.2.0
@ -43,9 +42,9 @@ options:
seealso:
- module: ansible.builtin.dnf
- module: ansible.builtin.yum_repository
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Ensure the crb repository is enabled
community.general.dnf_config_manager:
name: crb
@ -57,9 +56,9 @@ EXAMPLES = r'''
- appstream
- zfs
state: disabled
'''
"""
RETURN = r'''
RETURN = r"""
repo_states_pre:
description: Repo IDs before action taken.
returned: success
@ -119,8 +118,8 @@ changed_repos:
returned: success
type: list
elements: str
sample: [ 'crb' ]
'''
sample: ['crb']
"""
from ansible.module_utils.basic import AnsibleModule
import os

80
plugins/modules/dnf_versionlock.py
View File

@ -7,37 +7,32 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: dnf_versionlock
version_added: '4.0.0'
short_description: Locks package versions in C(dnf) based systems
description:
- Locks package versions using the C(versionlock) plugin in C(dnf) based
systems. This plugin takes a set of name and versions for packages and
excludes all other versions of those packages. This allows you to for example
protect packages from being updated by newer versions. The state of the
plugin that reflects locking of packages is the C(locklist).
- Locks package versions using the C(versionlock) plugin in C(dnf) based systems. This plugin takes a set of name and versions
for packages and excludes all other versions of those packages. This allows you to for example protect packages from being
updated by newer versions. The state of the plugin that reflects locking of packages is the C(locklist).
extends_documentation_fragment:
- community.general.attributes
attributes:
check_mode:
support: partial
details:
- The logics of the C(versionlock) plugin for corner cases could be
confusing, so please take in account that this module will do its best to
give a C(check_mode) prediction on what is going to happen. In case of
doubt, check the documentation of the plugin.
- Sometimes the module could predict changes in C(check_mode) that will not
be such because C(versionlock) concludes that there is already a entry in
C(locklist) that already matches.
- The logics of the C(versionlock) plugin for corner cases could be confusing, so please take in account that this module
will do its best to give a C(check_mode) prediction on what is going to happen. In case of doubt, check the documentation
of the plugin.
- Sometimes the module could predict changes in C(check_mode) that will not be such because C(versionlock) concludes
that there is already a entry in C(locklist) that already matches.
diff_mode:
support: none
options:
name:
description:
- Package name spec to add or exclude to or delete from the C(locklist)
using the format expected by the C(dnf repoquery) command.
- Package name spec to add or exclude to or delete from the C(locklist) using the format expected by the C(dnf repoquery)
command.
- This parameter is mutually exclusive with O(state=clean).
type: list
required: false
@ -45,43 +40,34 @@ options:
default: []
raw:
description:
- Do not resolve package name specs to NEVRAs to find specific version
to lock to. Instead the package name specs are used as they are. This
enables locking to not yet available versions of the package.
- Do not resolve package name specs to NEVRAs to find specific version to lock to. Instead the package name specs are
used as they are. This enables locking to not yet available versions of the package.
type: bool
default: false
state:
description:
- Whether to add (V(present) or V(excluded)) to or remove (V(absent) or
V(clean)) from the C(locklist).
- V(present) will add a package name spec to the C(locklist). If there is a
installed package that matches, then only that version will be added.
Otherwise, all available package versions will be added.
- V(excluded) will add a package name spec as excluded to the
C(locklist). It means that packages represented by the package name
spec will be excluded from transaction operations. All available
package versions will be added.
- V(absent) will delete entries in the C(locklist) that match the
package name spec.
- V(clean) will delete all entries in the C(locklist). This option is
mutually exclusive with O(name).
choices: [ 'absent', 'clean', 'excluded', 'present' ]
- Whether to add (V(present) or V(excluded)) to or remove (V(absent) or V(clean)) from the C(locklist).
- V(present) will add a package name spec to the C(locklist). If there is a installed package that matches, then only
that version will be added. Otherwise, all available package versions will be added.
- V(excluded) will add a package name spec as excluded to the C(locklist). It means that packages represented by the
package name spec will be excluded from transaction operations. All available package versions will be added.
- V(absent) will delete entries in the C(locklist) that match the package name spec.
- V(clean) will delete all entries in the C(locklist). This option is mutually exclusive with O(name).
choices: ['absent', 'clean', 'excluded', 'present']
type: str
default: present
notes:
- In an ideal world, the C(versionlock) plugin would have a dry-run option to
know for sure what is going to happen. So far we have to work with a best
guess as close as possible to the behaviour inferred from its code.
- For most of cases where you want to lock and unlock specific versions of a
package, this works fairly well.
- In an ideal world, the C(versionlock) plugin would have a dry-run option to know for sure what is going to happen. So
far we have to work with a best guess as close as possible to the behaviour inferred from its code.
- For most of cases where you want to lock and unlock specific versions of a package, this works fairly well.
requirements:
- dnf
- dnf-plugin-versionlock
author:
- Roberto Moreda (@moreda) <moreda@allenta.com>
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Prevent installed nginx from being updated
community.general.dnf_versionlock:
name: nginx
@ -113,34 +99,34 @@ EXAMPLES = r'''
- name: Delete all entries in the locklist of versionlock
community.general.dnf_versionlock:
state: clean
'''
"""
RETURN = r'''
RETURN = r"""
locklist_pre:
description: Locklist before module execution.
returned: success
type: list
elements: str
sample: [ 'bash-0:4.4.20-1.el8_4.*', '!bind-32:9.11.26-4.el8_4.*' ]
sample: ['bash-0:4.4.20-1.el8_4.*', '!bind-32:9.11.26-4.el8_4.*']
locklist_post:
description: Locklist after module execution.
returned: success and (not check mode or state is clean)
type: list
elements: str
sample: [ 'bash-0:4.4.20-1.el8_4.*' ]
sample: ['bash-0:4.4.20-1.el8_4.*']
specs_toadd:
description: Package name specs meant to be added by versionlock.
returned: success
type: list
elements: str
sample: [ 'bash' ]
sample: ['bash']
specs_todelete:
description: Package name specs meant to be deleted by versionlock.
returned: success
type: list
elements: str
sample: [ 'bind' ]
'''
sample: ['bind']
"""
from ansible.module_utils.basic import AnsibleModule
import fnmatch

26
plugins/modules/dnsimple.py
View File

@ -10,12 +10,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: dnsimple
short_description: Interface with dnsimple.com (a DNS hosting service)
description:
- "Manages domains and records via the DNSimple API, see the docs: U(http://developer.dnsimple.com/)."
- 'Manages domains and records using the DNSimple API, see the docs: U(http://developer.dnsimple.com/).'
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -27,8 +26,8 @@ options:
account_email:
description:
- Account email. If omitted, the environment variables E(DNSIMPLE_EMAIL) and E(DNSIMPLE_API_TOKEN) will be looked for.
- "If those aren't found, a C(.dnsimple) file will be looked for, see: U(https://github.com/mikemaccana/dnsimple-python#getting-started)."
- "C(.dnsimple) config files are only supported in dnsimple-python<2.0.0"
- "If those variables are not found, a C(.dnsimple) file will be looked for, see: U(https://github.com/mikemaccana/dnsimple-python#getting-started)."
- C(.dnsimple) config files are only supported in dnsimple-python<2.0.0.
type: str
account_api_token:
description:
@ -36,9 +35,9 @@ options:
type: str
domain:
description:
- Domain to work with. Can be the domain name (e.g. "mydomain.com") or the numeric ID of the domain in DNSimple.
- Domain to work with. Can be the domain name (for example V(mydomain.com)) or the numeric ID of the domain in DNSimple.
- If omitted, a list of domains will be returned.
- If domain is present but the domain doesn't exist, it will be created.
- If domain is present but the domain does not exist, it will be created.
type: str
record:
description:
@ -52,7 +51,8 @@ options:
type:
description:
- The type of DNS record to create.
choices: [ 'A', 'ALIAS', 'CNAME', 'MX', 'SPF', 'URL', 'TXT', 'NS', 'SRV', 'NAPTR', 'PTR', 'AAAA', 'SSHFP', 'HINFO', 'POOL', 'CAA' ]
choices: ['A', 'ALIAS', 'CNAME', 'MX', 'SPF', 'URL', 'TXT', 'NS', 'SRV', 'NAPTR', 'PTR', 'AAAA', 'SSHFP', 'HINFO', 'POOL',
'CAA']
type: str
ttl:
description:
@ -70,8 +70,8 @@ options:
type: int
state:
description:
- whether the record should exist or not.
choices: [ 'present', 'absent' ]
- Whether the record should exist or not.
choices: ['present', 'absent']
default: present
type: str
solo:
@ -91,9 +91,9 @@ options:
requirements:
- "dnsimple >= 2.0.0"
author: "Alex Coomans (@drcapulet)"
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Authenticate using email and API token and fetch all domains
community.general.dnsimple:
account_email: test@example.com
@ -149,7 +149,7 @@ EXAMPLES = '''
value: example.com
state: absent
delegate_to: localhost
'''
"""
RETURN = r"""# """

21
plugins/modules/dnsimple_info.py
View File

@ -9,8 +9,7 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: dnsimple_info
short_description: Pull basic info from DNSimple API
@ -56,9 +55,9 @@ options:
author:
- Edward Hilgendorf (@edhilgendorf)
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Get all domains from an account
community.general.dnsimple_info:
account_id: "1234"
@ -76,9 +75,9 @@ EXAMPLES = r'''
record: "subdomain"
account_id: "1234"
api_key: "1234"
'''
"""
RETURN = r'''
RETURN = r"""
dnsimple_domain_info:
description: Returns a list of dictionaries of all domains associated with the supplied account ID.
type: list
@ -126,8 +125,8 @@ dnsimple_records_info:
created_at: '2021-10-16T19:07:34Z'
id: 12345
name: 'catheadbiscuit'
parent_id: null
priority: null
parent_id:
priority:
regions:
- global
system_record: true
@ -182,8 +181,8 @@ dnsimple_record_info:
created_at: '2021-11-15T23:55:51Z'
id: 123456
name: catheadbiscuit
parent_id: null
priority: null
parent_id:
priority:
regions:
- global
system_record: false
@ -228,7 +227,7 @@ dnsimple_record_info:
zone_id:
description: ID of the zone that the record is associated with.
type: str
'''
"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils import deps

61
plugins/modules/dnsmadeeasy.py
View File

@ -9,14 +9,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: dnsmadeeasy
short_description: Interface with dnsmadeeasy.com (a DNS hosting service)
description:
- >
Manages DNS records via the v2 REST API of the DNS Made Easy service. It handles records only; there is no manipulation of domains or
monitor/account support yet. See: U(https://www.dnsmadeeasy.com/integration/restapi/)
- 'Manages DNS records using the v2 REST API of the DNS Made Easy service. It handles records only; there is no manipulation
of domains or monitor/account support yet. See: U(https://www.dnsmadeeasy.com/integration/restapi/).'
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -39,8 +37,8 @@ options:
domain:
description:
- Domain to work with. Can be the domain name (e.g. "mydomain.com") or the numeric ID of the domain in DNS Made Easy (e.g. "839989") for faster
resolution
- Domain to work with. Can be the domain name (for example V(mydomain.com)) or the numeric ID of the domain in DNS Made Easy
(for example V(839989)) for faster resolution.
required: true
type: str
@ -52,43 +50,41 @@ options:
record_name:
description:
- Record name to get/create/delete/update. If record_name is not specified; all records for the domain will be returned in "result" regardless
of the state argument.
- Record name to get/create/delete/update. If record_name is not specified; all records for the domain will be returned
in "result" regardless of the state argument.
type: str
record_type:
description:
- Record type.
choices: [ 'A', 'AAAA', 'CNAME', 'ANAME', 'HTTPRED', 'MX', 'NS', 'PTR', 'SRV', 'TXT' ]
choices: ['A', 'AAAA', 'CNAME', 'ANAME', 'HTTPRED', 'MX', 'NS', 'PTR', 'SRV', 'TXT']
type: str
record_value:
description:
- >
Record value. HTTPRED: <redirection URL>, MX: <priority> <target name>, NS: <name server>, PTR: <target name>,
SRV: <priority> <weight> <port> <target name>, TXT: <text value>"
- >
If record_value is not specified; no changes will be made and the record will be returned in 'result'
(in other words, this module can be used to fetch a record's current id, type, and ttl)
- 'Record value. HTTPRED: <redirection URL>, MX: <priority> <target name>, NS: <name server>, PTR: <target name>, SRV:
<priority> <weight> <port> <target name>, TXT: <text value>".'
- If record_value is not specified; no changes will be made and the record will be returned in 'result' (in other words,
this module can be used to fetch a record's current id, type, and ttl).
type: str
record_ttl:
description:
- record's "Time to live". Number of seconds the record remains cached in DNS servers.
- Record's "Time-To-Live". Number of seconds the record remains cached in DNS servers.
default: 1800
type: int
state:
description:
- whether the record should exist or not
- Whether the record should exist or not.
required: true
choices: [ 'present', 'absent' ]
choices: ['present', 'absent']
type: str
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
@ -192,20 +188,19 @@ options:
type: str
notes:
- The DNS Made Easy service requires that machines interacting with the API have the proper time and timezone set. Be sure you are within a few
seconds of actual time by using NTP.
- This module returns record(s) and monitor(s) in the "result" element when 'state' is set to 'present'.
These values can be be registered and used in your playbooks.
- The DNS Made Easy service requires that machines interacting with the API have the proper time and timezone set. Be sure
you are within a few seconds of actual time by using NTP.
- This module returns record(s) and monitor(s) in the "result" element when O(state=present). These values can
be be registered and used in your playbooks.
- Only A records can have a monitor or failover.
- To add failover, the 'failover', 'autoFailover', 'port', 'protocol', 'ip1', and 'ip2' options are required.
- To add monitor, the 'monitor', 'port', 'protocol', 'maxEmails', 'systemDescription', and 'ip1' options are required.
- The monitor and the failover will share 'port', 'protocol', and 'ip1' options.
requirements: [ hashlib, hmac ]
- To add failover, the O(failover), O(autoFailover), O(port), O(protocol), O(ip1), and O(ip2) options are required.
- To add monitor, the O(monitor), O(port), O(protocol), O(maxEmails), O(systemDescription), and O(ip1) options are required.
- The monitor and the failover will share O(port), O(protocol), and O(ip1) options.
requirements: [hashlib, hmac]
author: "Brice Burgess (@briceburg)"
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Fetch my.com domain records
community.general.dnsmadeeasy:
account_key: key
@ -357,7 +352,7 @@ EXAMPLES = '''
record_type: A
record_value: 127.0.0.1
monitor: false
'''
"""
# ============================================
# DNSMadeEasy module specific support methods.

68
plugins/modules/dpkg_divert.py
View File

@ -9,24 +9,20 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: dpkg_divert
short_description: Override a debian package's version of a file
version_added: '0.2.0'
author:
- quidame (@quidame)
description:
- A diversion is for C(dpkg) the knowledge that only a given package
(or the local administrator) is allowed to install a file at a given
location. Other packages shipping their own version of this file will
be forced to O(divert) it, that is to install it at another location. It
allows one to keep changes in a file provided by a debian package by
preventing its overwrite at package upgrade.
- This module manages diversions of debian packages files using the
C(dpkg-divert) commandline tool. It can either create or remove a
diversion for a given file, but also update an existing diversion
to modify its O(holder) and/or its O(divert) location.
- A diversion is for C(dpkg) the knowledge that only a given package (or the local administrator) is allowed to install
a file at a given location. Other packages shipping their own version of this file will be forced to O(divert) it, that
is to install it at another location. It allows one to keep changes in a file provided by a debian package by preventing
its overwrite at package upgrade.
- This module manages diversions of debian packages files using the C(dpkg-divert) commandline tool. It can either create
or remove a diversion for a given file, but also update an existing diversion to modify its O(holder) and/or its O(divert)
location.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -37,28 +33,23 @@ attributes:
options:
path:
description:
- The original and absolute path of the file to be diverted or
undiverted. This path is unique, i.e. it is not possible to get
two diversions for the same O(path).
- The original and absolute path of the file to be diverted or undiverted. This path is unique, in other words it is not possible
to get two diversions for the same O(path).
required: true
type: path
state:
description:
- When O(state=absent), remove the diversion of the specified
O(path); when O(state=present), create the diversion if it does
not exist, or update its package O(holder) or O(divert) location,
if it already exists.
- When O(state=absent), remove the diversion of the specified O(path); when O(state=present), create the diversion if
it does not exist, or update its package O(holder) or O(divert) location, if it already exists.
type: str
default: present
choices: [absent, present]
holder:
description:
- The name of the package whose copy of file is not diverted, also
known as the diversion holder or the package the diversion belongs
to.
- The actual package does not have to be installed or even to exist
for its name to be valid. If not specified, the diversion is hold
by 'LOCAL', that is reserved by/for dpkg for local diversions.
- The name of the package whose copy of file is not diverted, also known as the diversion holder or the package the
diversion belongs to.
- The actual package does not have to be installed or even to exist for its name to be valid. If not specified, the
diversion is hold by 'LOCAL', that is reserved by/for dpkg for local diversions.
- This parameter is ignored when O(state=absent).
type: str
divert:
@ -69,28 +60,25 @@ options:
type: path
rename:
description:
- Actually move the file aside (when O(state=present)) or back (when
O(state=absent)), but only when changing the state of the diversion.
This parameter has no effect when attempting to add a diversion that
already exists or when removing an unexisting one.
- Unless O(force=true), renaming fails if the destination file already
exists (this lock being a dpkg-divert feature, and bypassing it being
a module feature).
- Actually move the file aside (when O(state=present)) or back (when O(state=absent)), but only when changing the state
of the diversion. This parameter has no effect when attempting to add a diversion that already exists or when removing
an unexisting one.
- Unless O(force=true), renaming fails if the destination file already exists (this lock being a dpkg-divert feature,
and bypassing it being a module feature).
type: bool
default: false
force:
description:
- When O(rename=true) and O(force=true), renaming is performed even if
the target of the renaming exists, i.e. the existing contents of the
file at this location will be lost.
- When O(rename=true) and O(force=true), renaming is performed even if the target of the renaming exists, in other words the existing
contents of the file at this location will be lost.
- This parameter is ignored when O(rename=false).
type: bool
default: false
requirements:
- dpkg-divert >= 1.15.0 (Debian family)
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Divert /usr/bin/busybox to /usr/bin/busybox.distrib and keep file in place
community.general.dpkg_divert:
path: /usr/bin/busybox
@ -112,9 +100,9 @@ EXAMPLES = r'''
state: absent
rename: true
force: true
'''
"""
RETURN = r'''
RETURN = r"""
commands:
description: The dpkg-divert commands ran internally by the module.
type: list
@ -151,7 +139,7 @@ diversion:
"path": "/etc/foobarrc",
"state": "present"
}
'''
"""
import re

44
plugins/modules/easy_install.py
View File

@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: easy_install
short_description: Installs Python libraries
description:
- Installs Python libraries, optionally in a C(virtualenv)
- Installs Python libraries, optionally in a C(virtualenv).
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -31,31 +30,25 @@ options:
virtualenv:
type: str
description:
- An optional O(virtualenv) directory path to install into. If the
O(virtualenv) does not exist, it is created automatically.
- An optional O(virtualenv) directory path to install into. If the O(virtualenv) does not exist, it is created automatically.
virtualenv_site_packages:
description:
- Whether the virtual environment will inherit packages from the
global site-packages directory. Note that if this setting is
changed on an already existing virtual environment it will not
have any effect, the environment must be deleted and newly
created.
- Whether the virtual environment will inherit packages from the global site-packages directory. Note that if this setting
is changed on an already existing virtual environment it will not have any effect, the environment must be deleted
and newly created.
type: bool
default: false
virtualenv_command:
type: str
description:
- The command to create the virtual environment with. For example
V(pyvenv), V(virtualenv), V(virtualenv2).
- The command to create the virtual environment with. For example V(pyvenv), V(virtualenv), V(virtualenv2).
default: virtualenv
executable:
type: str
description:
- The explicit executable or a pathname to the executable to be used to
run easy_install for a specific version of Python installed in the
system. For example V(easy_install-3.3), if there are both Python 2.7
and 3.3 installations in the system and you want to run easy_install
for the Python 3.3 installation.
- The explicit executable or a pathname to the executable to be used to run easy_install for a specific version of Python
installed in the system. For example V(easy_install-3.3), if there are both Python 2.7 and 3.3 installations in the
system and you want to run easy_install for the Python 3.3 installation.
default: easy_install
state:
type: str
@ -64,17 +57,14 @@ options:
choices: [present, latest]
default: present
notes:
- Please note that the C(easy_install) module can only install Python
libraries. Thus this module is not able to remove libraries. It is
generally recommended to use the M(ansible.builtin.pip) module which you can first install
using M(community.general.easy_install).
- Also note that C(virtualenv) must be installed on the remote host if the
O(virtualenv) parameter is specified.
requirements: [ "virtualenv" ]
- Please note that the C(easy_install) module can only install Python libraries. Thus this module is not able to remove
libraries. It is generally recommended to use the M(ansible.builtin.pip) module which you can first install using M(community.general.easy_install).
- Also note that C(virtualenv) must be installed on the remote host if the O(virtualenv) parameter is specified.
requirements: ["virtualenv"]
author: "Matt Wright (@mattupstate)"
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Install or update pip
community.general.easy_install:
name: pip
@ -84,7 +74,7 @@ EXAMPLES = '''
community.general.easy_install:
name: bottle
virtualenv: /webapps/myapp/venv
'''
"""
import os
import os.path

25
plugins/modules/ejabberd_user.py
View File

@ -9,15 +9,14 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: ejabberd_user
author: "Peter Sprygada (@privateip)"
short_description: Manages users for ejabberd servers
requirements:
- ejabberd with mod_admin_extra
description:
- This module provides user management for ejabberd servers
- This module provides user management for ejabberd servers.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -29,31 +28,31 @@ options:
username:
type: str
description:
- the name of the user to manage
- The name of the user to manage.
required: true
host:
type: str
description:
- the ejabberd host associated with this username
- The ejabberd host associated with this username.
required: true
password:
type: str
description:
- the password to assign to the username
- The password to assign to the username.
required: false
state:
type: str
description:
- describe the desired state of the user to be managed
- Describe the desired state of the user to be managed.
required: false
default: 'present'
choices: [ 'present', 'absent' ]
choices: ['present', 'absent']
notes:
- Password parameter is required for state == present only
- Passwords must be stored in clear text for this release
- Password parameter is required for O(state=present) only.
- Passwords must be stored in clear text for this release.
- The ejabberd configuration file must include mod_admin_extra as a module.
'''
EXAMPLES = '''
"""
EXAMPLES = r"""
# Example playbook entries using the ejabberd_user module to manage users state.
- name: Create a user if it does not exist
@ -67,7 +66,7 @@ EXAMPLES = '''
username: test
host: server
state: absent
'''
"""
from ansible.module_utils.basic import AnsibleModule
from ansible_collections.community.general.plugins.module_utils.cmd_runner import CmdRunner, cmd_runner_fmt

35
plugins/modules/elasticsearch_plugin.py
View File

@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: elasticsearch_plugin
short_description: Manage Elasticsearch plugins
description:
@ -39,14 +38,12 @@ options:
type: str
src:
description:
- Optionally set the source location to retrieve the plugin from. This can be a file://
URL to install from a local file, or a remote URL. If this is not set, the plugin
location is just based on the name.
- Optionally set the source location to retrieve the plugin from. This can be a C(file://) URL to install from a local
file, or a remote URL. If this is not set, the plugin location is just based on the name.
- The name parameter must match the descriptor in the plugin ZIP specified.
- Is only used if the state would change, which is solely checked based on the name
parameter. If, for example, the plugin is already installed, changing this has no
effect.
- For ES 1.x use url.
- Is only used if the state would change, which is solely checked based on the name parameter. If, for example, the
plugin is already installed, changing this has no effect.
- For ES 1.x use O(url).
required: false
type: str
url:
@ -57,13 +54,14 @@ options:
type: str
timeout:
description:
- "Timeout setting: 30s, 1m, 1h..."
- 'Timeout setting: V(30s), V(1m), V(1h)...'
- Only valid for Elasticsearch < 5.0. This option is ignored for Elasticsearch > 5.0.
default: 1m
type: str
force:
description:
- "Force batch mode when installing plugins. This is only necessary if a plugin requires additional permissions and console detection fails."
- Force batch mode when installing plugins. This is only necessary if a plugin requires additional permissions and console
detection fails.
default: false
type: bool
plugin_bin:
@ -72,25 +70,24 @@ options:
type: path
plugin_dir:
description:
- Your configured plugin directory specified in Elasticsearch
- Your configured plugin directory specified in Elasticsearch.
default: /usr/share/elasticsearch/plugins/
type: path
proxy_host:
description:
- Proxy host to use during plugin installation
- Proxy host to use during plugin installation.
type: str
proxy_port:
description:
- Proxy port to use during plugin installation
- Proxy port to use during plugin installation.
type: str
version:
description:
- Version of the plugin to be installed.
If plugin exists with previous version, it will NOT be updated
- Version of the plugin to be installed. If plugin exists with previous version, it will NOT be updated.
type: str
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Install Elasticsearch Head plugin in Elasticsearch 2.x
community.general.elasticsearch_plugin:
name: mobz/elasticsearch-head
@ -116,7 +113,7 @@ EXAMPLES = '''
name: ingest-geoip
state: present
force: true
'''
"""
import os

22
plugins/modules/emc_vnx_sg_member.py
View File

@ -12,16 +12,14 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: emc_vnx_sg_member
short_description: Manage storage group member on EMC VNX
description:
- "This module manages the members of an existing storage group."
- This module manages the members of an existing storage group.
extends_documentation_fragment:
- community.general.emc.emc_vnx
- community.general.attributes
@ -46,18 +44,18 @@ options:
state:
description:
- Indicates the desired lunid state.
- V(present) ensures specified lunid is present in the Storage Group.
- V(absent) ensures specified lunid is absent from Storage Group.
- V(present) ensures specified O(lunid) is present in the Storage Group.
- V(absent) ensures specified O(lunid) is absent from Storage Group.
default: present
choices: [ "present", "absent"]
choices: ["present", "absent"]
type: str
author:
- Luca 'remix_tj' Lorenzetto (@remixtj)
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Add lun to storage group
community.general.emc_vnx_sg_member:
name: sg01
@ -75,14 +73,14 @@ EXAMPLES = '''
sp_password: sysadmin
lunid: 100
state: absent
'''
"""
RETURN = '''
RETURN = r"""
hluid:
description: LUNID that hosts attached to the storage group will see.
type: int
returned: success
'''
"""
import traceback

31
plugins/modules/etcd3.py
View File

@ -9,15 +9,14 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: etcd3
short_description: Set or delete key value pairs from an etcd3 cluster
requirements:
- etcd3
description:
- Sets or deletes values in etcd3 cluster using its v3 api.
- Needs python etcd3 lib to work
- Needs python etcd3 lib to work.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -29,30 +28,30 @@ options:
key:
type: str
description:
- the key where the information is stored in the cluster
- The key where the information is stored in the cluster.
required: true
value:
type: str
description:
- the information stored
- The information stored.
required: true
host:
type: str
description:
- the IP address of the cluster
- The IP address of the cluster.
default: 'localhost'
port:
type: int
description:
- the port number used to connect to the cluster
- The port number used to connect to the cluster.
default: 2379
state:
type: str
description:
- the state of the value for the key.
- can be present or absent
- The state of the value for the key.
- Can be present or absent.
required: true
choices: [ present, absent ]
choices: [present, absent]
user:
type: str
description:
@ -84,9 +83,9 @@ options:
author:
- Jean-Philippe Evrard (@evrardjp)
- Victor Fauth (@vfauth)
'''
"""
EXAMPLES = """
EXAMPLES = r"""
- name: Store a value "bar" under the key "foo" for a cluster located "http://localhost:2379"
community.general.etcd3:
key: "foo"
@ -114,16 +113,16 @@ EXAMPLES = """
client_key: "/etc/ssl/private/key.pem"
"""
RETURN = '''
RETURN = r"""
key:
description: The key that was queried
description: The key that was queried.
returned: always
type: str
old_value:
description: The previous value in the cluster
description: The previous value in the cluster.
returned: always
type: str
'''
"""
import traceback

14
plugins/modules/facter.py
View File

@ -8,14 +8,12 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: facter
short_description: Runs the discovery program C(facter) on the remote system
description:
- Runs the C(facter) discovery program
(U(https://github.com/puppetlabs/facter)) on the remote system, returning
JSON data that can be useful for inventory purposes.
- Runs the C(facter) discovery program (U(https://github.com/puppetlabs/facter)) on the remote system, returning JSON data
that can be useful for inventory purposes.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -35,9 +33,9 @@ requirements:
author:
- Ansible Core Team
- Michael DeHaan
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
# Example command-line invocation
# ansible www.example.net -m facter
@ -51,7 +49,7 @@ EXAMPLES = '''
- system_uptime
- timezone
- is_virtual
'''
"""
import json
from ansible.module_utils.basic import AnsibleModule

18
plugins/modules/facter_facts.py
View File

@ -9,15 +9,13 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: facter_facts
short_description: Runs the discovery program C(facter) on the remote system and return Ansible facts
version_added: 8.0.0
description:
- Runs the C(facter) discovery program
(U(https://github.com/puppetlabs/facter)) on the remote system, returning Ansible facts from the
JSON data that can be useful for inventory purposes.
- Runs the C(facter) discovery program (U(https://github.com/puppetlabs/facter)) on the remote system, returning Ansible
facts from the JSON data that can be useful for inventory purposes.
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes.facts
@ -34,9 +32,9 @@ requirements:
author:
- Ansible Core Team
- Michael DeHaan
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Execute facter no arguments
community.general.facter_facts:
@ -47,9 +45,9 @@ EXAMPLES = '''
- system_uptime
- timezone
- is_virtual
'''
"""
RETURN = r'''
RETURN = r"""
ansible_facts:
description: Dictionary with one key C(facter).
returned: always
@ -59,7 +57,7 @@ ansible_facts:
description: Dictionary containing facts discovered in the remote system.
returned: always
type: dict
'''
"""
import json

68
plugins/modules/filesize.py
View File

@ -9,17 +9,14 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: filesize
short_description: Create a file with a given size, or resize it if it exists
description:
- This module is a simple wrapper around C(dd) to create, extend or truncate
a file, given its size. It can be used to manage swap files (that require
contiguous blocks) or alternatively, huge sparse files.
- This module is a simple wrapper around C(dd) to create, extend or truncate a file, given its size. It can be used to manage
swap files (that require contiguous blocks) or alternatively, huge sparse files.
author:
- quidame (@quidame)
@ -40,36 +37,27 @@ options:
size:
description:
- Requested size of the file.
- The value is a number (either C(int) or C(float)) optionally followed
by a multiplicative suffix, that can be one of V(B) (bytes), V(KB) or
V(kB) (= 1000B), V(MB) or V(mB) (= 1000kB), V(GB) or V(gB) (= 1000MB),
and so on for V(T), V(P), V(E), V(Z) and V(Y); or alternatively one of
V(K), V(k) or V(KiB) (= 1024B); V(M), V(m) or V(MiB) (= 1024KiB);
- The value is a number (either C(int) or C(float)) optionally followed by a multiplicative suffix, that can be one
of V(B) (bytes), V(KB) or V(kB) (= 1000B), V(MB) or V(mB) (= 1000kB), V(GB) or V(gB) (= 1000MB), and so on for V(T),
V(P), V(E), V(Z) and V(Y); or alternatively one of V(K), V(k) or V(KiB) (= 1024B); V(M), V(m) or V(MiB) (= 1024KiB);
V(G), V(g) or V(GiB) (= 1024MiB); and so on.
- If the multiplicative suffix is not provided, the value is treated as
an integer number of blocks of O(blocksize) bytes each (float values
are rounded to the closest integer).
- If the multiplicative suffix is not provided, the value is treated as an integer number of blocks of O(blocksize)
bytes each (float values are rounded to the closest integer).
- When the O(size) value is equal to the current file size, does nothing.
- When the O(size) value is bigger than the current file size, bytes from
O(source) (if O(sparse) is not V(false)) are appended to the file
without truncating it, in other words, without modifying the existing
bytes of the file.
- When the O(size) value is smaller than the current file size, it is
truncated to the requested value without modifying bytes before this
value.
- That means that a file of any arbitrary size can be grown to any other
arbitrary size, and then resized down to its initial size without
modifying its initial content.
- When the O(size) value is bigger than the current file size, bytes from O(source) (if O(sparse) is not V(false)) are
appended to the file without truncating it, in other words, without modifying the existing bytes of the file.
- When the O(size) value is smaller than the current file size, it is truncated to the requested value without modifying
bytes before this value.
- That means that a file of any arbitrary size can be grown to any other arbitrary size, and then resized down to its
initial size without modifying its initial content.
type: raw
required: true
blocksize:
description:
- Size of blocks, in bytes if not followed by a multiplicative suffix.
- The numeric value (before the unit) B(MUST) be an integer (or a C(float)
if it equals an integer).
- If not set, the size of blocks is guessed from the OS and commonly
results in V(512) or V(4096) bytes, that is used internally by the
module or when O(size) has no unit.
- The numeric value (before the unit) B(MUST) be an integer (or a C(float) if it equals an integer).
- If not set, the size of blocks is guessed from the OS and commonly results in V(512) or V(4096) bytes, that is used
internally by the module or when O(size) has no unit.
type: raw
source:
description:
@ -79,26 +67,22 @@ options:
default: /dev/zero
force:
description:
- Whether or not to overwrite the file if it exists, in other words, to
truncate it from 0. When V(true), the module is not idempotent, that
means it always reports C(changed=true).
- Whether or not to overwrite the file if it exists, in other words, to truncate it from 0. When V(true), the module
is not idempotent, that means it always reports C(changed=true).
- O(force=true) and O(sparse=true) are mutually exclusive.
type: bool
default: false
sparse:
description:
- Whether or not the file to create should be a sparse file.
- This option is effective only on newly created files, or when growing a
file, only for the bytes to append.
- This option is effective only on newly created files, or when growing a file, only for the bytes to append.
- This option is not supported on OSes or filesystems not supporting sparse files.
- O(force=true) and O(sparse=true) are mutually exclusive.
type: bool
default: false
unsafe_writes:
description:
- This option is silently ignored. This module always modifies file
size in-place.
- This option is silently ignored. This module always modifies file size in-place.
requirements:
- dd (Data Duplicator) in PATH
@ -138,9 +122,9 @@ seealso:
- name: busybox(1) manpage for Linux
description: Manual page of the GNU/Linux's busybox, that provides its own dd implementation.
link: https://www.unix.com/man-page/linux/1/busybox
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Create a file of 1G filled with null bytes
community.general.filesize:
path: /var/bigfile
@ -183,9 +167,9 @@ EXAMPLES = r'''
mode: u=rw,go=
owner: root
group: root
'''
"""
RETURN = r'''
RETURN = r"""
cmd:
description: Command executed to create or resize the file.
type: str
@ -229,7 +213,7 @@ path:
type: str
sample: /var/swap0
returned: always
'''
"""
import re

76
plugins/modules/filesystem.py
View File

@ -10,8 +10,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
author:
- Alexander Bulimov (@abulimov)
- quidame (@quidame)
@ -29,33 +28,29 @@ attributes:
options:
state:
description:
- If O(state=present), the filesystem is created if it doesn't already
exist, that is the default behaviour if O(state) is omitted.
- If O(state=absent), filesystem signatures on O(dev) are wiped if it
contains a filesystem (as known by C(blkid)).
- When O(state=absent), all other options but O(dev) are ignored, and the
module does not fail if the device O(dev) doesn't actually exist.
- If O(state=present), the filesystem is created if it does not already exist, that is the default behaviour if O(state)
is omitted.
- If O(state=absent), filesystem signatures on O(dev) are wiped if it contains a filesystem (as known by C(blkid)).
- When O(state=absent), all other options but O(dev) are ignored, and the module does not fail if the device O(dev)
does not actually exist.
type: str
choices: [ present, absent ]
choices: [present, absent]
default: present
version_added: 1.3.0
fstype:
choices: [ bcachefs, btrfs, ext2, ext3, ext4, ext4dev, f2fs, lvm, ocfs2, reiserfs, xfs, vfat, swap, ufs ]
choices: [bcachefs, btrfs, ext2, ext3, ext4, ext4dev, f2fs, lvm, ocfs2, reiserfs, xfs, vfat, swap, ufs]
description:
- Filesystem type to be created. This option is required with
O(state=present) (or if O(state) is omitted).
- ufs support has been added in community.general 3.4.0.
- bcachefs support has been added in community.general 8.6.0.
- Filesystem type to be created. This option is required with O(state=present) (or if O(state) is omitted).
- Ufs support has been added in community.general 3.4.0.
- Bcachefs support has been added in community.general 8.6.0.
type: str
aliases: [type]
dev:
description:
- Target path to block device (Linux) or character device (FreeBSD) or
regular file (both).
- When setting Linux-specific filesystem types on FreeBSD, this module
only works when applying to regular files, aka disk images.
- Currently V(lvm) (Linux-only) and V(ufs) (FreeBSD-only) do not support
a regular file as their target O(dev).
- Target path to block device (Linux) or character device (FreeBSD) or regular file (both).
- When setting Linux-specific filesystem types on FreeBSD, this module only works when applying to regular files, aka
disk images.
- Currently V(lvm) (Linux-only) and V(ufs) (FreeBSD-only) do not support a regular file as their target O(dev).
- Support for character devices on FreeBSD has been added in community.general 3.4.0.
type: path
required: true
@ -68,12 +63,11 @@ options:
resizefs:
description:
- If V(true), if the block device and filesystem size differ, grow the filesystem into the space.
- Supported for C(bcachefs), C(btrfs), C(ext2), C(ext3), C(ext4), C(ext4dev), C(f2fs), C(lvm), C(xfs), C(ufs) and C(vfat) filesystems.
Attempts to resize other filesystem types will fail.
- XFS Will only grow if mounted. Currently, the module is based on commands
from C(util-linux) package to perform operations, so resizing of XFS is
not supported on FreeBSD systems.
- vFAT will likely fail if C(fatresize < 1.04).
- Supported for C(bcachefs), C(btrfs), C(ext2), C(ext3), C(ext4), C(ext4dev), C(f2fs), C(lvm), C(xfs), C(ufs) and C(vfat)
filesystems. Attempts to resize other filesystem types will fail.
- XFS Will only grow if mounted. Currently, the module is based on commands from C(util-linux) package to perform operations,
so resizing of XFS is not supported on FreeBSD systems.
- VFAT will likely fail if C(fatresize < 1.04).
- Mutually exclusive with O(uuid).
type: bool
default: false
@ -93,32 +87,28 @@ options:
type: str
version_added: 7.1.0
requirements:
- Uses specific tools related to the O(fstype) for creating or resizing a
filesystem (from packages e2fsprogs, xfsprogs, dosfstools, and so on).
- Uses generic tools mostly related to the Operating System (Linux or
FreeBSD) or available on both, as C(blkid).
- Uses specific tools related to the O(fstype) for creating or resizing a filesystem (from packages e2fsprogs, xfsprogs,
dosfstools, and so on).
- Uses generic tools mostly related to the Operating System (Linux or FreeBSD) or available on both, as C(blkid).
- On FreeBSD, either C(util-linux) or C(e2fsprogs) package is required.
notes:
- Potential filesystems on O(dev) are checked using C(blkid). In case C(blkid)
is unable to detect a filesystem (and in case C(fstyp) on FreeBSD is also
unable to detect a filesystem), this filesystem is overwritten even if
O(force) is V(false).
- On FreeBSD systems, both C(e2fsprogs) and C(util-linux) packages provide
a C(blkid) command that is compatible with this module. However, these
packages conflict with each other, and only the C(util-linux) package
provides the command required to not fail when O(state=absent).
- Potential filesystems on O(dev) are checked using C(blkid). In case C(blkid) is unable to detect a filesystem (and in
case C(fstyp) on FreeBSD is also unable to detect a filesystem), this filesystem is overwritten even if O(force) is V(false).
- On FreeBSD systems, both C(e2fsprogs) and C(util-linux) packages provide a C(blkid) command that is compatible with this
module. However, these packages conflict with each other, and only the C(util-linux) package provides the command required
to not fail when O(state=absent).
seealso:
- module: community.general.filesize
- module: ansible.posix.mount
- name: xfs_admin(8) manpage for Linux
description: Manual page of the GNU/Linux's xfs_admin implementation
description: Manual page of the GNU/Linux's xfs_admin implementation.
link: https://man7.org/linux/man-pages/man8/xfs_admin.8.html
- name: tune2fs(8) manpage for Linux
description: Manual page of the GNU/Linux's tune2fs implementation
description: Manual page of the GNU/Linux's tune2fs implementation.
link: https://man7.org/linux/man-pages/man8/tune2fs.8.html
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Create a ext2 filesystem on /dev/sdb1
community.general.filesystem:
fstype: ext2
@ -157,7 +147,7 @@ EXAMPLES = '''
fstype: lvm
dev: /dev/sdc
uuid: random
'''
"""
import os
import platform

61
plugins/modules/flatpak.py
View File

@ -10,8 +10,7 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: flatpak
short_description: Manage flatpaks
description:
@ -41,43 +40,37 @@ options:
method:
description:
- The installation method to use.
- Defines if the C(flatpak) is supposed to be installed globally for the whole V(system)
or only for the current V(user).
- Defines if the C(flatpak) is supposed to be installed globally for the whole V(system) or only for the current V(user).
type: str
choices: [ system, user ]
choices: [system, user]
default: system
name:
description:
- The name of the flatpak to manage. To operate on several packages this
can accept a list of packages.
- When used with O(state=present), O(name) can be specified as a URL to a
C(flatpakref) file or the unique reverse DNS name that identifies a flatpak.
- The name of the flatpak to manage. To operate on several packages this can accept a list of packages.
- When used with O(state=present), O(name) can be specified as a URL to a C(flatpakref) file or the unique reverse DNS
name that identifies a flatpak.
- Both C(https://) and C(http://) URLs are supported.
- When supplying a reverse DNS name, you can use the O(remote) option to specify on what remote
to look for the flatpak. An example for a reverse DNS name is C(org.gnome.gedit).
- When used with O(state=absent) or O(state=latest), it is recommended to specify the name in
the reverse DNS format.
- When supplying a URL with O(state=absent) or O(state=latest), the module will try to match the
installed flatpak based on the name of the flatpakref to remove or update it. However, there
is no guarantee that the names of the flatpakref file and the reverse DNS name of the
installed flatpak do match.
- When supplying a reverse DNS name, you can use the O(remote) option to specify on what remote to look for the flatpak.
An example for a reverse DNS name is C(org.gnome.gedit).
- When used with O(state=absent) or O(state=latest), it is recommended to specify the name in the reverse DNS format.
- When supplying a URL with O(state=absent) or O(state=latest), the module will try to match the installed flatpak based
on the name of the flatpakref to remove or update it. However, there is no guarantee that the names of the flatpakref
file and the reverse DNS name of the installed flatpak do match.
type: list
elements: str
required: true
no_dependencies:
description:
- If installing runtime dependencies should be omitted or not
- This parameter is primarily implemented for integration testing this module.
There might however be some use cases where you would want to have this, like when you are
packaging your own flatpaks.
- If installing runtime dependencies should be omitted or not.
- This parameter is primarily implemented for integration testing this module. There might however be some use cases
where you would want to have this, like when you are packaging your own flatpaks.
type: bool
default: false
version_added: 3.2.0
remote:
description:
- The flatpak remote (repository) to install the flatpak from.
- By default, V(flathub) is assumed, but you do need to add the flathub flatpak_remote before
you can use this.
- By default, V(flathub) is assumed, but you do need to add the flathub flatpak_remote before you can use this.
- See the M(community.general.flatpak_remote) module for managing flatpak remotes.
type: str
default: flathub
@ -85,12 +78,12 @@ options:
description:
- Indicates the desired package state.
- The value V(latest) is supported since community.general 8.6.0.
choices: [ absent, present, latest ]
choices: [absent, present, latest]
type: str
default: present
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Install the spotify flatpak
community.general.flatpak:
name: https://s3.amazonaws.com/alexlarsson/spotify-repo/spotify.flatpakref
@ -164,35 +157,35 @@ EXAMPLES = r'''
- org.inkscape.Inkscape
- org.mozilla.firefox
state: absent
'''
"""
RETURN = r'''
RETURN = r"""
command:
description: The exact flatpak command that was executed
description: The exact flatpak command that was executed.
returned: When a flatpak command has been executed
type: str
sample: "/usr/bin/flatpak install --user --nontinteractive flathub org.gnome.Calculator"
msg:
description: Module error message
description: Module error message.
returned: failure
type: str
sample: "Executable '/usr/local/bin/flatpak' was not found on the system."
rc:
description: Return code from flatpak binary
description: Return code from flatpak binary.
returned: When a flatpak command has been executed
type: int
sample: 0
stderr:
description: Error output from flatpak binary
description: Error output from flatpak binary.
returned: When a flatpak command has been executed
type: str
sample: "error: Error searching remote flathub: Can't find ref org.gnome.KDE"
stdout:
description: Output from flatpak binary
description: Output from flatpak binary.
returned: When a flatpak command has been executed
type: str
sample: "org.gnome.Calendar/x86_64/stable\tcurrent\norg.gnome.gitg/x86_64/stable\tcurrent\n"
'''
"""
from ansible.module_utils.six.moves.urllib.parse import urlparse
from ansible.module_utils.basic import AnsibleModule

42
plugins/modules/flatpak_remote.py
View File

@ -10,15 +10,13 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: flatpak_remote
short_description: Manage flatpak repository remotes
description:
- Allows users to add or remove flatpak remotes.
- The flatpak remotes concept is comparable to what is called repositories in other packaging
formats.
- Currently, remote addition is only supported via C(flatpakrepo) file URLs.
- The flatpak remotes concept is comparable to what is called repositories in other packaging formats.
- Currently, remote addition is only supported using C(flatpakrepo) file URLs.
- Existing remotes will not be updated.
- See the M(community.general.flatpak) module for managing flatpaks.
author:
@ -43,24 +41,22 @@ options:
flatpakrepo_url:
description:
- The URL to the C(flatpakrepo) file representing the repository remote to add.
- When used with O(state=present), the flatpak remote specified under the O(flatpakrepo_url)
is added using the specified installation O(method).
- When used with O(state=present), the flatpak remote specified under the O(flatpakrepo_url) is added using the specified
installation O(method).
- When used with O(state=absent), this is not required.
- Required when O(state=present).
type: str
method:
description:
- The installation method to use.
- Defines if the C(flatpak) is supposed to be installed globally for the whole V(system)
or only for the current V(user).
- Defines if the C(flatpak) is supposed to be installed globally for the whole V(system) or only for the current V(user).
type: str
choices: [ system, user ]
choices: [system, user]
default: system
name:
description:
- The desired name for the flatpak remote to be registered under on the managed host.
- When used with O(state=present), the remote will be added to the managed host under
the specified O(name).
- When used with O(state=present), the remote will be added to the managed host under the specified O(name).
- When used with O(state=absent) the remote with that name will be removed.
type: str
required: true
@ -68,7 +64,7 @@ options:
description:
- Indicates the desired package state.
type: str
choices: [ absent, present ]
choices: [absent, present]
default: present
enabled:
description:
@ -76,9 +72,9 @@ options:
type: bool
default: true
version_added: 6.4.0
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Add the Gnome flatpak remote to the system installation
community.general.flatpak_remote:
name: gnome
@ -108,35 +104,35 @@ EXAMPLES = r'''
name: flathub
state: present
enabled: false
'''
"""
RETURN = r'''
RETURN = r"""
command:
description: The exact flatpak command that was executed
description: The exact flatpak command that was executed.
returned: When a flatpak command has been executed
type: str
sample: "/usr/bin/flatpak remote-add --system flatpak-test https://dl.flathub.org/repo/flathub.flatpakrepo"
msg:
description: Module error message
description: Module error message.
returned: failure
type: str
sample: "Executable '/usr/local/bin/flatpak' was not found on the system."
rc:
description: Return code from flatpak binary
description: Return code from flatpak binary.
returned: When a flatpak command has been executed
type: int
sample: 0
stderr:
description: Error output from flatpak binary
description: Error output from flatpak binary.
returned: When a flatpak command has been executed
type: str
sample: "error: GPG verification enabled, but no summary found (check that the configured URL in remote config is correct)\n"
stdout:
description: Output from flatpak binary
description: Output from flatpak binary.
returned: When a flatpak command has been executed
type: str
sample: "flathub\tFlathub\thttps://dl.flathub.org/repo/\t1\t\n"
'''
"""
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.common.text.converters import to_bytes, to_native