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

s[e-n]*: normalize docs (#9352) 

* s[e-n]*: normalize docs

* Apply suggestions from code review

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

* quote line with : and remove extraneous notes

* Update plugins/modules/slack.py

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

* Update plugins/modules/seport.py

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

---------

Co-authored-by: Felix Fontein <felix@fontein.de>
pull/9101/merge
Alexei Znamensky 2024-12-26 20:22:58 +13:00 committed by GitHub
parent bef82e28a2
commit 9fc3092bb3
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
20 changed files with 627 additions and 689 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

94
plugins/modules/sefcontext.py
View File

@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: sefcontext
short_description: Manages SELinux file context mapping definitions
description:
@ -28,85 +27,82 @@ attributes:
options:
target:
description:
- Target path (expression).
- Target path (expression).
type: str
required: true
aliases: [ path ]
aliases: [path]
ftype:
description:
- The file type that should have SELinux contexts applied.
- "The following file type options are available:"
- V(a) for all files,
- V(b) for block devices,
- V(c) for character devices,
- V(d) for directories,
- V(f) for regular files,
- V(l) for symbolic links,
- V(p) for named pipes,
- V(s) for socket files.
- The file type that should have SELinux contexts applied.
- 'The following file type options are available:'
- V(a) for all files,
- V(b) for block devices,
- V(c) for character devices,
- V(d) for directories,
- V(f) for regular files,
- V(l) for symbolic links,
- V(p) for named pipes,
- V(s) for socket files.
type: str
choices: [ a, b, c, d, f, l, p, s ]
choices: [a, b, c, d, f, l, p, s]
default: a
setype:
description:
- SELinux type for the specified O(target).
- SELinux type for the specified O(target).
type: str
substitute:
description:
- Path to use to substitute file context(s) for the specified O(target). The context labeling for the O(target) subtree is made equivalent to this path.
- This is also referred to as SELinux file context equivalence and it implements the C(equal) functionality of the SELinux management tools.
- Path to use to substitute file context(s) for the specified O(target). The context labeling for the O(target) subtree is made equivalent
to this path.
- This is also referred to as SELinux file context equivalence and it implements the C(equal) functionality of the SELinux management tools.
version_added: 6.4.0
type: str
aliases: [ equal ]
aliases: [equal]
seuser:
description:
- SELinux user for the specified O(target).
- Defaults to V(system_u) for new file contexts and to existing value when modifying file contexts.
- SELinux user for the specified O(target).
- Defaults to V(system_u) for new file contexts and to existing value when modifying file contexts.
type: str
selevel:
description:
- SELinux range for the specified O(target).
- Defaults to V(s0) for new file contexts and to existing value when modifying file contexts.
- SELinux range for the specified O(target).
- Defaults to V(s0) for new file contexts and to existing value when modifying file contexts.
type: str
aliases: [ serange ]
aliases: [serange]
state:
description:
- Whether the SELinux file context must be V(absent) or V(present).
- Specifying V(absent) without either O(setype) or O(substitute) deletes both SELinux type or path substitution mappings that match O(target).
- Whether the SELinux file context must be V(absent) or V(present).
- Specifying V(absent) without either O(setype) or O(substitute) deletes both SELinux type or path substitution mappings that match O(target).
type: str
choices: [ absent, present ]
choices: [absent, present]
default: present
reload:
description:
- Reload SELinux policy after commit.
- Note that this does not apply SELinux file contexts to existing files.
- Reload SELinux policy after commit.
- Note that this does not apply SELinux file contexts to existing files.
type: bool
default: true
ignore_selinux_state:
description:
- Useful for scenarios (chrooted environment) that you can't get the real SELinux state.
- Useful for scenarios (chrooted environment) that you cannot get the real SELinux state.
type: bool
default: false
notes:
- The changes are persistent across reboots.
- O(setype) and O(substitute) are mutually exclusive.
- If O(state=present) then one of O(setype) or O(substitute) is mandatory.
- The M(community.general.sefcontext) module does not modify existing files to the new
SELinux context(s), so it is advisable to first create the SELinux
file contexts before creating files, or run C(restorecon) manually
for the existing files that require the new SELinux file contexts.
- Not applying SELinux fcontexts to existing files is a deliberate
decision as it would be unclear what reported changes would entail
to, and there's no guarantee that applying SELinux fcontext does
not pick up other unrelated prior changes.
- The changes are persistent across reboots.
- O(setype) and O(substitute) are mutually exclusive.
- If O(state=present) then one of O(setype) or O(substitute) is mandatory.
- The M(community.general.sefcontext) module does not modify existing files to the new SELinux context(s), so it is advisable to first create
the SELinux file contexts before creating files, or run C(restorecon) manually for the existing files that require the new SELinux file contexts.
- Not applying SELinux fcontexts to existing files is a deliberate decision as it would be unclear what reported changes would entail to, and
there is no guarantee that applying SELinux fcontext does not pick up other unrelated prior changes.
requirements:
- libselinux-python
- policycoreutils-python
- libselinux-python
- policycoreutils-python
author:
- Dag Wieers (@dagwieers)
'''
- Dag Wieers (@dagwieers)
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Allow apache to modify files in /srv/git_repos
community.general.sefcontext:
target: '/srv/git_repos(/.*)?'
@ -132,11 +128,11 @@ EXAMPLES = r'''
- name: Apply new SELinux file context to filesystem
ansible.builtin.command: restorecon -irv /srv/git_repos
'''
"""
RETURN = r'''
RETURN = r"""
# Default return values
'''
"""
import traceback

27
plugins/modules/selinux_permissive.py
View File

@ -9,8 +9,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: selinux_permissive
short_description: Change permissive domain in SELinux policy
description:
@ -25,20 +24,20 @@ attributes:
options:
domain:
description:
- The domain that will be added or removed from the list of permissive domains.
- The domain that will be added or removed from the list of permissive domains.
type: str
required: true
aliases: [ name ]
aliases: [name]
permissive:
description:
- Indicate if the domain should or should not be set as permissive.
- Indicate if the domain should or should not be set as permissive.
type: bool
required: true
no_reload:
description:
- Disable reloading of the SELinux policy after making change to a domain's permissive setting.
- The default is V(false), which causes policy to be reloaded when a domain changes state.
- Reloading the policy does not work on older versions of the C(policycoreutils-python) library, for example in EL 6."
- Disable reloading of the SELinux policy after making change to a domain's permissive setting.
- The default is V(false), which causes policy to be reloaded when a domain changes state.
- Reloading the policy does not work on older versions of the C(policycoreutils-python) library, for example in EL 6.".
type: bool
default: false
store:
@ -47,18 +46,18 @@ options:
type: str
default: ''
notes:
- Requires a recent version of SELinux and C(policycoreutils-python) (EL 6 or newer).
requirements: [ policycoreutils-python ]
- Requires a recent version of SELinux and C(policycoreutils-python) (EL 6 or newer).
requirements: [policycoreutils-python]
author:
- Michael Scherer (@mscherer) <misc@zarb.org>
'''
- Michael Scherer (@mscherer) <misc@zarb.org>
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Change the httpd_t domain to permissive
community.general.selinux_permissive:
name: httpd_t
permissive: true
'''
"""
import traceback

37
plugins/modules/selogin.py
View File

@ -8,12 +8,11 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: selogin
short_description: Manages linux user to SELinux user mapping
description:
- Manages linux user to SELinux user mapping
- Manages linux user to SELinux user mapping.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -25,15 +24,15 @@ options:
login:
type: str
description:
- a Linux user
- A Linux user.
required: true
seuser:
type: str
description:
- SELinux user name
- SELinux user name.
selevel:
type: str
aliases: [ serange ]
aliases: [serange]
description:
- MLS/MCS Security Range (MLS/MCS Systems only) SELinux Range for SELinux login mapping defaults to the SELinux user record range.
default: s0
@ -42,7 +41,7 @@ options:
description:
- Desired mapping value.
default: present
choices: [ 'present', 'absent' ]
choices: ['present', 'absent']
reload:
description:
- Reload SELinux policy after commit.
@ -50,20 +49,20 @@ options:
default: true
ignore_selinux_state:
description:
- Run independent of selinux runtime state
- Run independent of selinux runtime state.
type: bool
default: false
notes:
- The changes are persistent across reboots
- Not tested on any debian based system
requirements: [ 'libselinux', 'policycoreutils' ]
- The changes are persistent across reboots.
- Not tested on any debian based system.
requirements: ['libselinux', 'policycoreutils']
author:
- Dan Keder (@dankeder)
- Petr Lautrbach (@bachradsusi)
- James Cassell (@jamescassell)
'''
- Dan Keder (@dankeder)
- Petr Lautrbach (@bachradsusi)
- James Cassell (@jamescassell)
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Modify the default user on the system to the guest_u user
community.general.selogin:
login: __default__
@ -82,11 +81,11 @@ EXAMPLES = '''
login: '%engineering'
seuser: staff_u
state: present
'''
"""
RETURN = r'''
RETURN = r"""
# Default return values
'''
"""
import traceback

38
plugins/modules/sendgrid.py
View File

@ -9,21 +9,15 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: sendgrid
short_description: Sends an email with the SendGrid API
description:
- "Sends an email with a SendGrid account through their API, not through
the SMTP service."
- Sends an email with a SendGrid account through their API, not through the SMTP service.
notes:
- "This module is non-idempotent because it sends an email through the
external API. It is idempotent only in the case that the module fails."
- "Like the other notification modules, this one requires an external
dependency to work. In this case, you'll need an active SendGrid
account."
- "In order to use api_key, cc, bcc, attachments, from_name, html_body, headers
you must pip install sendgrid"
- This module is non-idempotent because it sends an email through the external API. It is idempotent only in the case that the module fails.
- Like the other notification modules, this one requires an external dependency to work. In this case, you will need an active SendGrid account.
- In order to use O(api_key), O(cc), O(bcc), O(attachments), O(from_name), O(html_body), and O(headers) you must C(pip install sendgrid).
requirements:
- sendgrid Python library 1.6.22 or lower (Sendgrid API V2 supported)
extends_documentation_fragment:
@ -98,9 +92,9 @@ options:
- The e-mail body content.
required: true
author: "Matt Makai (@makaimc)"
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Send an email to a single recipient that the deployment was successful
community.general.sendgrid:
username: "{{ sendgrid_username }}"
@ -114,16 +108,16 @@ EXAMPLES = r'''
- name: Send an email to more than one recipient that the build failed
community.general.sendgrid:
username: "{{ sendgrid_username }}"
password: "{{ sendgrid_password }}"
from_address: "build@mycompany.com"
to_addresses:
- "ops@mycompany.com"
- "devteam@mycompany.com"
subject: "Build failure!."
body: "Unable to pull source repository from Git server."
username: "{{ sendgrid_username }}"
password: "{{ sendgrid_password }}"
from_address: "build@mycompany.com"
to_addresses:
- "ops@mycompany.com"
- "devteam@mycompany.com"
subject: "Build failure!."
body: "Unable to pull source repository from Git server."
delegate_to: localhost
'''
"""
# =======================================
# sendgrid module support methods

65
plugins/modules/sensu_check.py
View File

@ -9,15 +9,14 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: sensu_check
short_description: Manage Sensu checks
description:
- Manage the checks that should be run on a machine by I(Sensu).
- Most options do not have a default and will not be added to the check definition unless specified.
- All defaults except O(path), O(state), O(backup) and O(metric) are not managed by this module,
- they are simply specified for your convenience.
they are simply specified for your convenience.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -29,127 +28,127 @@ options:
name:
type: str
description:
- The name of the check
- This is the key that is used to determine whether a check exists
- The name of the check.
- This is the key that is used to determine whether a check exists.
required: true
state:
type: str
description:
- Whether the check should be present or not
choices: [ 'present', 'absent' ]
- Whether the check should be present or not.
choices: ['present', 'absent']
default: present
path:
type: str
description:
- Path to the json file of the check to be added/removed.
- Will be created if it does not exist (unless O(state=absent)).
- The parent folders need to exist when O(state=present), otherwise an error will be thrown
- The parent folders need to exist when O(state=present), otherwise an error will be thrown.
default: /etc/sensu/conf.d/checks.json
backup:
description:
- Create a backup file (if yes), including the timestamp information so
- you can get the original file back if you somehow clobbered it incorrectly.
you can get the original file back if you somehow clobbered it incorrectly.
type: bool
default: false
command:
type: str
description:
- Path to the sensu check to run (not required when O(state=absent))
- Path to the sensu check to run (not required when O(state=absent)).
handlers:
type: list
elements: str
description:
- List of handlers to notify when the check fails
- List of handlers to notify when the check fails.
subscribers:
type: list
elements: str
description:
- List of subscribers/channels this check should run for
- See sensu_subscribers to subscribe a machine to a channel
- List of subscribers/channels this check should run for.
- See sensu_subscribers to subscribe a machine to a channel.
interval:
type: int
description:
- Check interval in seconds
- Check interval in seconds.
timeout:
type: int
description:
- Timeout for the check
- Timeout for the check.
- If not specified, it defaults to 10.
ttl:
type: int
description:
- Time to live in seconds until the check is considered stale
- Time to live in seconds until the check is considered stale.
handle:
description:
- Whether the check should be handled or not
- Whether the check should be handled or not.
- Default is V(false).
type: bool
subdue_begin:
type: str
description:
- When to disable handling of check failures
- When to disable handling of check failures.
subdue_end:
type: str
description:
- When to enable handling of check failures
- When to enable handling of check failures.
dependencies:
type: list
elements: str
description:
- Other checks this check depends on, if dependencies fail handling of this check will be disabled
- Other checks this check depends on, if dependencies fail handling of this check will be disabled.
metric:
description:
- Whether the check is a metric
- Whether the check is a metric.
type: bool
default: false
standalone:
description:
- Whether the check should be scheduled by the sensu client or server
- This option obviates the need for specifying the O(subscribers) option
- Whether the check should be scheduled by the sensu client or server.
- This option obviates the need for specifying the O(subscribers) option.
- Default is V(false).
type: bool
publish:
description:
- Whether the check should be scheduled at all.
- You can still issue it via the sensu api
- You can still issue it via the sensu API.
- Default is V(false).
type: bool
occurrences:
type: int
description:
- Number of event occurrences before the handler should take action
- Number of event occurrences before the handler should take action.
- If not specified, defaults to 1.
refresh:
type: int
description:
- Number of seconds handlers should wait before taking second action
- Number of seconds handlers should wait before taking second action.
aggregate:
description:
- Classifies the check as an aggregate check,
- making it available via the aggregate API
making it available via the aggregate API.
- Default is V(false).
type: bool
low_flap_threshold:
type: int
description:
- The low threshold for flap detection
- The low threshold for flap detection.
high_flap_threshold:
type: int
description:
- The high threshold for flap detection
- The high threshold for flap detection.
custom:
type: dict
description:
- A hash/dictionary of custom parameters for mixing to the configuration.
- You can't rewrite others module parameters using this
- You can't rewrite others module parameters using this.
source:
type: str
description:
- The check source, used to create a JIT Sensu client for an external resource (e.g. a network switch).
author: "Anders Ingemann (@andsens)"
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
# Fetch metrics about the CPU load every 60 seconds,
# the sensu server has a handler called 'relay' which forwards stats to graphite
- name: Get cpu metrics
@ -177,7 +176,7 @@ EXAMPLES = '''
community.general.sensu_check:
name: check_disk_capacity
state: absent
'''
"""
import json
import traceback

26
plugins/modules/sensu_client.py
View File

@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: sensu_client
author: "David Moreau Simard (@dmsimard)"
short_description: Manages Sensu client configuration
@ -27,8 +26,8 @@ options:
state:
type: str
description:
- Whether the client should be present or not
choices: [ 'present', 'absent' ]
- Whether the client should be present or not.
choices: ['present', 'absent']
default: present
name:
type: str
@ -49,7 +48,8 @@ options:
- The subscriptions array items must be strings.
safe_mode:
description:
- If safe mode is enabled for the client. Safe mode requires local check definitions in order to accept a check request and execute the check.
- If safe mode is enabled for the client. Safe mode requires local check definitions in order to accept a check request and execute the
check.
type: bool
default: false
redact:
@ -99,11 +99,9 @@ options:
type: dict
description:
- The servicenow definition scope, used to configure the Sensu Enterprise ServiceNow integration (Sensu Enterprise users only).
notes:
- Check mode is supported
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
# Minimum possible configuration
- name: Configure Sensu client
community.general.sensu_client:
@ -146,20 +144,20 @@ EXAMPLES = '''
- name: Delete the Sensu client configuration
community.general.sensu_client:
state: "absent"
'''
"""
RETURN = '''
RETURN = r"""
config:
description: Effective client configuration, when state is present
description: Effective client configuration, when state is present.
returned: success
type: dict
sample: {'name': 'client', 'subscriptions': ['default']}
file:
description: Path to the client configuration file
description: Path to the client configuration file.
returned: success
type: str
sample: "/etc/sensu/conf.d/client.json"
'''
"""
import json
import os

33
plugins/modules/sensu_handler.py
View File

@ -8,13 +8,12 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: sensu_handler
author: "David Moreau Simard (@dmsimard)"
short_description: Manages Sensu handler configuration
description:
- Manages Sensu handler configuration
- Manages Sensu handler configuration.
- 'For more information, refer to the Sensu documentation: U(https://sensuapp.org/docs/latest/reference/handlers.html)'
extends_documentation_fragment:
- community.general.attributes
@ -27,8 +26,8 @@ options:
state:
type: str
description:
- Whether the handler should be present or not
choices: [ 'present', 'absent' ]
- Whether the handler should be present or not.
choices: ['present', 'absent']
default: present
name:
type: str
@ -38,8 +37,8 @@ options:
type:
type: str
description:
- The handler type
choices: [ 'pipe', 'tcp', 'udp', 'transport', 'set' ]
- The handler type.
choices: ['pipe', 'tcp', 'udp', 'transport', 'set']
filter:
type: str
description:
@ -98,12 +97,10 @@ options:
elements: str
description:
- An array of Sensu event handlers (names) to use for events using the handler set.
- 'NOTE: the handlers attribute is only required for handler sets (i.e. handlers configured with "type": "set").'
notes:
- Check mode is supported
'''
- 'NOTE: the handlers attribute is only required for handler sets (that is, handlers configured with O(type=set)).'
"""
EXAMPLES = '''
EXAMPLES = r"""
# Configure a handler that sends event data as STDIN (pipe)
- name: Configure IRC Sensu handler
community.general.sensu_handler:
@ -146,25 +143,25 @@ EXAMPLES = '''
owner: "sensu"
group: "sensu"
mode: "0600"
'''
"""
RETURN = '''
RETURN = r"""
config:
description: Effective handler configuration, when state is present
description: Effective handler configuration, when state is present.
returned: success
type: dict
sample: {'name': 'irc', 'type': 'pipe', 'command': '/usr/local/bin/notify-irc.sh'}
file:
description: Path to the handler configuration file
description: Path to the handler configuration file.
returned: success
type: str
sample: "/etc/sensu/conf.d/handlers/irc.json"
name:
description: Name of the handler
description: Name of the handler.
returned: success
type: str
sample: "irc"
'''
"""
import json
import os

30
plugins/modules/sensu_silence.py
View File

@ -9,14 +9,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: sensu_silence
author: Steven Bambling (@smbambling)
short_description: Manage Sensu silence entries
description:
- Create and clear (delete) a silence entries via the Sensu API
for subscriptions and checks.
- Create and clear (delete) a silence entries via the Sensu API for subscriptions and checks.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -36,30 +34,26 @@ options:
expire:
type: int
description:
- If specified, the silence entry will be automatically cleared
after this number of seconds.
- If specified, the silence entry will be automatically cleared after this number of seconds.
expire_on_resolve:
description:
- If specified as true, the silence entry will be automatically
cleared once the condition it is silencing is resolved.
- If specified as true, the silence entry will be automatically cleared once the condition it is silencing is resolved.
type: bool
reason:
type: str
description:
- If specified, this free-form string is used to provide context or
rationale for the reason this silence entry was created.
- If specified, this free-form string is used to provide context or rationale for the reason this silence entry was created.
state:
type: str
description:
- Specifies to create or clear (delete) a silence entry via the Sensu API
- Specifies to create or clear (delete) a silence entry via the Sensu API.
default: present
choices: ['present', 'absent']
subscription:
type: str
description:
- Specifies the subscription which the silence entry applies to.
- To create a silence entry for a client prepend C(client:) to client name.
Example - C(client:server1.example.dev)
- To create a silence entry for a client prepend C(client:) to client name. Example - C(client:server1.example.dev).
required: true
url:
type: str
@ -67,9 +61,9 @@ options:
- Specifies the URL of the Sensu monitoring host server.
required: false
default: http://127.0.01:4567
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
# Silence ALL checks for a given client
- name: Silence server1.example.dev
community.general.sensu_silence:
@ -98,10 +92,10 @@ EXAMPLES = '''
reason: "{{ item.value.reason }}"
creator: "{{ ansible_user_id }}"
with_dict: "{{ silence }}"
'''
"""
RETURN = '''
'''
RETURN = r"""
"""
import json

35
plugins/modules/sensu_subscription.py
View File

@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: sensu_subscription
short_description: Manage Sensu subscriptions
description:
- Manage which I(sensu channels) a machine should subscribe to
- Manage which I(sensu channels) a machine should subscribe to.
extends_documentation_fragment:
- community.general.attributes
attributes:
@ -26,41 +25,41 @@ options:
name:
type: str
description:
- The name of the channel
- The name of the channel.
required: true
state:
type: str
description:
- Whether the machine should subscribe or unsubscribe from the channel
choices: [ 'present', 'absent' ]
- Whether the machine should subscribe or unsubscribe from the channel.
choices: ['present', 'absent']
required: false
default: present
path:
type: str
description:
- Path to the subscriptions json file
- Path to the subscriptions json file.
required: false
default: /etc/sensu/conf.d/subscriptions.json
backup:
description:
- Create a backup file (if yes), including the timestamp information so you
- can get the original file back if you somehow clobbered it incorrectly.
can get the original file back if you somehow clobbered it incorrectly.
type: bool
required: false
default: false
requirements: [ ]
requirements: []
author: Anders Ingemann (@andsens)
'''
"""
RETURN = '''
RETURN = r"""
reasons:
description: the reasons why the module changed or did not change something
returned: success
type: list
sample: ["channel subscription was absent and state is `present'"]
'''
description: The reasons why the module changed or did not change something.
returned: success
type: list
sample: ["channel subscription was absent and state is `present'"]
"""
EXAMPLES = '''
EXAMPLES = r"""
# Subscribe to the nginx channel
- name: Subscribe to nginx checks
community.general.sensu_subscription: name=nginx
@ -68,7 +67,7 @@ EXAMPLES = '''
# Unsubscribe from the common checks channel
- name: Unsubscribe from common checks
community.general.sensu_subscription: name=common state=absent
'''
"""
import json
import traceback

31
plugins/modules/seport.py
View File

@ -8,14 +8,13 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: seport
short_description: Manages SELinux network port type definitions
description:
- Manages SELinux network port type definitions.
- Manages SELinux network port type definitions.
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes
attributes:
check_mode:
support: full
@ -34,7 +33,7 @@ options:
- Protocol for the specified port.
type: str
required: true
choices: [ tcp, udp ]
choices: [tcp, udp]
setype:
description:
- SELinux type for the specified port.
@ -44,7 +43,7 @@ options:
description:
- Desired boolean value.
type: str
choices: [ absent, present ]
choices: [absent, present]
default: present
reload:
description:
@ -53,26 +52,26 @@ options:
default: true
ignore_selinux_state:
description:
- Run independent of selinux runtime state
- Run independent of selinux runtime state.
type: bool
default: false
local:
description:
- Work with local modifications only.
- Work with local modifications only.
type: bool
default: false
version_added: 5.6.0
notes:
- The changes are persistent across reboots.
- Not tested on any debian based system.
- The changes are persistent across reboots.
- Not tested on any Debian based system.
requirements:
- libselinux-python
- policycoreutils-python
- libselinux-python
- policycoreutils-python
author:
- Dan Keder (@dankeder)
'''
- Dan Keder (@dankeder)
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Allow Apache to listen on tcp port 8888
community.general.seport:
ports: 8888
@ -110,7 +109,7 @@ EXAMPLES = r'''
setype: ssh_port_t
state: absent
local: true
'''
"""
import traceback

26
plugins/modules/serverless.py
View File

@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: serverless
short_description: Manages a Serverless Framework project
description:
@ -26,11 +25,11 @@ options:
description:
- Goal state of given stage/project.
type: str
choices: [ absent, present ]
choices: [absent, present]
default: present
serverless_bin_path:
description:
- The path of a serverless framework binary relative to the 'service_path' eg. node_module/.bin/serverless
- The path of a serverless framework binary relative to the O(service_path), for example V(node_module/.bin/serverless).
type: path
service_path:
description:
@ -67,16 +66,15 @@ options:
type: bool
default: false
notes:
- Currently, the C(serverless) command must be in the path of the node executing the task.
In the future this may be a flag.
- Currently, the C(serverless) command must be in the path of the node executing the task. In the future this may be a flag.
requirements:
- serverless
- yaml
- serverless
- PyYAML
author:
- Ryan Scott Brown (@ryansb)
'''
- Ryan Scott Brown (@ryansb)
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Basic deploy of a service
community.general.serverless:
service_path: '{{ project_dir }}'
@ -103,9 +101,9 @@ EXAMPLES = r'''
region: us-east-1
service_path: '{{ project_dir }}'
serverless_bin_path: node_modules/.bin/serverless
'''
"""
RETURN = r'''
RETURN = r"""
service_name:
type: str
description: The service name specified in the serverless.yml that was just deployed.
@ -120,7 +118,7 @@ command:
description: Full C(serverless) command run by this module, in case you want to re-run the command outside the module.
returned: always
sample: serverless deploy --stage production
'''
"""
import os

33
plugins/modules/shutdown.py
View File

@ -8,14 +8,14 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = r'''
DOCUMENTATION = r"""
module: shutdown
short_description: Shut down a machine
notes:
- E(PATH) is ignored on the remote node when searching for the C(shutdown) command. Use O(search_paths)
to specify locations to search if the default paths do not work.
- The O(msg) and O(delay) options are not supported when a shutdown command is not found in O(search_paths), instead
the module will attempt to shutdown the system by calling C(systemctl shutdown).
- E(PATH) is ignored on the remote node when searching for the C(shutdown) command. Use O(search_paths) to specify locations to search if the
default paths do not work.
- The O(msg) and O(delay) options are not supported when a shutdown command is not found in O(search_paths), instead the module will attempt
to shutdown the system by calling C(systemctl shutdown).
description:
- Shut downs a machine.
version_added: "1.1.0"
@ -47,20 +47,21 @@ options:
search_paths:
description:
- Paths to search on the remote machine for the C(shutdown) command.
- I(Only) these paths will be searched for the C(shutdown) command. E(PATH) is ignored in the remote node when searching for the C(shutdown) command.
- I(Only) these paths will be searched for the C(shutdown) command. E(PATH) is ignored in the remote node when searching for the C(shutdown)
command.
type: list
elements: path
default: ['/sbin', '/usr/sbin', '/usr/local/sbin']
seealso:
- module: ansible.builtin.reboot
- module: ansible.builtin.reboot
author:
- Matt Davis (@nitzmahone)
- Sam Doran (@samdoran)
- Amin Vakil (@aminvakil)
'''
- Matt Davis (@nitzmahone)
- Sam Doran (@samdoran)
- Amin Vakil (@aminvakil)
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Unconditionally shut down the machine with all defaults
community.general.shutdown:
@ -71,13 +72,13 @@ EXAMPLES = r'''
- name: Shut down a machine with shutdown command in unusual place
community.general.shutdown:
search_paths:
- '/lib/molly-guard'
'''
- '/lib/molly-guard'
"""
RETURN = r'''
RETURN = r"""
shutdown:
description: V(true) if the machine has been shut down.
returned: always
type: bool
sample: true
'''
"""

20
plugins/modules/simpleinit_msb.py
View File

@ -11,8 +11,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: simpleinit_msb
short_description: Manage services on Source Mage GNU/Linux
version_added: 7.5.0
@ -38,24 +37,21 @@ options:
state:
type: str
required: false
choices: [ running, started, stopped, restarted, reloaded ]
choices: [running, started, stopped, restarted, reloaded]
description:
- V(started)/V(stopped) are idempotent actions that will not run
commands unless necessary. V(restarted) will always bounce the
service. V(reloaded) will always reload.
- V(started)/V(stopped) are idempotent actions that will not run commands unless necessary. V(restarted) will always bounce the service.
V(reloaded) will always reload.
- At least one of O(state) and O(enabled) are required.
- Note that V(reloaded) will start the
service if it is not already started, even if your chosen init
system would not normally.
- Note that V(reloaded) will start the service if it is not already started, even if your chosen init system would not normally.
enabled:
type: bool
required: false
description:
- Whether the service should start on boot.
- At least one of O(state) and O(enabled) are required.
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Example action to start service httpd, if not running
community.general.simpleinit_msb:
name: httpd
@ -80,7 +76,7 @@ EXAMPLES = '''
community.general.simpleinit_msb:
name: httpd
enabled: true
'''
"""
import os
import re

163
plugins/modules/sl_vm.py
View File

@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: sl_vm
short_description: Create or cancel a virtual instance in SoftLayer
description:
@ -121,7 +120,7 @@ options:
disks:
description:
- List of disk sizes to be assigned to new virtual instance.
default: [ 25 ]
default: [25]
type: list
elements: int
os_code:
@ -159,7 +158,7 @@ options:
description:
- Create, or cancel a virtual instance.
- Specify V(present) for create, V(absent) to cancel.
choices: [ absent, present ]
choices: [absent, present]
default: present
type: str
wait:
@ -173,102 +172,102 @@ options:
default: 600
type: int
requirements:
- softlayer >= 4.1.1
- softlayer >= 4.1.1
author:
- Matt Colton (@mcltn)
'''
- Matt Colton (@mcltn)
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Build instance
hosts: localhost
gather_facts: false
tasks:
- name: Build instance request
community.general.sl_vm:
hostname: instance-1
domain: anydomain.com
datacenter: dal09
tags: ansible-module-test
hourly: true
private: false
dedicated: false
local_disk: true
cpus: 1
memory: 1024
disks: [25]
os_code: UBUNTU_LATEST
wait: false
- name: Build instance request
community.general.sl_vm:
hostname: instance-1
domain: anydomain.com
datacenter: dal09
tags: ansible-module-test
hourly: true
private: false
dedicated: false
local_disk: true
cpus: 1
memory: 1024
disks: [25]
os_code: UBUNTU_LATEST
wait: false
- name: Build additional instances
hosts: localhost
gather_facts: false
tasks:
- name: Build instances request
community.general.sl_vm:
hostname: "{{ item.hostname }}"
domain: "{{ item.domain }}"
datacenter: "{{ item.datacenter }}"
tags: "{{ item.tags }}"
hourly: "{{ item.hourly }}"
private: "{{ item.private }}"
dedicated: "{{ item.dedicated }}"
local_disk: "{{ item.local_disk }}"
cpus: "{{ item.cpus }}"
memory: "{{ item.memory }}"
disks: "{{ item.disks }}"
os_code: "{{ item.os_code }}"
ssh_keys: "{{ item.ssh_keys }}"
wait: "{{ item.wait }}"
with_items:
- hostname: instance-2
domain: anydomain.com
datacenter: dal09
tags:
- ansible-module-test
- ansible-module-test-replicas
hourly: true
private: false
dedicated: false
local_disk: true
cpus: 1
memory: 1024
disks:
- 25
- 100
os_code: UBUNTU_LATEST
ssh_keys: []
wait: true
- hostname: instance-3
domain: anydomain.com
datacenter: dal09
tags:
- ansible-module-test
- ansible-module-test-replicas
hourly: true
private: false
dedicated: false
local_disk: true
cpus: 1
memory: 1024
disks:
- 25
- 100
os_code: UBUNTU_LATEST
ssh_keys: []
wait: true
- name: Build instances request
community.general.sl_vm:
hostname: "{{ item.hostname }}"
domain: "{{ item.domain }}"
datacenter: "{{ item.datacenter }}"
tags: "{{ item.tags }}"
hourly: "{{ item.hourly }}"
private: "{{ item.private }}"
dedicated: "{{ item.dedicated }}"
local_disk: "{{ item.local_disk }}"
cpus: "{{ item.cpus }}"
memory: "{{ item.memory }}"
disks: "{{ item.disks }}"
os_code: "{{ item.os_code }}"
ssh_keys: "{{ item.ssh_keys }}"
wait: "{{ item.wait }}"
with_items:
- hostname: instance-2
domain: anydomain.com
datacenter: dal09
tags:
- ansible-module-test
- ansible-module-test-replicas
hourly: true
private: false
dedicated: false
local_disk: true
cpus: 1
memory: 1024
disks:
- 25
- 100
os_code: UBUNTU_LATEST
ssh_keys: []
wait: true
- hostname: instance-3
domain: anydomain.com
datacenter: dal09
tags:
- ansible-module-test
- ansible-module-test-replicas
hourly: true
private: false
dedicated: false
local_disk: true
cpus: 1
memory: 1024
disks:
- 25
- 100
os_code: UBUNTU_LATEST
ssh_keys: []
wait: true
- name: Cancel instances
hosts: localhost
gather_facts: false
tasks:
- name: Cancel by tag
community.general.sl_vm:
state: absent
tags: ansible-module-test
'''
- name: Cancel by tag
community.general.sl_vm:
state: absent
tags: ansible-module-test
"""
# TODO: Disabled RETURN as it is breaking the build for docs. Needs to be fixed.
RETURN = '''# '''
RETURN = """# """
import json
import time

83
plugins/modules/slack.py
View File

@ -15,11 +15,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = """
DOCUMENTATION = r"""
module: slack
short_description: Send Slack notifications
description:
- The M(community.general.slack) module sends notifications to U(http://slack.com) via the Incoming WebHook integration
- The M(community.general.slack) module sends notifications to U(http://slack.com) via the Incoming WebHook integration.
author: "Ramon de la Fuente (@ramondelafuente)"
extends_documentation_fragment:
- community.general.attributes
@ -32,51 +32,42 @@ options:
domain:
type: str
description:
- Slack (sub)domain for your environment without protocol. (For example
V(example.slack.com).) In Ansible 1.8 and beyond, this is deprecated and may
be ignored. See token documentation for information.
- Slack (sub)domain for your environment without protocol. (For example V(example.slack.com).) In Ansible 1.8 and beyond, this is deprecated
and may be ignored. See token documentation for information.
token:
type: str
description:
- Slack integration token. This authenticates you to the slack service.
Make sure to use the correct type of token, depending on what method you use.
- "Webhook token:
Prior to Ansible 1.8, a token looked like V(3Ffe373sfhRE6y42Fg3rvf4GlK). In
Ansible 1.8 and above, Ansible adapts to the new slack API where tokens look
like V(G922VJP24/D921DW937/3Ffe373sfhRE6y42Fg3rvf4GlK). If tokens
are in the new format then slack will ignore any value of domain. If
the token is in the old format the domain is required. Ansible has no
control of when slack will get rid of the old API. When slack does
that the old format will stop working. ** Please keep in mind the tokens
are not the API tokens but are the webhook tokens. In slack these are
found in the webhook URL which are obtained under the apps and integrations.
The incoming webhooks can be added in that area. In some cases this may
be locked by your Slack admin and you must request access. It is there
that the incoming webhooks can be added. The key is on the end of the
URL given to you in that section."
- "WebAPI token:
Slack WebAPI requires a personal, bot or work application token. These tokens start with V(xoxp-), V(xoxb-)
or V(xoxa-), for example V(xoxb-1234-56789abcdefghijklmnop). WebAPI token is required if you intend to receive thread_id.
See Slack's documentation (U(https://api.slack.com/docs/token-types)) for more information."
- Slack integration token. This authenticates you to the slack service. Make sure to use the correct type of token, depending on what method
you use.
- 'Webhook token: Prior to Ansible 1.8, a token looked like V(3Ffe373sfhRE6y42Fg3rvf4GlK). In Ansible 1.8 and above, Ansible adapts to the
new slack API where tokens look like V(G922VJP24/D921DW937/3Ffe373sfhRE6y42Fg3rvf4GlK). If tokens are in the new format then slack will
ignore any value of domain. If the token is in the old format the domain is required. Ansible has no control of when slack will get rid
of the old API. When slack does that the old format will stop working. ** Please keep in mind the tokens are not the API tokens but are
the webhook tokens. In slack these are found in the webhook URL which are obtained under the apps and integrations. The incoming webhooks
can be added in that area. In some cases this may be locked by your Slack admin and you must request access. It is there that the incoming
webhooks can be added. The key is on the end of the URL given to you in that section.'
- "WebAPI token: Slack WebAPI requires a personal, bot or work application token. These tokens start with V(xoxp-), V(xoxb-) or V(xoxa-),
for example V(xoxb-1234-56789abcdefghijklmnop). WebAPI token is required if you intend to receive thread_id. See Slack's documentation
(U(https://api.slack.com/docs/token-types)) for more information."
required: true
msg:
type: str
description:
- Message to send. Note that the module does not handle escaping characters.
Plain-text angle brackets and ampersands should be converted to HTML entities (e.g. & to &amp;) before sending.
See Slack's documentation (U(https://api.slack.com/docs/message-formatting)) for more.
- Message to send. Note that the module does not handle escaping characters. Plain-text angle brackets and ampersands should be converted
to HTML entities (for example C(&) to C(&amp;)) before sending. See Slack's documentation (U(https://api.slack.com/docs/message-formatting)) for more.
channel:
type: str
description:
- Channel to send the message to. If absent, the message goes to the channel selected for the O(token).
thread_id:
description:
- Optional. Timestamp of parent message to thread this message. https://api.slack.com/docs/message-threading
- Optional. Timestamp of parent message to thread this message, see U(https://api.slack.com/docs/message-threading).
type: str
message_id:
description:
- Optional. Message ID to edit, instead of posting a new message.
- If supplied O(channel) must be in form of C(C0xxxxxxx). use C({{ slack_response.channel }}) to get RV(ignore:channel) from previous task run.
- If supplied O(channel) must be in form of C(C0xxxxxxx). use C({{ slack_response.channel }}) to get RV(ignore:channel) from previous task
run.
- The token needs history scope to get information on the message to edit (C(channels:history,groups:history,mpim:history,im:history)).
- Corresponds to C(ts) in the Slack API (U(https://api.slack.com/messaging/modifying)).
type: str
@ -107,14 +98,13 @@ options:
parse:
type: str
description:
- Setting for the message parser at Slack
- Setting for the message parser at Slack.
choices:
- 'full'
- 'none'
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
color:
@ -140,11 +130,10 @@ options:
type: str
description:
- Setting for automatically prepending a V(#) symbol on the passed in O(channel).
- The V(auto) method prepends a V(#) unless O(channel) starts with one of V(#), V(@), V(C0), V(GF), V(G0), V(CP).
These prefixes only cover a small set of the prefixes that should not have a V(#) prepended.
Since an exact condition which O(channel) values must not have the V(#) prefix is not known,
the value V(auto) for this option will be deprecated in the future. It is best to explicitly set
O(prepend_hash=always) or O(prepend_hash=never) to obtain the needed behavior.
- The V(auto) method prepends a V(#) unless O(channel) starts with one of V(#), V(@), V(C0), V(GF), V(G0), V(CP). These prefixes only cover
a small set of the prefixes that should not have a V(#) prepended. Since an exact condition which O(channel) values must not have the
V(#) prefix is not known, the value V(auto) for this option will be deprecated in the future. It is best to explicitly set O(prepend_hash=always)
or O(prepend_hash=never) to obtain the needed behavior.
choices:
- 'always'
- 'never'
@ -153,7 +142,7 @@ options:
version_added: 6.1.0
"""
EXAMPLES = """
EXAMPLES = r"""
- name: Send notification message via Slack
community.general.slack:
token: thetoken/generatedby/slack
@ -215,14 +204,14 @@ EXAMPLES = """
Display my system load on host A and B
- type: context
elements:
- type: mrkdwn
text: |-
*System A*
load average: 0,74, 0,66, 0,63
- type: mrkdwn
text: |-
*System B*
load average: 5,16, 4,64, 2,43
- type: mrkdwn
text: |-
*System A*
load average: 0,74, 0,66, 0,63
- type: mrkdwn
text: |-
*System B*
load average: 5,16, 4,64, 2,43
- name: Send a message with a link using Slack markup
community.general.slack:

64
plugins/modules/slackpkg.py
View File

@ -15,49 +15,47 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: slackpkg
short_description: Package manager for Slackware >= 12.2
description:
- Manage binary packages for Slackware using 'slackpkg' which
is available in versions after 12.2.
- Manage binary packages for Slackware using C(slackpkg) which is available in versions after 12.2.
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes
attributes:
check_mode:
support: full
diff_mode:
support: none
check_mode:
support: full
diff_mode:
support: none
options:
name:
description:
- name of package to install/remove
required: true
type: list
elements: str
aliases: [pkg]
name:
description:
- Name of package to install/remove.
required: true
type: list
elements: str
aliases: [pkg]
state:
description:
- State of the package, you can use V(installed) as an alias for V(present) and V(removed) as one for V(absent).
choices: [ 'present', 'absent', 'latest', 'installed', 'removed' ]
required: false
default: present
type: str
state:
description:
- State of the package, you can use V(installed) as an alias for V(present) and V(removed) as one for V(absent).
choices: ['present', 'absent', 'latest', 'installed', 'removed']
required: false
default: present
type: str
update_cache:
description:
- update the package database first
required: false
default: false
type: bool
update_cache:
description:
- Update the package database first.
required: false
default: false
type: bool
author: Kim Nørgaard (@KimNorgaard)
requirements: [ "Slackware >= 12.2" ]
'''
requirements: ["Slackware >= 12.2"]
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Install package foo
community.general.slackpkg:
name: foo
@ -72,7 +70,7 @@ EXAMPLES = '''
community.general.slackpkg:
name: foo
state: latest
'''
"""
from ansible.module_utils.basic import AnsibleModule

43
plugins/modules/smartos_image_info.py
View File

@ -9,31 +9,28 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: smartos_image_info
short_description: Get SmartOS image details
description:
- Retrieve information about all installed images on SmartOS.
- Retrieve information about all installed images on SmartOS.
author: Adam Števko (@xen0l)
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes.info_module
- community.general.attributes
- community.general.attributes.info_module
attributes:
check_mode:
version_added: 3.3.0
# This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
check_mode:
version_added: 3.3.0
# This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
options:
filters:
description:
- Criteria for selecting image. Can be any value from image
manifest and C(published_date), C(published), C(source), C(clones),
and C(size). More information can be found at U(https://smartos.org/man/1m/imgadm)
under C(imgadm list).
type: str
'''
filters:
description:
- Criteria for selecting image. Can be any value from image manifest and V(published_date), V(published), V(source), V(clones), and V(size).
- More information can be found at U(https://smartos.org/man/1m/imgadm) under C(imgadm list).
type: str
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Return information about all installed images
community.general.smartos_image_info:
register: result
@ -49,19 +46,17 @@ EXAMPLES = '''
- name: Print information
ansible.builtin.debug:
msg: "{{ result.smartos_images[item]['name'] }}-{{ result.smartos_images[item]['version'] }}
has {{ result.smartos_images[item]['clones'] }} VM(s)"
msg: "{{ result.smartos_images[item]['name'] }}-{{ result.smartos_images[item]['version'] }} has {{ result.smartos_images[item]['clones'] }} VM(s)"
with_items: "{{ result.smartos_images.keys() | list }}"
- name: Print information
ansible.builtin.debug:
msg: "{{ smartos_images[item]['name'] }}-{{ smartos_images[item]['version'] }}
has {{ smartos_images[item]['clones'] }} VM(s)"
msg: "{{ smartos_images[item]['name'] }}-{{ smartos_images[item]['version'] }} has {{ smartos_images[item]['clones'] }} VM(s)"
with_items: "{{ smartos_images.keys() | list }}"
'''
"""
RETURN = '''
'''
RETURN = r"""
"""
import json
from ansible.module_utils.basic import AnsibleModule

193
plugins/modules/snap.py
View File

@ -13,96 +13,87 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: snap
short_description: Manages snaps
description:
- Manages snaps packages.
- Manages snaps packages.
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes
attributes:
check_mode:
support: full
diff_mode:
support: none
check_mode:
support: full
diff_mode:
support: none
options:
name:
description:
- Name of the snaps to be installed.
- Any named snap accepted by the C(snap) command is valid.
- >
O(dangerous=true) may be necessary when installing `.snap` files. See O(dangerous) for more details.
required: true
type: list
elements: str
state:
description:
- Desired state of the package.
- >
When O(state=present) the module will use C(snap install) if the snap is not installed,
and C(snap refresh) if it is installed but from a different channel.
default: present
choices: [ absent, present, enabled, disabled ]
type: str
classic:
description:
- Install a snap that has classic confinement.
- This option corresponds to the C(--classic) argument of the C(snap install) command.
- This level of confinement is permissive, granting full system access,
similar to that of traditionally packaged applications that do not use sandboxing mechanisms.
This option can only be specified when the task involves a single snap.
- See U(https://snapcraft.io/docs/snap-confinement) for more details about classic confinement and confinement levels.
type: bool
required: false
default: false
channel:
description:
- Define which release of a snap is installed and tracked for updates.
This option can only be specified if there is a single snap in the task.
- If not passed, the C(snap) command will default to V(stable).
- If the value passed does not contain the C(track), it will default to C(latest).
For example, if V(edge) is passed, the module will assume the channel to be V(latest/edge).
- See U(https://snapcraft.io/docs/channels) for more details about snap channels.
type: str
required: false
options:
description:
- Set options with pattern C(key=value) or C(snap:key=value). If a snap name is given, the option will be applied
to that snap only. If the snap name is omitted, the options will be applied to all snaps listed in O(name). Options will
only be applied to active snaps.
- Options will only be applied when C(state) is set to V(present).
This is done after the necessary installation
or refresh (upgrade/downgrade) of all the snaps listed in O(name).
- See U(https://snapcraft.io/docs/configuration-in-snaps) for more details about snap configuration options.
required: false
type: list
elements: str
version_added: 4.4.0
dangerous:
description:
- Install the snap in dangerous mode, without validating its assertions and signatures.
- This is useful when installing local snaps that are either unsigned or have signatures that have not been acknowledged.
- See U(https://snapcraft.io/docs/install-modes) for more details about installation modes.
type: bool
required: false
default: false
version_added: 7.2.0
name:
description:
- Name of the snaps to be installed.
- Any named snap accepted by the C(snap) command is valid.
- O(dangerous=true) may be necessary when installing C(.snap) files. See O(dangerous) for more details.
required: true
type: list
elements: str
state:
description:
- Desired state of the package.
- When O(state=present) the module will use C(snap install) if the snap is not installed, and C(snap refresh) if it is installed but from
a different channel.
default: present
choices: [absent, present, enabled, disabled]
type: str
classic:
description:
- Install a snap that has classic confinement.
- This option corresponds to the C(--classic) argument of the C(snap install) command.
- This level of confinement is permissive, granting full system access, similar to that of traditionally packaged applications that do not
use sandboxing mechanisms. This option can only be specified when the task involves a single snap.
- See U(https://snapcraft.io/docs/snap-confinement) for more details about classic confinement and confinement levels.
type: bool
required: false
default: false
channel:
description:
- Define which release of a snap is installed and tracked for updates. This option can only be specified if there is a single snap in the
task.
- If not passed, the C(snap) command will default to V(stable).
- If the value passed does not contain the C(track), it will default to C(latest). For example, if V(edge) is passed, the module will assume
the channel to be V(latest/edge).
- See U(https://snapcraft.io/docs/channels) for more details about snap channels.
type: str
required: false
options:
description:
- Set options with pattern C(key=value) or C(snap:key=value). If a snap name is given, the option will be applied to that snap only. If
the snap name is omitted, the options will be applied to all snaps listed in O(name). Options will only be applied to active snaps.
- Options will only be applied when C(state) is set to V(present). This is done after the necessary installation or refresh (upgrade/downgrade)
of all the snaps listed in O(name).
- See U(https://snapcraft.io/docs/configuration-in-snaps) for more details about snap configuration options.
required: false
type: list
elements: str
version_added: 4.4.0
dangerous:
description:
- Install the snap in dangerous mode, without validating its assertions and signatures.
- This is useful when installing local snaps that are either unsigned or have signatures that have not been acknowledged.
- See U(https://snapcraft.io/docs/install-modes) for more details about installation modes.
type: bool
required: false
default: false
version_added: 7.2.0
notes:
- Privileged operations, such as installing and configuring snaps, require root priviledges.
This is only the case if the user has not logged in to the Snap Store.
- Privileged operations, such as installing and configuring snaps, require root priviledges. This is only the case if the user has not logged
in to the Snap Store.
author:
- Victor Carceler (@vcarceler) <vcarceler@iespuigcastellar.xeill.net>
- Stanislas Lange (@angristan) <angristan@pm.me>
- Victor Carceler (@vcarceler) <vcarceler@iespuigcastellar.xeill.net>
- Stanislas Lange (@angristan) <angristan@pm.me>
seealso:
- module: community.general.snap_alias
'''
- module: community.general.snap_alias
"""
EXAMPLES = '''
EXAMPLES = r"""
# Install "foo" and "bar" snap
- name: Install foo
community.general.snap:
@ -147,35 +138,35 @@ EXAMPLES = '''
community.general.snap:
name: foo
channel: latest/edge
'''
"""
RETURN = '''
RETURN = r"""
classic:
description: Whether or not the snaps were installed with the classic confinement
type: bool
returned: When snaps are installed
description: Whether or not the snaps were installed with the classic confinement.
type: bool
returned: When snaps are installed
channel:
description: The channel the snaps were installed from
type: str
returned: When snaps are installed
description: The channel the snaps were installed from.
type: str
returned: When snaps are installed
cmd:
description: The command that was executed on the host
type: str
returned: When changed is true
description: The command that was executed on the host.
type: str
returned: When changed is true
snaps_installed:
description: The list of actually installed snaps
type: list
returned: When any snaps have been installed
description: The list of actually installed snaps.
type: list
returned: When any snaps have been installed
snaps_removed:
description: The list of actually removed snaps
type: list
returned: When any snaps have been removed
description: The list of actually removed snaps.
type: list
returned: When any snaps have been removed
options_changed:
description: The list of options set/changed in format C(snap:key=value).
type: list
returned: When any options have been changed/set
version_added: 4.4.0
'''
description: The list of options set/changed in format C(snap:key=value).
type: list
returned: When any options have been changed/set
version_added: 4.4.0
"""
import re
import json

71
plugins/modules/snap_alias.py
View File

@ -9,46 +9,45 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: snap_alias
short_description: Manages snap aliases
version_added: 4.0.0
description:
- "Manages snaps aliases."
- Manages snaps aliases.
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes
attributes:
check_mode:
support: full
diff_mode:
support: full
check_mode:
support: full
diff_mode:
support: full
options:
state:
description:
- Desired state of the alias.
type: str
choices: [ absent, present ]
default: present
name:
description:
- Name of the snap.
type: str
alias:
description:
- Aliases to be created or removed.
type: list
elements: str
aliases: [aliases]
state:
description:
- Desired state of the alias.
type: str
choices: [absent, present]
default: present
name:
description:
- Name of the snap.
type: str
alias:
description:
- Aliases to be created or removed.
type: list
elements: str
aliases: [aliases]
author:
- Alexei Znamensky (@russoz) <russoz@gmail.com>
- Alexei Znamensky (@russoz) <russoz@gmail.com>
seealso:
- module: community.general.snap
'''
- module: community.general.snap
"""
EXAMPLES = '''
EXAMPLES = r"""
# Install "foo" and "bar" snap
- name: Create snap alias
community.general.snap_alias:
@ -62,7 +61,7 @@ EXAMPLES = '''
- hw
- hw2
- hw3
state: present # optional
state: present # optional
- name: Remove one specific aliases
community.general.snap_alias:
@ -73,15 +72,15 @@ EXAMPLES = '''
community.general.snap_alias:
name: hello-world
state: absent
'''
"""
RETURN = '''
RETURN = r"""
snap_aliases:
description: The snap aliases after execution. If called in check mode, then the list represents the state before execution.
type: list
elements: str
returned: always
'''
description: The snap aliases after execution. If called in check mode, then the list represents the state before execution.
type: list
elements: str
returned: always
"""
import re

204
plugins/modules/snmp_facts.py
View File

@ -9,87 +9,85 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: snmp_facts
author:
- Patrick Ogenstad (@ogenstad)
- Patrick Ogenstad (@ogenstad)
short_description: Retrieve facts for a device using SNMP
description:
- Retrieve facts for a device using SNMP, the facts will be
inserted to the ansible_facts key.
- Retrieve facts for a device using SNMP, the facts will be inserted to the C(ansible_facts) key.
requirements:
- pysnmp
- pysnmp
extends_documentation_fragment:
- community.general.attributes
- community.general.attributes.facts
- community.general.attributes.facts_module
- community.general.attributes
- community.general.attributes.facts
- community.general.attributes.facts_module
attributes:
check_mode:
version_added: 3.3.0
# This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
check_mode:
version_added: 3.3.0
# This was backported to 2.5.4 and 1.3.11 as well, since this was a bugfix
options:
host:
description:
- Set to target SNMP server (normally C({{ inventory_hostname }})).
type: str
required: true
version:
description:
- SNMP Version to use, V(v2), V(v2c) or V(v3).
type: str
required: true
choices: [ v2, v2c, v3 ]
community:
description:
- The SNMP community string, required if O(version) is V(v2) or V(v2c).
type: str
level:
description:
- Authentication level.
- Required if O(version=v3).
type: str
choices: [ authNoPriv, authPriv ]
username:
description:
- Username for SNMPv3.
- Required if O(version=v3).
type: str
integrity:
description:
- Hashing algorithm.
- Required if O(version=v3).
type: str
choices: [ md5, sha ]
authkey:
description:
- Authentication key.
- Required O(version=v3).
type: str
privacy:
description:
- Encryption algorithm.
- Required if O(level=authPriv).
type: str
choices: [ aes, des ]
privkey:
description:
- Encryption key.
- Required if O(level=authPriv).
type: str
timeout:
description:
- Response timeout in seconds.
type: int
version_added: 2.3.0
retries:
description:
- Maximum number of request retries, 0 retries means just a single request.
type: int
version_added: 2.3.0
'''
host:
description:
- Set to target SNMP server (normally C({{ inventory_hostname }})).
type: str
required: true
version:
description:
- SNMP Version to use, V(v2), V(v2c) or V(v3).
type: str
required: true
choices: [v2, v2c, v3]
community:
description:
- The SNMP community string, required if O(version) is V(v2) or V(v2c).
type: str
level:
description:
- Authentication level.
- Required if O(version=v3).
type: str
choices: [authNoPriv, authPriv]
username:
description:
- Username for SNMPv3.
- Required if O(version=v3).
type: str
integrity:
description:
- Hashing algorithm.
- Required if O(version=v3).
type: str
choices: [md5, sha]
authkey:
description:
- Authentication key.
- Required O(version=v3).
type: str
privacy:
description:
- Encryption algorithm.
- Required if O(level=authPriv).
type: str
choices: [aes, des]
privkey:
description:
- Encryption key.
- Required if O(level=authPriv).
type: str
timeout:
description:
- Response timeout in seconds.
type: int
version_added: 2.3.0
retries:
description:
- Maximum number of request retries, 0 retries means just a single request.
type: int
version_added: 2.3.0
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Gather facts with SNMP version 2
community.general.snmp_facts:
host: '{{ inventory_hostname }}'
@ -108,9 +106,9 @@ EXAMPLES = r'''
authkey: abc12345
privkey: def6789
delegate_to: localhost
'''
"""
RETURN = r'''
RETURN = r"""
ansible_sysdescr:
description: A textual description of the entity.
returned: success
@ -152,39 +150,39 @@ ansible_interfaces:
type: dict
sample: {
"1": {
"adminstatus": "up",
"description": "",
"ifindex": "1",
"ipv4": [
{
"address": "127.0.0.1",
"netmask": "255.0.0.0"
}
],
"mac": "",
"mtu": "65536",
"name": "lo",
"operstatus": "up",
"speed": "65536"
"adminstatus": "up",
"description": "",
"ifindex": "1",
"ipv4": [
{
"address": "127.0.0.1",
"netmask": "255.0.0.0"
}
],
"mac": "",
"mtu": "65536",
"name": "lo",
"operstatus": "up",
"speed": "65536"
},
"2": {
"adminstatus": "up",
"description": "",
"ifindex": "2",
"ipv4": [
{
"address": "192.168.213.128",
"netmask": "255.255.255.0"
}
],
"mac": "000a305a52a1",
"mtu": "1500",
"name": "Intel Corporation 82545EM Gigabit Ethernet Controller (Copper)",
"operstatus": "up",
"speed": "1500"
"adminstatus": "up",
"description": "",
"ifindex": "2",
"ipv4": [
{
"address": "192.168.213.128",
"netmask": "255.255.255.0"
}
],
"mac": "000a305a52a1",
"mtu": "1500",
"name": "Intel Corporation 82545EM Gigabit Ethernet Controller (Copper)",
"operstatus": "up",
"speed": "1500"
}
}
'''
"""
import binascii
from collections import defaultdict