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

[PR #9352/9fc3092b backport][stable-9] s[e-n]*: normalize docs (#9398) 

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>
(cherry picked from commit 9fc3092bb3)

Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com>
pull/9410/head
patchback[bot] 2024-12-26 08:39:24 +01:00 committed by GitHub
parent c64705474d
commit 7506742c38
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

32
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:
@ -35,7 +34,7 @@ options:
ftype:
description:
- The file type that should have SELinux contexts applied.
- "The following file type options are available:"
- 'The following file type options are available:'
- V(a) for all files,
- V(b) for block devices,
- V(c) for character devices,
@ -53,7 +52,8 @@ options:
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.
- 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
@ -84,29 +84,25 @@ options:
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 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
author:
- 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

11
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:
@ -38,7 +37,7 @@ options:
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."
- 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:
@ -51,14 +50,14 @@ notes:
requirements: [policycoreutils-python]
author:
- 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

25
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,12 +24,12 @@ 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]
@ -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
- 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)
'''
"""
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

22
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 }}"
@ -123,7 +117,7 @@ EXAMPLES = r'''
subject: "Build failure!."
body: "Unable to pull source repository from Git server."
delegate_to: localhost
'''
"""
# =======================================
# sendgrid module support methods

63
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,13 +28,13 @@ 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
- Whether the check should be present or not.
choices: ['present', 'absent']
default: present
path:
@ -43,113 +42,113 @@ options:
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

24
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,7 +26,7 @@ options:
state:
type: str
description:
- Whether the client should be present or not
- Whether the client should be present or not.
choices: ['present', 'absent']
default: present
name:
@ -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

29
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,7 +26,7 @@ options:
state:
type: str
description:
- Whether the handler should be present or not
- Whether the handler should be present or not.
choices: ['present', 'absent']
default: present
name:
@ -38,7 +37,7 @@ options:
type:
type: str
description:
- The handler type
- The handler type.
choices: ['pipe', 'tcp', 'udp', 'transport', 'set']
filter:
type: str
@ -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

25
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
- 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: []
author: Anders Ingemann (@andsens)
'''
"""
RETURN = '''
RETURN = r"""
reasons:
description: the reasons why the module changed or did not change something
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

13
plugins/modules/seport.py
View File

@ -8,8 +8,7 @@
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:
@ -53,7 +52,7 @@ options:
default: true
ignore_selinux_state:
description:
- Run independent of selinux runtime state
- Run independent of selinux runtime state.
type: bool
default: false
local:
@ -64,15 +63,15 @@ options:
version_added: 5.6.0
notes:
- The changes are persistent across reboots.
- Not tested on any debian based system.
- Not tested on any Debian based system.
requirements:
- libselinux-python
- policycoreutils-python
author:
- 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

20
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:
@ -30,7 +29,7 @@ options:
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
- PyYAML
author:
- 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

23
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,7 +47,8 @@ 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']
@ -58,9 +59,9 @@ author:
- 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:
@ -72,12 +73,12 @@ EXAMPLES = r'''
community.general.shutdown:
search_paths:
- '/lib/molly-guard'
'''
"""
RETURN = r'''
RETURN = r"""
shutdown:
description: V(true) if the machine has been shut down.
returned: always
type: bool
sample: true
'''
"""

18
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
@ -40,22 +39,19 @@ options:
required: false
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

11
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:
@ -176,9 +175,9 @@ requirements:
- softlayer >= 4.1.1
author:
- Matt Colton (@mcltn)
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Build instance
hosts: localhost
gather_facts: false
@ -265,10 +264,10 @@ EXAMPLES = '''
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

67
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

16
plugins/modules/slackpkg.py
View File

@ -15,13 +15,11 @@ 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
attributes:
@ -32,7 +30,7 @@ attributes:
options:
name:
description:
- name of package to install/remove
- Name of package to install/remove.
required: true
type: list
elements: str
@ -48,16 +46,16 @@ options:
update_cache:
description:
- update the package database first
- Update the package database first.
required: false
default: false
type: bool
author: Kim Nørgaard (@KimNorgaard)
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

25
plugins/modules/smartos_image_info.py
View File

@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: smartos_image_info
short_description: Get SmartOS image details
description:
@ -26,14 +25,12 @@ attributes:
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).
- 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

61
plugins/modules/snap.py
View File

@ -13,8 +13,7 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: snap
short_description: Manages snaps
description:
@ -31,17 +30,15 @@ options:
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.
- 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.
- 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
@ -49,34 +46,29 @@ options:
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.
- 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.
- 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).
- 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).
- 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
@ -91,18 +83,17 @@ options:
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>
seealso:
- module: community.general.snap_alias
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
# Install "foo" and "bar" snap
- name: Install foo
community.general.snap:
@ -147,27 +138,27 @@ 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
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
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
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
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
description: The list of actually removed snaps.
type: list
returned: When any snaps have been removed
options_changed:
@ -175,7 +166,7 @@ options_changed:
type: list
returned: When any options have been changed/set
version_added: 4.4.0
'''
"""
import re
import json

15
plugins/modules/snap_alias.py
View File

@ -9,13 +9,12 @@
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
attributes:
@ -46,9 +45,9 @@ author:
seealso:
- module: community.general.snap
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
# Install "foo" and "bar" snap
- name: Create snap alias
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
'''
"""
import re

16
plugins/modules/snmp_facts.py
View File

@ -9,15 +9,13 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: snmp_facts
author:
- 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
extends_documentation_fragment:
@ -87,9 +85,9 @@ options:
- 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
@ -184,7 +182,7 @@ ansible_interfaces:
"speed": "1500"
}
}
'''
"""
import binascii
from collections import defaultdict