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

l*.py: normalize docs (#9390)

pull/9101/merge
Alexei Znamensky 2024-12-26 21:12:05 +13:00 committed by GitHub
parent 6b7ea3443d
commit cea6eeef37
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
25 changed files with 1194 additions and 1350 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
plugins/modules/launchd.py
View File

@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r''' DOCUMENTATION = r"""
---
module: launchd module: launchd
author: author:
- Martin Migasiewicz (@martinm82) - Martin Migasiewicz (@martinm82)
@ -20,57 +19,52 @@ description:
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: full support: full
diff_mode: diff_mode:
support: none support: none
options: options:
name: name:
description: description:
- Name of the service. - Name of the service.
type: str type: str
required: true required: true
plist: plist:
description: description:
- Name of the V(.plist) file for the service. - Name of the V(.plist) file for the service.
- Defaults to V({name}.plist). - Defaults to V({name}.plist).
type: str type: str
version_added: 10.1.0 version_added: 10.1.0
state: state:
description: description:
- V(started)/V(stopped) are idempotent actions that will not run - V(started)/V(stopped) are idempotent actions that will not run commands unless necessary.
commands unless necessary. - Launchd does not support V(restarted) nor V(reloaded) natively. These will trigger a stop/start (restarted) or an unload/load (reloaded).
- Launchd does not support V(restarted) nor V(reloaded) natively. - V(restarted) unloads and loads the service before start to ensure that the latest job definition (plist) is used.
These will trigger a stop/start (restarted) or an unload/load - V(reloaded) unloads and loads the service to ensure that the latest job definition (plist) is used. Whether a service is started or stopped
(reloaded). depends on the content of the definition file.
- V(restarted) unloads and loads the service before start to ensure type: str
that the latest job definition (plist) is used. choices: [reloaded, restarted, started, stopped, unloaded]
- V(reloaded) unloads and loads the service to ensure that the latest enabled:
job definition (plist) is used. Whether a service is started or description:
stopped depends on the content of the definition file.
type: str
choices: [ reloaded, restarted, started, stopped, unloaded ]
enabled:
description:
- Whether the service should start on boot. - Whether the service should start on boot.
- B(At least one of state and enabled are required.) - B(At least one of state and enabled are required).
type: bool type: bool
force_stop: force_stop:
description: description:
- Whether the service should not be restarted automatically by launchd. - Whether the service should not be restarted automatically by launchd.
- Services might have the 'KeepAlive' attribute set to true in a launchd configuration. - Services might have the 'KeepAlive' attribute set to true in a launchd configuration. In case this is set to true, stopping a service
In case this is set to true, stopping a service will cause that launchd starts the service again. will cause that launchd starts the service again.
- Set this option to V(true) to let this module change the 'KeepAlive' attribute to V(false). - Set this option to V(true) to let this module change the C(KeepAlive) attribute to V(false).
type: bool type: bool
default: false default: false
notes: notes:
- A user must privileged to manage services using this module. - A user must privileged to manage services using this module.
requirements: requirements:
- A system managed by launchd - A system managed by launchd
- The plistlib python library - The plistlib Python library
''' """
EXAMPLES = r''' EXAMPLES = r"""
- name: Make sure spotify webhelper is started - name: Make sure spotify webhelper is started
community.general.launchd: community.general.launchd:
name: com.spotify.webhelper name: com.spotify.webhelper
@ -112,11 +106,11 @@ EXAMPLES = r'''
name: com.openssh.sshd name: com.openssh.sshd
plist: ssh.plist plist: ssh.plist
state: restarted state: restarted
''' """
RETURN = r''' RETURN = r"""
status: status:
description: Metadata about service status description: Metadata about service status.
returned: always returned: always
type: dict type: dict
sample: sample:
@ -126,7 +120,7 @@ status:
"previous_pid": "82636", "previous_pid": "82636",
"previous_state": "running" "previous_state": "running"
} }
''' """
import os import os
import plistlib import plistlib

26
plugins/modules/layman.py
View File

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

30
plugins/modules/lbu.py
View File

@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: lbu module: lbu
short_description: Local Backup Utility for Alpine Linux short_description: Local Backup Utility for Alpine Linux
@ -17,8 +16,7 @@ short_description: Local Backup Utility for Alpine Linux
version_added: '0.2.0' version_added: '0.2.0'
description: description:
- Manage Local Backup Utility of Alpine Linux in run-from-RAM mode - Manage Local Backup Utility of Alpine Linux in run-from-RAM mode.
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
@ -31,24 +29,24 @@ attributes:
options: options:
commit: commit:
description: description:
- Control whether to commit changed files. - Control whether to commit changed files.
type: bool type: bool
exclude: exclude:
description: description:
- List of paths to exclude. - List of paths to exclude.
type: list type: list
elements: str elements: str
include: include:
description: description:
- List of paths to include. - List of paths to include.
type: list type: list
elements: str elements: str
author: author:
- Kaarle Ritvanen (@kunkku) - Kaarle Ritvanen (@kunkku)
''' """
EXAMPLES = ''' EXAMPLES = r"""
# Commit changed files (if any) # Commit changed files (if any)
- name: Commit - name: Commit
community.general.lbu: community.general.lbu:
@ -59,22 +57,22 @@ EXAMPLES = '''
community.general.lbu: community.general.lbu:
commit: true commit: true
exclude: exclude:
- /etc/opt - /etc/opt
# Include paths without committing # Include paths without committing
- name: Include file and directory - name: Include file and directory
community.general.lbu: community.general.lbu:
include: include:
- /root/.ssh/authorized_keys - /root/.ssh/authorized_keys
- /var/lib/misc - /var/lib/misc
''' """
RETURN = ''' RETURN = r"""
msg: msg:
description: Error message description: Error message.
type: str type: str
returned: on failure returned: on failure
''' """
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule

122
plugins/modules/ldap_attrs.py
View File

@ -12,27 +12,19 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r''' DOCUMENTATION = r"""
---
module: ldap_attrs module: ldap_attrs
short_description: Add or remove multiple LDAP attribute values short_description: Add or remove multiple LDAP attribute values
description: description:
- Add or remove multiple LDAP attribute values. - Add or remove multiple LDAP attribute values.
notes: notes:
- This only deals with attributes on existing entries. To add or remove - This only deals with attributes on existing entries. To add or remove whole entries, see M(community.general.ldap_entry).
whole entries, see M(community.general.ldap_entry). - The default authentication settings will attempt to use a SASL EXTERNAL bind over a UNIX domain socket. This works well with the default Ubuntu
- The default authentication settings will attempt to use a SASL EXTERNAL install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL rule allowing root to modify the server configuration. If you need
bind over a UNIX domain socket. This works well with the default Ubuntu to use a simple bind to access your server, pass the credentials in O(bind_dn) and O(bind_pw).
install for example, which includes a cn=peercred,cn=external,cn=auth ACL - For O(state=present) and O(state=absent), all value comparisons are performed on the server for maximum accuracy. For O(state=exact), values
rule allowing root to modify the server configuration. If you need to use have to be compared in Python, which obviously ignores LDAP matching rules. This should work out in most cases, but it is theoretically possible
a simple bind to access your server, pass the credentials in O(bind_dn) to see spurious changes when target and actual values are semantically identical but lexically distinct.
and O(bind_pw).
- For O(state=present) and O(state=absent), all value comparisons are
performed on the server for maximum accuracy. For O(state=exact), values
have to be compared in Python, which obviously ignores LDAP matching
rules. This should work out in most cases, but it is theoretically
possible to see spurious changes when target and actual values are
semantically identical but lexically distinct.
version_added: '0.2.0' version_added: '0.2.0'
author: author:
- Jiri Tyr (@jtyr) - Jiri Tyr (@jtyr)
@ -53,46 +45,38 @@ options:
choices: [present, absent, exact] choices: [present, absent, exact]
default: present default: present
description: description:
- The state of the attribute values. If V(present), all given attribute - The state of the attribute values. If V(present), all given attribute values will be added if they are missing. If V(absent), all given
values will be added if they're missing. If V(absent), all given attribute values will be removed if present. If V(exact), the set of attribute values will be forced to exactly those provided and no
attribute values will be removed if present. If V(exact), the set of others. If O(state=exact) and the attribute value is empty, all values for this attribute will be removed.
attribute values will be forced to exactly those provided and no others.
If O(state=exact) and the attribute value is empty, all values for
this attribute will be removed.
attributes: attributes:
required: true required: true
type: dict type: dict
description: description:
- The attribute(s) and value(s) to add or remove. - The attribute(s) and value(s) to add or remove.
- Each attribute value can be a string for single-valued attributes or - Each attribute value can be a string for single-valued attributes or a list of strings for multi-valued attributes.
a list of strings for multi-valued attributes. - If you specify values for this option in YAML, please note that you can improve readability for long string values by using YAML block
- If you specify values for this option in YAML, please note that you can improve modifiers as seen in the examples for this module.
readability for long string values by using YAML block modifiers as seen in the - Note that when using values that YAML/ansible-core interprets as other types, like V(yes), V(no) (booleans), or V(2.10) (float), make
examples for this module. sure to quote them if these are meant to be strings. Otherwise the wrong values may be sent to LDAP.
- Note that when using values that YAML/ansible-core interprets as other types,
like V(yes), V(no) (booleans), or V(2.10) (float), make sure to quote them if
these are meant to be strings. Otherwise the wrong values may be sent to LDAP.
ordered: ordered:
required: false required: false
type: bool type: bool
default: false default: false
description: description:
- If V(true), prepend list values with X-ORDERED index numbers in all - If V(true), prepend list values with X-ORDERED index numbers in all attributes specified in the current task. This is useful mostly with
attributes specified in the current task. This is useful mostly with
C(olcAccess) attribute to easily manage LDAP Access Control Lists. C(olcAccess) attribute to easily manage LDAP Access Control Lists.
extends_documentation_fragment: extends_documentation_fragment:
- community.general.ldap.documentation - community.general.ldap.documentation
- community.general.attributes - community.general.attributes
"""
'''
EXAMPLES = r''' EXAMPLES = r"""
- name: Configure directory number 1 for example.com - name: Configure directory number 1 for example.com
community.general.ldap_attrs: community.general.ldap_attrs:
dn: olcDatabase={1}hdb,cn=config dn: olcDatabase={1}hdb,cn=config
attributes: attributes:
olcSuffix: dc=example,dc=com olcSuffix: dc=example,dc=com
state: exact state: exact
# The complex argument format is required here to pass a list of ACL strings. # The complex argument format is required here to pass a list of ACL strings.
@ -100,17 +84,17 @@ EXAMPLES = r'''
community.general.ldap_attrs: community.general.ldap_attrs:
dn: olcDatabase={1}hdb,cn=config dn: olcDatabase={1}hdb,cn=config
attributes: attributes:
olcAccess: olcAccess:
- >- - >-
{0}to attrs=userPassword,shadowLastChange {0}to attrs=userPassword,shadowLastChange
by self write by self write
by anonymous auth by anonymous auth
by dn="cn=admin,dc=example,dc=com" write by dn="cn=admin,dc=example,dc=com" write
by * none' by * none'
- >- - >-
{1}to dn.base="dc=example,dc=com" {1}to dn.base="dc=example,dc=com"
by dn="cn=admin,dc=example,dc=com" write by dn="cn=admin,dc=example,dc=com" write
by * read by * read
state: exact state: exact
# An alternative approach with automatic X-ORDERED numbering # An alternative approach with automatic X-ORDERED numbering
@ -118,17 +102,17 @@ EXAMPLES = r'''
community.general.ldap_attrs: community.general.ldap_attrs:
dn: olcDatabase={1}hdb,cn=config dn: olcDatabase={1}hdb,cn=config
attributes: attributes:
olcAccess: olcAccess:
- >- - >-
to attrs=userPassword,shadowLastChange to attrs=userPassword,shadowLastChange
by self write by self write
by anonymous auth by anonymous auth
by dn="cn=admin,dc=example,dc=com" write by dn="cn=admin,dc=example,dc=com" write
by * none' by * none'
- >- - >-
to dn.base="dc=example,dc=com" to dn.base="dc=example,dc=com"
by dn="cn=admin,dc=example,dc=com" write by dn="cn=admin,dc=example,dc=com" write
by * read by * read
ordered: true ordered: true
state: exact state: exact
@ -136,23 +120,23 @@ EXAMPLES = r'''
community.general.ldap_attrs: community.general.ldap_attrs:
dn: olcDatabase={1}hdb,cn=config dn: olcDatabase={1}hdb,cn=config
attributes: attributes:
olcDbIndex: olcDbIndex:
- objectClass eq - objectClass eq
- uid eq - uid eq
- name: Set up a root user, which we can use later to bootstrap the directory - name: Set up a root user, which we can use later to bootstrap the directory
community.general.ldap_attrs: community.general.ldap_attrs:
dn: olcDatabase={1}hdb,cn=config dn: olcDatabase={1}hdb,cn=config
attributes: attributes:
olcRootDN: cn=root,dc=example,dc=com olcRootDN: cn=root,dc=example,dc=com
olcRootPW: "{SSHA}tabyipcHzhwESzRaGA7oQ/SDoBZQOGND" olcRootPW: "{SSHA}tabyipcHzhwESzRaGA7oQ/SDoBZQOGND"
state: exact state: exact
- name: Remove an attribute with a specific value - name: Remove an attribute with a specific value
community.general.ldap_attrs: community.general.ldap_attrs:
dn: uid=jdoe,ou=people,dc=example,dc=com dn: uid=jdoe,ou=people,dc=example,dc=com
attributes: attributes:
description: "An example user account" description: "An example user account"
state: absent state: absent
server_uri: ldap://localhost/ server_uri: ldap://localhost/
bind_dn: cn=admin,dc=example,dc=com bind_dn: cn=admin,dc=example,dc=com
@ -162,22 +146,22 @@ EXAMPLES = r'''
community.general.ldap_attrs: community.general.ldap_attrs:
dn: uid=jdoe,ou=people,dc=example,dc=com dn: uid=jdoe,ou=people,dc=example,dc=com
attributes: attributes:
description: [] description: []
state: exact state: exact
server_uri: ldap://localhost/ server_uri: ldap://localhost/
bind_dn: cn=admin,dc=example,dc=com bind_dn: cn=admin,dc=example,dc=com
bind_pw: password bind_pw: password
''' """
RETURN = r''' RETURN = r"""
modlist: modlist:
description: list of modified parameters description: List of modified parameters.
returned: success returned: success
type: list type: list
sample: sample:
- [2, "olcRootDN", ["cn=root,dc=example,dc=com"]] - [2, "olcRootDN", ["cn=root,dc=example,dc=com"]]
''' """
import traceback import traceback

73
plugins/modules/ldap_entry.py
View File

@ -11,21 +11,16 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: ldap_entry module: ldap_entry
short_description: Add or remove LDAP entries short_description: Add or remove LDAP entries
description: description:
- Add or remove LDAP entries. This module only asserts the existence or - Add or remove LDAP entries. This module only asserts the existence or non-existence of an LDAP entry, not its attributes. To assert the attribute
non-existence of an LDAP entry, not its attributes. To assert the values of an entry, see M(community.general.ldap_attrs).
attribute values of an entry, see M(community.general.ldap_attrs).
notes: notes:
- The default authentication settings will attempt to use a SASL EXTERNAL - The default authentication settings will attempt to use a SASL EXTERNAL bind over a UNIX domain socket. This works well with the default Ubuntu
bind over a UNIX domain socket. This works well with the default Ubuntu install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL rule allowing root to modify the server configuration. If you need
install for example, which includes a cn=peercred,cn=external,cn=auth ACL to use a simple bind to access your server, pass the credentials in O(bind_dn) and O(bind_pw).
rule allowing root to modify the server configuration. If you need to use
a simple bind to access your server, pass the credentials in O(bind_dn)
and O(bind_pw).
author: author:
- Jiri Tyr (@jtyr) - Jiri Tyr (@jtyr)
requirements: requirements:
@ -38,24 +33,18 @@ attributes:
options: options:
attributes: attributes:
description: description:
- If O(state=present), attributes necessary to create an entry. Existing - If O(state=present), attributes necessary to create an entry. Existing entries are never modified. To assert specific attribute values
entries are never modified. To assert specific attribute values on an on an existing entry, use M(community.general.ldap_attrs) module instead.
existing entry, use M(community.general.ldap_attrs) module instead. - Each attribute value can be a string for single-valued attributes or a list of strings for multi-valued attributes.
- Each attribute value can be a string for single-valued attributes or - If you specify values for this option in YAML, please note that you can improve readability for long string values by using YAML block
a list of strings for multi-valued attributes. modifiers as seen in the examples for this module.
- If you specify values for this option in YAML, please note that you can improve - Note that when using values that YAML/ansible-core interprets as other types, like V(yes), V(no) (booleans), or V(2.10) (float), make
readability for long string values by using YAML block modifiers as seen in the sure to quote them if these are meant to be strings. Otherwise the wrong values may be sent to LDAP.
examples for this module.
- Note that when using values that YAML/ansible-core interprets as other types,
like V(yes), V(no) (booleans), or V(2.10) (float), make sure to quote them if
these are meant to be strings. Otherwise the wrong values may be sent to LDAP.
type: dict type: dict
default: {} default: {}
objectClass: objectClass:
description: description:
- If O(state=present), value or list of values to use when creating - If O(state=present), value or list of values to use when creating the entry. It can either be a string or an actual list of strings.
the entry. It can either be a string or an actual list of
strings.
type: list type: list
elements: str elements: str
state: state:
@ -66,19 +55,17 @@ options:
type: str type: str
recursive: recursive:
description: description:
- If O(state=delete), a flag indicating whether a single entry or the - If O(state=delete), a flag indicating whether a single entry or the whole branch must be deleted.
whole branch must be deleted.
type: bool type: bool
default: false default: false
version_added: 4.6.0 version_added: 4.6.0
extends_documentation_fragment: extends_documentation_fragment:
- community.general.ldap.documentation - community.general.ldap.documentation
- community.general.attributes - community.general.attributes
"""
'''
EXAMPLES = """ EXAMPLES = r"""
- name: Make sure we have a parent entry for users - name: Make sure we have a parent entry for users
community.general.ldap_entry: community.general.ldap_entry:
dn: ou=users,dc=example,dc=com dn: ou=users,dc=example,dc=com
@ -103,19 +90,19 @@ EXAMPLES = """
attributes: attributes:
description: An LDAP Administrator description: An LDAP Administrator
roleOccupant: roleOccupant:
- cn=Chocs Puddington,ou=Information Technology,dc=example,dc=com - cn=Chocs Puddington,ou=Information Technology,dc=example,dc=com
- cn=Alice Stronginthebrain,ou=Information Technology,dc=example,dc=com - cn=Alice Stronginthebrain,ou=Information Technology,dc=example,dc=com
olcAccess: olcAccess:
- >- - >-
{0}to attrs=userPassword,shadowLastChange {0}to attrs=userPassword,shadowLastChange
by self write by self write
by anonymous auth by anonymous auth
by dn="cn=admin,dc=example,dc=com" write by dn="cn=admin,dc=example,dc=com" write
by * none' by * none'
- >- - >-
{1}to dn.base="dc=example,dc=com" {1}to dn.base="dc=example,dc=com"
by dn="cn=admin,dc=example,dc=com" write by dn="cn=admin,dc=example,dc=com" write
by * read by * read
- name: Get rid of an old entry - name: Get rid of an old entry
community.general.ldap_entry: community.general.ldap_entry:
@ -143,7 +130,7 @@ EXAMPLES = """
""" """
RETURN = """ RETURN = r"""
# Default return values # Default return values
""" """

28
plugins/modules/ldap_passwd.py
View File

@ -9,21 +9,16 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: ldap_passwd module: ldap_passwd
short_description: Set passwords in LDAP short_description: Set passwords in LDAP
description: description:
- Set a password for an LDAP entry. This module only asserts that - Set a password for an LDAP entry. This module only asserts that a given password is valid for a given entry. To assert the existence of an
a given password is valid for a given entry. To assert the entry, see M(community.general.ldap_entry).
existence of an entry, see M(community.general.ldap_entry).
notes: notes:
- The default authentication settings will attempt to use a SASL EXTERNAL - The default authentication settings will attempt to use a SASL EXTERNAL bind over a UNIX domain socket. This works well with the default Ubuntu
bind over a UNIX domain socket. This works well with the default Ubuntu install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL rule allowing root to modify the server configuration. If you
install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL need to use a simple bind to access your server, pass the credentials in O(bind_dn) and O(bind_pw).
rule allowing root to modify the server configuration. If you need to use
a simple bind to access your server, pass the credentials in O(bind_dn)
and O(bind_pw).
author: author:
- Keller Fuchs (@KellerFuchs) - Keller Fuchs (@KellerFuchs)
requirements: requirements:
@ -41,10 +36,9 @@ options:
extends_documentation_fragment: extends_documentation_fragment:
- community.general.ldap.documentation - community.general.ldap.documentation
- community.general.attributes - community.general.attributes
"""
''' EXAMPLES = r"""
EXAMPLES = """
- name: Set a password for the admin user - name: Set a password for the admin user
community.general.ldap_passwd: community.general.ldap_passwd:
dn: cn=admin,dc=example,dc=com dn: cn=admin,dc=example,dc=com
@ -56,13 +50,13 @@ EXAMPLES = """
passwd: "{{ item.value }}" passwd: "{{ item.value }}"
with_dict: with_dict:
alice: alice123123 alice: alice123123
bob: "|30b!" bob: "|30b!"
admin: "{{ vault_secret }}" admin: "{{ vault_secret }}"
""" """
RETURN = """ RETURN = r"""
modlist: modlist:
description: list of modified parameters description: List of modified parameters.
returned: success returned: success
type: list type: list
sample: sample:

30
plugins/modules/ldap_search.py
View File

@ -10,19 +10,15 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r""" DOCUMENTATION = r"""
---
module: ldap_search module: ldap_search
version_added: '0.2.0' version_added: '0.2.0'
short_description: Search for entries in a LDAP server short_description: Search for entries in a LDAP server
description: description:
- Return the results of an LDAP search. - Return the results of an LDAP search.
notes: notes:
- The default authentication settings will attempt to use a SASL EXTERNAL - The default authentication settings will attempt to use a SASL EXTERNAL bind over a UNIX domain socket. This works well with the default Ubuntu
bind over a UNIX domain socket. This works well with the default Ubuntu install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL rule allowing root to modify the server configuration. If you
install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL need to use a simple bind to access your server, pass the credentials in O(bind_dn) and O(bind_pw).
rule allowing root to modify the server configuration. If you need to use
a simple bind to access your server, pass the credentials in O(bind_dn)
and O(bind_pw).
author: author:
- Sebastian Pfahl (@eryx12o45) - Sebastian Pfahl (@eryx12o45)
requirements: requirements:
@ -55,30 +51,26 @@ options:
type: list type: list
elements: str elements: str
description: description:
- A list of attributes for limiting the result. Use an - A list of attributes for limiting the result. Use an actual list or a comma-separated string.
actual list or a comma-separated string.
schema: schema:
default: false default: false
type: bool type: bool
description: description:
- Set to V(true) to return the full attribute schema of entries, not - Set to V(true) to return the full attribute schema of entries, not their attribute values. Overrides O(attrs) when provided.
their attribute values. Overrides O(attrs) when provided.
page_size: page_size:
default: 0 default: 0
type: int type: int
description: description:
- The page size when performing a simple paged result search (RFC 2696). - The page size when performing a simple paged result search (RFC 2696). This setting can be tuned to reduce issues with timeouts and server
This setting can be tuned to reduce issues with timeouts and server limits. limits.
- Setting the page size to V(0) (default) disables paged searching. - Setting the page size to V(0) (default) disables paged searching.
version_added: 7.1.0 version_added: 7.1.0
base64_attributes: base64_attributes:
description: description:
- If provided, all attribute values returned that are listed in this option - If provided, all attribute values returned that are listed in this option will be Base64 encoded.
will be Base64 encoded. - If the special value V(*) appears in this list, all attributes will be Base64 encoded.
- If the special value V(*) appears in this list, all attributes will be - All other attribute values will be converted to UTF-8 strings. If they contain binary data, please note that invalid UTF-8 bytes will
Base64 encoded. be omitted.
- All other attribute values will be converted to UTF-8 strings. If they
contain binary data, please note that invalid UTF-8 bytes will be omitted.
type: list type: list
elements: str elements: str
version_added: 7.0.0 version_added: 7.0.0

117
plugins/modules/librato_annotation.py
View File

@ -9,74 +9,73 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: librato_annotation module: librato_annotation
short_description: Create an annotation in librato short_description: Create an annotation in librato
description: description:
- Create an annotation event on the given annotation stream :name. If the annotation stream does not exist, it will be created automatically - Create an annotation event on the given annotation stream :name. If the annotation stream does not exist, it will be created automatically.
author: "Seth Edwards (@Sedward)" author: "Seth Edwards (@Sedward)"
requirements: [] requirements: []
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: none support: none
diff_mode: diff_mode:
support: none support: none
options: options:
user: user:
type: str type: str
description:
- Librato account username
required: true
api_key:
type: str
description:
- Librato account api key
required: true
name:
type: str
description:
- The annotation stream name
- If the annotation stream does not exist, it will be created automatically
required: false
title:
type: str
description:
- The title of an annotation is a string and may contain spaces
- The title should be a short, high-level summary of the annotation e.g. v45 Deployment
required: true
source:
type: str
description:
- A string which describes the originating source of an annotation when that annotation is tracked across multiple members of a population
required: false
description: description:
type: str - Librato account username.
description: required: true
- The description contains extra metadata about a particular annotation api_key:
- The description should contain specifics on the individual annotation e.g. Deployed 9b562b2 shipped new feature foo! type: str
required: false description:
start_time: - Librato account api key.
type: int required: true
description: name:
- The unix timestamp indicating the time at which the event referenced by this annotation started type: str
required: false description:
end_time: - The annotation stream name.
type: int - If the annotation stream does not exist, it will be created automatically.
description: required: false
- The unix timestamp indicating the time at which the event referenced by this annotation ended title:
- For events that have a duration, this is a useful way to annotate the duration of the event type: str
required: false description:
links: - The title of an annotation is a string and may contain spaces.
type: list - The title should be a short, high-level summary of the annotation for example V(v45 Deployment).
elements: dict required: true
description: source:
- See examples type: str
''' description:
- A string which describes the originating source of an annotation when that annotation is tracked across multiple members of a population.
required: false
description:
type: str
description:
- The description contains extra metadata about a particular annotation.
- The description should contain specifics on the individual annotation for example V(Deployed 9b562b2 shipped new feature foo!).
required: false
start_time:
type: int
description:
- The unix timestamp indicating the time at which the event referenced by this annotation started.
required: false
end_time:
type: int
description:
- The unix timestamp indicating the time at which the event referenced by this annotation ended.
- For events that have a duration, this is a useful way to annotate the duration of the event.
required: false
links:
type: list
elements: dict
description:
- See examples.
"""
EXAMPLES = ''' EXAMPLES = r"""
- name: Create a simple annotation event with a source - name: Create a simple annotation event with a source
community.general.librato_annotation: community.general.librato_annotation:
user: user@example.com user: user@example.com
@ -105,7 +104,7 @@ EXAMPLES = '''
description: This is a detailed description of maintenance description: This is a detailed description of maintenance
start_time: 1395940006 start_time: 1395940006
end_time: 1395954406 end_time: 1395954406
''' """
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.urls import fetch_url from ansible.module_utils.urls import fetch_url

216
plugins/modules/linode.py
View File

@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: linode module: linode
short_description: Manage instances on the Linode Public Cloud short_description: Manage instances on the Linode Public Cloud
description: description:
@ -24,34 +23,32 @@ attributes:
options: options:
state: state:
description: description:
- Indicate desired state of the resource - Indicate desired state of the resource.
choices: [ absent, active, deleted, present, restarted, started, stopped ] choices: [absent, active, deleted, present, restarted, started, stopped]
default: present default: present
type: str type: str
api_key: api_key:
description: description:
- Linode API key. - Linode API key.
- E(LINODE_API_KEY) environment variable can be used instead. - E(LINODE_API_KEY) environment variable can be used instead.
type: str type: str
required: true required: true
name: name:
description: description:
- Name to give the instance (alphanumeric, dashes, underscore). - Name to give the instance (alphanumeric, dashes, underscore).
- To keep sanity on the Linode Web Console, name is prepended with C(LinodeID-). - To keep sanity on the Linode Web Console, name is prepended with C(LinodeID-).
required: true required: true
type: str type: str
displaygroup: displaygroup:
description: description:
- Add the instance to a Display Group in Linode Manager. - Add the instance to a Display Group in Linode Manager.
type: str type: str
default: '' default: ''
linode_id: linode_id:
description: description:
- Unique ID of a linode server. This value is read-only in the sense that - Unique ID of a linode server. This value is read-only in the sense that if you specify it on creation of a Linode it will not be used.
if you specify it on creation of a Linode it will not be used. The The Linode API generates these IDs and we can those generated value here to reference a Linode more specifically. This is useful for idempotence.
Linode API generates these IDs and we can those generated value here to aliases: [lid]
reference a Linode more specifically. This is useful for idempotence.
aliases: [ lid ]
type: int type: int
additional_disks: additional_disks:
description: description:
@ -61,119 +58,118 @@ options:
elements: dict elements: dict
alert_bwin_enabled: alert_bwin_enabled:
description: description:
- Set status of bandwidth in alerts. - Set status of bandwidth in alerts.
type: bool type: bool
alert_bwin_threshold: alert_bwin_threshold:
description: description:
- Set threshold in MB of bandwidth in alerts. - Set threshold in MB of bandwidth in alerts.
type: int type: int
alert_bwout_enabled: alert_bwout_enabled:
description: description:
- Set status of bandwidth out alerts. - Set status of bandwidth out alerts.
type: bool type: bool
alert_bwout_threshold: alert_bwout_threshold:
description: description:
- Set threshold in MB of bandwidth out alerts. - Set threshold in MB of bandwidth out alerts.
type: int type: int
alert_bwquota_enabled: alert_bwquota_enabled:
description: description:
- Set status of bandwidth quota alerts as percentage of network transfer quota. - Set status of bandwidth quota alerts as percentage of network transfer quota.
type: bool type: bool
alert_bwquota_threshold: alert_bwquota_threshold:
description: description:
- Set threshold in MB of bandwidth quota alerts. - Set threshold in MB of bandwidth quota alerts.
type: int type: int
alert_cpu_enabled: alert_cpu_enabled:
description: description:
- Set status of receiving CPU usage alerts. - Set status of receiving CPU usage alerts.
type: bool type: bool
alert_cpu_threshold: alert_cpu_threshold:
description: description:
- Set percentage threshold for receiving CPU usage alerts. Each CPU core adds 100% to total. - Set percentage threshold for receiving CPU usage alerts. Each CPU core adds 100% to total.
type: int type: int
alert_diskio_enabled: alert_diskio_enabled:
description: description:
- Set status of receiving disk IO alerts. - Set status of receiving disk IO alerts.
type: bool type: bool
alert_diskio_threshold: alert_diskio_threshold:
description: description:
- Set threshold for average IO ops/sec over 2 hour period. - Set threshold for average IO ops/sec over 2 hour period.
type: int type: int
backupweeklyday: backupweeklyday:
description: description:
- Day of the week to take backups. - Day of the week to take backups.
type: int type: int
backupwindow: backupwindow:
description: description:
- The time window in which backups will be taken. - The time window in which backups will be taken.
type: int type: int
plan: plan:
description: description:
- plan to use for the instance (Linode plan) - Plan to use for the instance (Linode plan).
type: int type: int
payment_term: payment_term:
description: description:
- payment term to use for the instance (payment term in months) - Payment term to use for the instance (payment term in months).
default: 1 default: 1
choices: [ 1, 12, 24 ] choices: [1, 12, 24]
type: int type: int
password: password:
description: description:
- root password to apply to a new server (auto generated if missing) - Root password to apply to a new server (auto generated if missing).
type: str type: str
private_ip: private_ip:
description: description:
- Add private IPv4 address when Linode is created. - Add private IPv4 address when Linode is created.
- Default is V(false). - Default is V(false).
type: bool type: bool
ssh_pub_key: ssh_pub_key:
description: description:
- SSH public key applied to root user - SSH public key applied to root user.
type: str type: str
swap: swap:
description: description:
- swap size in MB - Swap size in MB.
default: 512 default: 512
type: int type: int
distribution: distribution:
description: description:
- distribution to use for the instance (Linode Distribution) - Distribution to use for the instance (Linode Distribution).
type: int type: int
datacenter: datacenter:
description: description:
- datacenter to create an instance in (Linode Datacenter) - Datacenter to create an instance in (Linode Datacenter).
type: int type: int
kernel_id: kernel_id:
description: description:
- kernel to use for the instance (Linode Kernel) - Kernel to use for the instance (Linode Kernel).
type: int type: int
wait: wait:
description: description:
- wait for the instance to be in state V(running) before returning - Wait for the instance to be in state V(running) before returning.
type: bool type: bool
default: true default: true
wait_timeout: wait_timeout:
description: description:
- how long before wait gives up, in seconds - How long before wait gives up, in seconds.
default: 300 default: 300
type: int type: int
watchdog: watchdog:
description: description:
- Set status of Lassie watchdog. - Set status of Lassie watchdog.
type: bool type: bool
default: true default: true
requirements: requirements:
- linode-python - linode-python
author: author:
- Vincent Viallet (@zbal) - Vincent Viallet (@zbal)
notes: notes:
- Please note, linode-python does not have python 3 support. - Please note, linode-python does not have python 3 support.
- This module uses the now deprecated v3 of the Linode API. - This module uses the now deprecated v3 of the Linode API.
- Please review U(https://www.linode.com/api/linode) for determining the required parameters. - Please review U(https://www.linode.com/api/linode) for determining the required parameters.
''' """
EXAMPLES = '''
EXAMPLES = r"""
- name: Create a new Linode - name: Create a new Linode
community.general.linode: community.general.linode:
name: linode-test1 name: linode-test1
@ -185,97 +181,97 @@ EXAMPLES = '''
- name: Create a server with a private IP Address - name: Create a server with a private IP Address
community.general.linode: community.general.linode:
module: linode module: linode
api_key: 'longStringFromLinodeApi' api_key: 'longStringFromLinodeApi'
name: linode-test1 name: linode-test1
plan: 1 plan: 1
datacenter: 2 datacenter: 2
distribution: 99 distribution: 99
password: 'superSecureRootPassword' password: 'superSecureRootPassword'
private_ip: true private_ip: true
ssh_pub_key: 'ssh-rsa qwerty' ssh_pub_key: 'ssh-rsa qwerty'
swap: 768 swap: 768
wait: true wait: true
wait_timeout: 600 wait_timeout: 600
state: present state: present
delegate_to: localhost delegate_to: localhost
register: linode_creation register: linode_creation
- name: Fully configure new server - name: Fully configure new server
community.general.linode: community.general.linode:
api_key: 'longStringFromLinodeApi' api_key: 'longStringFromLinodeApi'
name: linode-test1 name: linode-test1
plan: 4 plan: 4
datacenter: 2 datacenter: 2
distribution: 99 distribution: 99
kernel_id: 138 kernel_id: 138
password: 'superSecureRootPassword' password: 'superSecureRootPassword'
private_ip: true private_ip: true
ssh_pub_key: 'ssh-rsa qwerty' ssh_pub_key: 'ssh-rsa qwerty'
swap: 768 swap: 768
wait: true wait: true
wait_timeout: 600 wait_timeout: 600
state: present state: present
alert_bwquota_enabled: true alert_bwquota_enabled: true
alert_bwquota_threshold: 80 alert_bwquota_threshold: 80
alert_bwin_enabled: true alert_bwin_enabled: true
alert_bwin_threshold: 10 alert_bwin_threshold: 10
alert_cpu_enabled: true alert_cpu_enabled: true
alert_cpu_threshold: 210 alert_cpu_threshold: 210
alert_bwout_enabled: true alert_bwout_enabled: true
alert_bwout_threshold: 10 alert_bwout_threshold: 10
alert_diskio_enabled: true alert_diskio_enabled: true
alert_diskio_threshold: 10000 alert_diskio_threshold: 10000
backupweeklyday: 1 backupweeklyday: 1
backupwindow: 2 backupwindow: 2
displaygroup: 'test' displaygroup: 'test'
additional_disks: additional_disks:
- {Label: 'disk1', Size: 2500, Type: 'raw'} - {Label: 'disk1', Size: 2500, Type: 'raw'}
- {Label: 'newdisk', Size: 2000} - {Label: 'newdisk', Size: 2000}
watchdog: true watchdog: true
delegate_to: localhost delegate_to: localhost
register: linode_creation register: linode_creation
- name: Ensure a running server (create if missing) - name: Ensure a running server (create if missing)
community.general.linode: community.general.linode:
api_key: 'longStringFromLinodeApi' api_key: 'longStringFromLinodeApi'
name: linode-test1 name: linode-test1
plan: 1 plan: 1
datacenter: 2 datacenter: 2
distribution: 99 distribution: 99
password: 'superSecureRootPassword' password: 'superSecureRootPassword'
ssh_pub_key: 'ssh-rsa qwerty' ssh_pub_key: 'ssh-rsa qwerty'
swap: 768 swap: 768
wait: true wait: true
wait_timeout: 600 wait_timeout: 600
state: present state: present
delegate_to: localhost delegate_to: localhost
register: linode_creation register: linode_creation
- name: Delete a server - name: Delete a server
community.general.linode: community.general.linode:
api_key: 'longStringFromLinodeApi' api_key: 'longStringFromLinodeApi'
name: linode-test1 name: linode-test1
linode_id: "{{ linode_creation.instance.id }}" linode_id: "{{ linode_creation.instance.id }}"
state: absent state: absent
delegate_to: localhost delegate_to: localhost
- name: Stop a server - name: Stop a server
community.general.linode: community.general.linode:
api_key: 'longStringFromLinodeApi' api_key: 'longStringFromLinodeApi'
name: linode-test1 name: linode-test1
linode_id: "{{ linode_creation.instance.id }}" linode_id: "{{ linode_creation.instance.id }}"
state: stopped state: stopped
delegate_to: localhost delegate_to: localhost
- name: Reboot a server - name: Reboot a server
community.general.linode: community.general.linode:
api_key: 'longStringFromLinodeApi' api_key: 'longStringFromLinodeApi'
name: linode-test1 name: linode-test1
linode_id: "{{ linode_creation.instance.id }}" linode_id: "{{ linode_creation.instance.id }}"
state: restarted state: restarted
delegate_to: localhost delegate_to: localhost
''' """
import time import time
import traceback import traceback

66
plugins/modules/linode_v4.py
View File

@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: linode_v4 module: linode_v4
short_description: Manage instances on the Linode cloud short_description: Manage instances on the Linode cloud
description: Manage instances on the Linode cloud. description: Manage instances on the Linode cloud.
@ -18,9 +17,8 @@ requirements:
author: author:
- Luke Murphy (@decentral1se) - Luke Murphy (@decentral1se)
notes: notes:
- No Linode resizing is currently implemented. This module will, in time, - No Linode resizing is currently implemented. This module will, in time, replace the current Linode module which uses deprecated API bindings
replace the current Linode module which uses deprecated API bindings on the on the Linode side.
Linode side.
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
@ -31,52 +29,44 @@ attributes:
options: options:
region: region:
description: description:
- The region of the instance. This is a required parameter only when - The region of the instance. This is a required parameter only when creating Linode instances. See U(https://www.linode.com/docs/api/regions/).
creating Linode instances. See
U(https://www.linode.com/docs/api/regions/).
type: str type: str
image: image:
description: description:
- The image of the instance. This is a required parameter only when - The image of the instance. This is a required parameter only when creating Linode instances.
creating Linode instances. See - See U(https://www.linode.com/docs/api/images/).
U(https://www.linode.com/docs/api/images/).
type: str type: str
type: type:
description: description:
- The type of the instance. This is a required parameter only when - The type of the instance. This is a required parameter only when creating Linode instances.
creating Linode instances. See - See U(https://www.linode.com/docs/api/linode-types/).
U(https://www.linode.com/docs/api/linode-types/).
type: str type: str
label: label:
description: description:
- The instance label. This label is used as the main determiner for - The instance label. This label is used as the main determiner for idempotence for the module and is therefore mandatory.
idempotence for the module and is therefore mandatory.
type: str type: str
required: true required: true
group: group:
description: description:
- The group that the instance should be marked under. Please note, that - The group that the instance should be marked under. Please note, that group labelling is deprecated but still supported. The encouraged
group labelling is deprecated but still supported. The encouraged method for marking instances is to use tags.
method for marking instances is to use tags.
type: str type: str
private_ip: private_ip:
description: description:
- If V(true), the created Linode will have private networking enabled and - If V(true), the created Linode will have private networking enabled and assigned a private IPv4 address.
assigned a private IPv4 address.
type: bool type: bool
default: false default: false
version_added: 3.0.0 version_added: 3.0.0
tags: tags:
description: description:
- The tags that the instance should be marked under. See - The tags that the instance should be marked under.
U(https://www.linode.com/docs/api/tags/). - See U(https://www.linode.com/docs/api/tags/).
type: list type: list
elements: str elements: str
root_pass: root_pass:
description: description:
- The password for the root user. If not specified, one will be - The password for the root user. If not specified, one will be generated. This generated password will be available in the task success
generated. This generated password will be available in the task JSON.
success JSON.
type: str type: str
authorized_keys: authorized_keys:
description: description:
@ -88,33 +78,31 @@ options:
- The desired instance state. - The desired instance state.
type: str type: str
choices: choices:
- present - present
- absent - absent
required: true required: true
access_token: access_token:
description: description:
- The Linode API v4 access token. It may also be specified by exposing - The Linode API v4 access token. It may also be specified by exposing the E(LINODE_ACCESS_TOKEN) environment variable.
the E(LINODE_ACCESS_TOKEN) environment variable. See - See U(https://www.linode.com/docs/api#access-and-authentication).
U(https://www.linode.com/docs/api#access-and-authentication).
required: true required: true
type: str type: str
stackscript_id: stackscript_id:
description: description:
- The numeric ID of the StackScript to use when creating the instance. - The numeric ID of the StackScript to use when creating the instance.
See U(https://www.linode.com/docs/api/stackscripts/). - See U(https://www.linode.com/docs/api/stackscripts/).
type: int type: int
version_added: 1.3.0 version_added: 1.3.0
stackscript_data: stackscript_data:
description: description:
- An object containing arguments to any User Defined Fields present in - An object containing arguments to any User Defined Fields present in the StackScript used when creating the instance. Only valid when
the StackScript used when creating the instance. a O(stackscript_id) is provided.
Only valid when a stackscript_id is provided. - See U(https://www.linode.com/docs/api/stackscripts/).
See U(https://www.linode.com/docs/api/stackscripts/).
type: dict type: dict
version_added: 1.3.0 version_added: 1.3.0
''' """
EXAMPLES = """ EXAMPLES = r"""
- name: Create a new Linode. - name: Create a new Linode.
community.general.linode_v4: community.general.linode_v4:
label: new-linode label: new-linode
@ -135,7 +123,7 @@ EXAMPLES = """
state: absent state: absent
""" """
RETURN = """ RETURN = r"""
instance: instance:
description: The instance description in JSON serialized form. description: The instance description in JSON serialized form.
returned: Always. returned: Always.

34
plugins/modules/listen_ports_facts.py
View File

@ -8,21 +8,19 @@
from __future__ import (absolute_import, division, print_function) from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r''' DOCUMENTATION = r"""
---
module: listen_ports_facts module: listen_ports_facts
author: author:
- Nathan Davison (@ndavison) - Nathan Davison (@ndavison)
description: description:
- Gather facts on processes listening on TCP and UDP ports using the C(netstat) or C(ss) commands. - Gather facts on processes listening on TCP and UDP ports using the C(netstat) or C(ss) commands.
- This module currently supports Linux only. - This module currently supports Linux only.
requirements: requirements:
- netstat or ss - netstat or ss
short_description: Gather facts on processes listening on TCP and UDP ports short_description: Gather facts on processes listening on TCP and UDP ports
notes: notes:
- | - C(ss) returns all processes for each listen address and port.
C(ss) returns all processes for each listen address and port. - This plugin will return each of them, so multiple entries for the same listen address and port are likely in results.
This plugin will return each of them, so multiple entries for the same listen address and port are likely in results.
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
- community.general.attributes.facts - community.general.attributes.facts
@ -31,7 +29,7 @@ options:
command: command:
description: description:
- Override which command to use for fetching listen ports. - Override which command to use for fetching listen ports.
- 'By default module will use first found supported command on the system (in alphanumerical order).' - By default module will use first found supported command on the system (in alphanumerical order).
type: str type: str
choices: choices:
- netstat - netstat
@ -39,15 +37,15 @@ options:
version_added: 4.1.0 version_added: 4.1.0
include_non_listening: include_non_listening:
description: description:
- Show both listening and non-listening sockets (for TCP this means established connections). - Show both listening and non-listening sockets (for TCP this means established connections).
- Adds the return values RV(ansible_facts.tcp_listen[].state), RV(ansible_facts.udp_listen[].state), - Adds the return values RV(ansible_facts.tcp_listen[].state), RV(ansible_facts.udp_listen[].state), RV(ansible_facts.tcp_listen[].foreign_address),
RV(ansible_facts.tcp_listen[].foreign_address), and RV(ansible_facts.udp_listen[].foreign_address) to the returned facts. and RV(ansible_facts.udp_listen[].foreign_address) to the returned facts.
type: bool type: bool
default: false default: false
version_added: 5.4.0 version_added: 5.4.0
''' """
EXAMPLES = r''' EXAMPLES = r"""
- name: Gather facts on listening ports - name: Gather facts on listening ports
community.general.listen_ports_facts: community.general.listen_ports_facts:
@ -77,11 +75,11 @@ EXAMPLES = r'''
community.general.listen_ports_facts: community.general.listen_ports_facts:
command: 'netstat' command: 'netstat'
include_non_listening: true include_non_listening: true
''' """
RETURN = r''' RETURN = r"""
ansible_facts: ansible_facts:
description: Dictionary containing details of TCP and UDP ports with listening servers description: Dictionary containing details of TCP and UDP ports with listening servers.
returned: always returned: always
type: complex type: complex
contains: contains:
@ -189,7 +187,7 @@ ansible_facts:
returned: always returned: always
type: str type: str
sample: "root" sample: "root"
''' """
import re import re
import platform import platform

28
plugins/modules/lldp.py
View File

@ -9,13 +9,12 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: lldp module: lldp
requirements: [ lldpctl ] requirements: [lldpctl]
short_description: Get details reported by lldp short_description: Get details reported by LLDP
description: description:
- Reads data out of lldpctl - Reads data out of C(lldpctl).
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
@ -26,25 +25,24 @@ attributes:
options: {} options: {}
author: "Andy Hill (@andyhky)" author: "Andy Hill (@andyhky)"
notes: notes:
- Requires lldpd running and lldp enabled on switches - Requires C(lldpd) running and LLDP enabled on switches.
''' """
EXAMPLES = ''' EXAMPLES = r"""
# Retrieve switch/port information # Retrieve switch/port information
- name: Gather information from lldp - name: Gather information from LLDP
community.general.lldp: community.general.lldp:
- name: Print each switch/port - name: Print each switch/port
ansible.builtin.debug: ansible.builtin.debug:
msg: "{{ lldp[item]['chassis']['name'] }} / {{ lldp[item]['port']['ifname'] }}" msg: "{{ lldp[item]['chassis']['name'] }} / {{ lldp[item]['port']['ifname'] }}"
with_items: "{{ lldp.keys() }}" with_items: "{{ lldp.keys() }}"
# TASK: [Print each switch/port] *********************************************************** # TASK: [Print each switch/port] ***********************************************************
# ok: [10.13.0.22] => (item=eth2) => {"item": "eth2", "msg": "switch1.example.com / Gi0/24"} # ok: [10.13.0.22] => (item=eth2) => {"item": "eth2", "msg": "switch1.example.com / Gi0/24"}
# ok: [10.13.0.22] => (item=eth1) => {"item": "eth1", "msg": "switch2.example.com / Gi0/3"} # ok: [10.13.0.22] => (item=eth1) => {"item": "eth1", "msg": "switch2.example.com / Gi0/3"}
# ok: [10.13.0.22] => (item=eth0) => {"item": "eth0", "msg": "switch3.example.com / Gi0/3"} # ok: [10.13.0.22] => (item=eth0) => {"item": "eth0", "msg": "switch3.example.com / Gi0/3"}
"""
'''
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule

51
plugins/modules/locale_gen.py
View File

@ -8,40 +8,39 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: locale_gen module: locale_gen
short_description: Creates or removes locales short_description: Creates or removes locales
description: description:
- Manages locales by editing /etc/locale.gen and invoking locale-gen. - Manages locales by editing /etc/locale.gen and invoking C(locale-gen).
author: author:
- Augustus Kling (@AugustusKling) - Augustus Kling (@AugustusKling)
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: full support: full
diff_mode: diff_mode:
support: none support: none
options: options:
name: name:
type: list type: list
elements: str elements: str
description: description:
- Name and encoding of the locales, such as V(en_GB.UTF-8). - Name and encoding of the locales, such as V(en_GB.UTF-8).
- Before community.general 9.3.0, this was a string. Using a string still works. - Before community.general 9.3.0, this was a string. Using a string still works.
required: true required: true
state: state:
type: str type: str
description: description:
- Whether the locale shall be present. - Whether the locale shall be present.
choices: [ absent, present ] choices: [absent, present]
default: present default: present
notes: notes:
- This module does not support RHEL-based systems. - This module does not support RHEL-based systems.
''' """
EXAMPLES = ''' EXAMPLES = r"""
- name: Ensure a locale exists - name: Ensure a locale exists
community.general.locale_gen: community.general.locale_gen:
name: de_CH.UTF-8 name: de_CH.UTF-8
@ -53,7 +52,7 @@ EXAMPLES = '''
- en_GB.UTF-8 - en_GB.UTF-8
- nl_NL.UTF-8 - nl_NL.UTF-8
state: present state: present
''' """
import os import os
import re import re

72
plugins/modules/logentries.py
View File

@ -9,49 +9,49 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: logentries module: logentries
author: "Ivan Vanderbyl (@ivanvanderbyl)" author: "Ivan Vanderbyl (@ivanvanderbyl)"
short_description: Module for tracking logs via logentries.com short_description: Module for tracking logs using U(logentries.com)
description: description:
- Sends logs to LogEntries in realtime - Sends logs to LogEntries in realtime.
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: full support: full
diff_mode: diff_mode:
support: none support: none
options: options:
path: path:
type: str type: str
description: description:
- path to a log file - Path to a log file.
required: true required: true
state: state:
type: str type: str
description: description:
- following state of the log - Following state of the log.
choices: [ 'present', 'absent', 'followed', 'unfollowed' ] choices: ['present', 'absent', 'followed', 'unfollowed']
required: false required: false
default: present default: present
name: name:
type: str type: str
description: description:
- name of the log - Name of the log.
required: false required: false
logtype: logtype:
type: str type: str
description: description:
- type of the log - Type of the log.
required: false required: false
aliases: [type] aliases: [type]
notes: notes:
- Requires the LogEntries agent which can be installed following the instructions at logentries.com - Requires the LogEntries agent which can be installed following the instructions at U(logentries.com).
''' """
EXAMPLES = '''
EXAMPLES = r"""
- name: Track nginx logs - name: Track nginx logs
community.general.logentries: community.general.logentries:
path: /var/log/nginx/access.log path: /var/log/nginx/access.log
@ -62,7 +62,7 @@ EXAMPLES = '''
community.general.logentries: community.general.logentries:
path: /var/log/nginx/error.log path: /var/log/nginx/error.log
state: absent state: absent
''' """
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule

21
plugins/modules/logentries_msg.py
View File

@ -9,12 +9,11 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: logentries_msg module: logentries_msg
short_description: Send a message to logentries short_description: Send a message to logentries
description: description:
- Send a message to logentries - Send a message to logentries.
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
@ -36,24 +35,24 @@ options:
api: api:
type: str type: str
description: description:
- API endpoint - API endpoint.
default: data.logentries.com default: data.logentries.com
port: port:
type: int type: int
description: description:
- API endpoint port - API endpoint port.
default: 80 default: 80
author: "Jimmy Tang (@jcftang) <jimmy_tang@rapid7.com>" author: "Jimmy Tang (@jcftang) <jimmy_tang@rapid7.com>"
''' """
RETURN = '''# ''' RETURN = """# """
EXAMPLES = ''' EXAMPLES = r"""
- name: Send a message to logentries - name: Send a message to logentries
community.general.logentries_msg: community.general.logentries_msg:
token=00000000-0000-0000-0000-000000000000 token: 00000000-0000-0000-0000-000000000000
msg="{{ ansible_hostname }}" msg: "{{ ansible_hostname }}"
''' """
import socket import socket

78
plugins/modules/logstash_plugin.py
View File

@ -8,53 +8,51 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: logstash_plugin module: logstash_plugin
short_description: Manage Logstash plugins short_description: Manage Logstash plugins
description: description:
- Manages Logstash plugins. - Manages Logstash plugins.
author: Loic Blot (@nerzhul) author: Loic Blot (@nerzhul)
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: full support: full
diff_mode: diff_mode:
support: none support: none
options: options:
name: name:
type: str type: str
description: description:
- Install plugin with that name. - Install plugin with that name.
required: true required: true
state: state:
type: str type: str
description: description:
- Apply plugin state. - Apply plugin state.
choices: ["present", "absent"] choices: ["present", "absent"]
default: present default: present
plugin_bin: plugin_bin:
type: path type: path
description: description:
- Specify logstash-plugin to use for plugin management. - Specify logstash-plugin to use for plugin management.
default: /usr/share/logstash/bin/logstash-plugin default: /usr/share/logstash/bin/logstash-plugin
proxy_host: proxy_host:
type: str type: str
description: description:
- Proxy host to use during plugin installation. - Proxy host to use during plugin installation.
proxy_port: proxy_port:
type: str type: str
description: description:
- Proxy port to use during plugin installation. - Proxy port to use during plugin installation.
version: version:
type: str type: str
description: description:
- Specify plugin Version of the plugin to install. - Specify plugin Version of the plugin to install. If plugin exists with previous version, it will NOT be updated.
If plugin exists with previous version, it will NOT be updated. """
'''
EXAMPLES = ''' EXAMPLES = r"""
- name: Install Logstash beats input plugin - name: Install Logstash beats input plugin
community.general.logstash_plugin: community.general.logstash_plugin:
state: present state: present
@ -77,7 +75,7 @@ EXAMPLES = '''
name: logstash-input-beats name: logstash-input-beats
environment: environment:
LS_JAVA_OPTS: "-Xms256m -Xmx256m" LS_JAVA_OPTS: "-Xms256m -Xmx256m"
''' """
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule

59
plugins/modules/lvg.py
View File

@ -9,10 +9,9 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r''' DOCUMENTATION = r"""
---
author: author:
- Alexander Bulimov (@abulimov) - Alexander Bulimov (@abulimov)
module: lvg module: lvg
short_description: Configure LVM volume groups short_description: Configure LVM volume groups
description: description:
@ -27,78 +26,76 @@ attributes:
options: options:
vg: vg:
description: description:
- The name of the volume group. - The name of the volume group.
type: str type: str
required: true required: true
pvs: pvs:
description: description:
- List of comma-separated devices to use as physical devices in this volume group. - List of comma-separated devices to use as physical devices in this volume group.
- Required when creating or resizing volume group. - Required when creating or resizing volume group.
- The module will take care of running pvcreate if needed. - The module will take care of running pvcreate if needed.
type: list type: list
elements: str elements: str
pesize: pesize:
description: description:
- "The size of the physical extent. O(pesize) must be a power of 2 of at least 1 sector - The size of the physical extent. O(pesize) must be a power of 2 of at least 1 sector (where the sector size is the largest sector size
(where the sector size is the largest sector size of the PVs currently used in the VG), of the PVs currently used in the VG), or at least 128KiB.
or at least 128KiB." - O(pesize) can be optionally suffixed by a UNIT (k/K/m/M/g/G), default unit is megabyte.
- O(pesize) can be optionally suffixed by a UNIT (k/K/m/M/g/G), default unit is megabyte.
type: str type: str
default: "4" default: "4"
pv_options: pv_options:
description: description:
- Additional options to pass to C(pvcreate) when creating the volume group. - Additional options to pass to C(pvcreate) when creating the volume group.
type: str type: str
default: '' default: ''
pvresize: pvresize:
description: description:
- If V(true), resize the physical volume to the maximum available size. - If V(true), resize the physical volume to the maximum available size.
type: bool type: bool
default: false default: false
version_added: '0.2.0' version_added: '0.2.0'
vg_options: vg_options:
description: description:
- Additional options to pass to C(vgcreate) when creating the volume group. - Additional options to pass to C(vgcreate) when creating the volume group.
type: str type: str
default: '' default: ''
state: state:
description: description:
- Control if the volume group exists and it's state. - Control if the volume group exists and it's state.
- The states V(active) and V(inactive) implies V(present) state. Added in 7.1.0 - The states V(active) and V(inactive) implies V(present) state. Added in 7.1.0.
- "If V(active) or V(inactive), the module manages the VG's logical volumes current state. - If V(active) or V(inactive), the module manages the VG's logical volumes current state. The module also handles the VG's autoactivation
The module also handles the VG's autoactivation state if supported state if supported unless when creating a volume group and the autoactivation option specified in O(vg_options).
unless when creating a volume group and the autoactivation option specified in O(vg_options)."
type: str type: str
choices: [ absent, present, active, inactive ] choices: [absent, present, active, inactive]
default: present default: present
force: force:
description: description:
- If V(true), allows to remove volume group with logical volumes. - If V(true), allows to remove volume group with logical volumes.
type: bool type: bool
default: false default: false
reset_vg_uuid: reset_vg_uuid:
description: description:
- Whether the volume group's UUID is regenerated. - Whether the volume group's UUID is regenerated.
- This is B(not idempotent). Specifying this parameter always results in a change. - This is B(not idempotent). Specifying this parameter always results in a change.
type: bool type: bool
default: false default: false
version_added: 7.1.0 version_added: 7.1.0
reset_pv_uuid: reset_pv_uuid:
description: description:
- Whether the volume group's physical volumes' UUIDs are regenerated. - Whether the volume group's physical volumes' UUIDs are regenerated.
- This is B(not idempotent). Specifying this parameter always results in a change. - This is B(not idempotent). Specifying this parameter always results in a change.
type: bool type: bool
default: false default: false
version_added: 7.1.0 version_added: 7.1.0
seealso: seealso:
- module: community.general.filesystem - module: community.general.filesystem
- module: community.general.lvol - module: community.general.lvol
- module: community.general.parted - module: community.general.parted
notes: notes:
- This module does not modify PE size for already present volume group. - This module does not modify PE size for already present volume group.
''' """
EXAMPLES = r''' EXAMPLES = r"""
- name: Create a volume group on top of /dev/sda1 with physical extent size = 32MB - name: Create a volume group on top of /dev/sda1 with physical extent size = 32MB
community.general.lvg: community.general.lvg:
vg: vg.services vg: vg.services
@ -154,7 +151,7 @@ EXAMPLES = r'''
pvs: /dev/sdb1,/dev/sdc5 pvs: /dev/sdb1,/dev/sdc5
reset_vg_uuid: true reset_vg_uuid: true
reset_pv_uuid: true reset_pv_uuid: true
''' """
import itertools import itertools
import os import os

19
plugins/modules/lvg_rename.py
View File

@ -8,8 +8,7 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r''' DOCUMENTATION = r"""
---
author: author:
- Laszlo Szomor (@lszomor) - Laszlo Szomor (@lszomor)
module: lvg_rename module: lvg_rename
@ -27,23 +26,23 @@ version_added: 7.1.0
options: options:
vg: vg:
description: description:
- The name or UUID of the source VG. - The name or UUID of the source VG.
- See V(vgrename(8\)) for valid values. - See V(vgrename(8\)) for valid values.
type: str type: str
required: true required: true
vg_new: vg_new:
description: description:
- The new name of the VG. - The new name of the VG.
- See V(lvm(8\)) for valid names. - See V(lvm(8\)) for valid names.
type: str type: str
required: true required: true
seealso: seealso:
- module: community.general.lvg - module: community.general.lvg
notes: notes:
- This module does not modify VG renaming-related configurations like C(fstab) entries or boot parameters. - This module does not modify VG renaming-related configurations like C(fstab) entries or boot parameters.
''' """
EXAMPLES = r''' EXAMPLES = r"""
- name: Rename a VG by name - name: Rename a VG by name
community.general.lvg_rename: community.general.lvg_rename:
vg: vg_orig_name vg: vg_orig_name
@ -53,7 +52,7 @@ EXAMPLES = r'''
community.general.lvg_rename: community.general.lvg_rename:
vg_uuid: SNgd0Q-rPYa-dPB8-U1g6-4WZI-qHID-N7y9Vj vg_uuid: SNgd0Q-rPYa-dPB8-U1g6-4WZI-qHID-N7y9Vj
vg_new: vg_new_name vg_new: vg_new_name
''' """
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule

61
plugins/modules/lvol.py
View File

@ -8,13 +8,12 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
author: author:
- Jeroen Hoekx (@jhoekx) - Jeroen Hoekx (@jhoekx)
- Alexander Bulimov (@abulimov) - Alexander Bulimov (@abulimov)
- Raoul Baudach (@unkaputtbar112) - Raoul Baudach (@unkaputtbar112)
- Ziga Kern (@zigaSRC) - Ziga Kern (@zigaSRC)
module: lvol module: lvol
short_description: Configure LVM logical volumes short_description: Configure LVM logical volumes
description: description:
@ -31,75 +30,69 @@ options:
type: str type: str
required: true required: true
description: description:
- The volume group this logical volume is part of. - The volume group this logical volume is part of.
lv: lv:
type: str type: str
description: description:
- The name of the logical volume. - The name of the logical volume.
size: size:
type: str type: str
description: description:
- The size of the logical volume, according to lvcreate(8) --size, by - The size of the logical volume, according to lvcreate(8) C(--size), by default in megabytes or optionally with one of [bBsSkKmMgGtTpPeE]
default in megabytes or optionally with one of [bBsSkKmMgGtTpPeE] units; or units; or according to lvcreate(8) --extents as a percentage of [VG|PVS|FREE|ORIGIN]; Float values must begin with a digit.
according to lvcreate(8) --extents as a percentage of [VG|PVS|FREE|ORIGIN]; - When resizing, apart from specifying an absolute size you may, according to lvextend(8)|lvreduce(8) C(--size), specify the amount to extend
Float values must begin with a digit. the logical volume with the prefix V(+) or the amount to reduce the logical volume by with prefix V(-).
- When resizing, apart from specifying an absolute size you may, according to - Resizing using V(+) or V(-) was not supported prior to community.general 3.0.0.
lvextend(8)|lvreduce(8) C(--size), specify the amount to extend the logical volume with - Please note that when using V(+), V(-), or percentage of FREE, the module is B(not idempotent).
the prefix V(+) or the amount to reduce the logical volume by with prefix V(-).
- Resizing using V(+) or V(-) was not supported prior to community.general 3.0.0.
- Please note that when using V(+), V(-), or percentage of FREE, the module is B(not idempotent).
state: state:
type: str type: str
description: description:
- Control if the logical volume exists. If V(present) and the - Control if the logical volume exists. If V(present) and the volume does not already exist then the O(size) option is required.
volume does not already exist then the O(size) option is required. choices: [absent, present]
choices: [ absent, present ]
default: present default: present
active: active:
description: description:
- Whether the volume is active and visible to the host. - Whether the volume is active and visible to the host.
type: bool type: bool
default: true default: true
force: force:
description: description:
- Shrink or remove operations of volumes requires this switch. Ensures that - Shrink or remove operations of volumes requires this switch. Ensures that that filesystems get never corrupted/destroyed by mistake.
that filesystems get never corrupted/destroyed by mistake.
type: bool type: bool
default: false default: false
opts: opts:
type: str type: str
description: description:
- Free-form options to be passed to the lvcreate command. - Free-form options to be passed to the lvcreate command.
snapshot: snapshot:
type: str type: str
description: description:
- The name of a snapshot volume to be configured. When creating a snapshot volume, the O(lv) parameter specifies the origin volume. - The name of a snapshot volume to be configured. When creating a snapshot volume, the O(lv) parameter specifies the origin volume.
pvs: pvs:
type: list type: list
elements: str elements: str
description: description:
- List of physical volumes (for example V(/dev/sda, /dev/sdb)). - List of physical volumes (for example V(/dev/sda, /dev/sdb)).
thinpool: thinpool:
type: str type: str
description: description:
- The thin pool volume name. When you want to create a thin provisioned volume, specify a thin pool volume name. - The thin pool volume name. When you want to create a thin provisioned volume, specify a thin pool volume name.
shrink: shrink:
description: description:
- Shrink if current size is higher than size requested. - Shrink if current size is higher than size requested.
type: bool type: bool
default: true default: true
resizefs: resizefs:
description: description:
- Resize the underlying filesystem together with the logical volume. - Resize the underlying filesystem together with the logical volume.
- Supported for C(ext2), C(ext3), C(ext4), C(reiserfs) and C(XFS) filesystems. - Supported for C(ext2), C(ext3), C(ext4), C(reiserfs) and C(XFS) filesystems. Attempts to resize other filesystem types will fail.
Attempts to resize other filesystem types will fail.
type: bool type: bool
default: false default: false
notes: notes:
- You must specify lv (when managing the state of logical volumes) or thinpool (when managing a thin provisioned volume). - You must specify lv (when managing the state of logical volumes) or thinpool (when managing a thin provisioned volume).
''' """
EXAMPLES = ''' EXAMPLES = r"""
- name: Create a logical volume of 512m - name: Create a logical volume of 512m
community.general.lvol: community.general.lvol:
vg: firefly vg: firefly
@ -233,7 +226,7 @@ EXAMPLES = '''
lv: test lv: test
thinpool: testpool thinpool: testpool
size: 128g size: 128g
''' """
import re import re
import shlex import shlex

411
plugins/modules/lxc_container.py
View File

@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = r''' DOCUMENTATION = r"""
---
module: lxc_container module: lxc_container
short_description: Manage LXC Containers short_description: Manage LXC Containers
description: description:
@ -19,183 +18,171 @@ author: "Kevin Carter (@cloudnull)"
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: none support: none
diff_mode: diff_mode:
support: none support: none
options: options:
name: name:
description: description:
- Name of a container. - Name of a container.
type: str type: str
required: true required: true
backing_store: backing_store:
choices: choices:
- dir - dir
- lvm - lvm
- loop - loop
- btrfs - btrfs
- overlayfs - overlayfs
- zfs - zfs
description: description:
- Backend storage type for the container. - Backend storage type for the container.
type: str type: str
default: dir default: dir
template: template:
description: description:
- Name of the template to use within an LXC create. - Name of the template to use within an LXC create.
type: str type: str
default: ubuntu default: ubuntu
template_options: template_options:
description: description:
- Template options when building the container. - Template options when building the container.
type: str type: str
config: config:
description: description:
- Path to the LXC configuration file. - Path to the LXC configuration file.
type: path type: path
lv_name: lv_name:
description: description:
- Name of the logical volume, defaults to the container name. - Name of the logical volume, defaults to the container name.
- If not specified, it defaults to C($CONTAINER_NAME). - If not specified, it defaults to E(CONTAINER_NAME).
type: str type: str
vg_name: vg_name:
description: description:
- If backend store is lvm, specify the name of the volume group. - If backend store is lvm, specify the name of the volume group.
type: str type: str
default: lxc default: lxc
thinpool: thinpool:
description: description:
- Use LVM thin pool called TP. - Use LVM thin pool called TP.
type: str type: str
fs_type: fs_type:
description: description:
- Create fstype TYPE. - Create fstype TYPE.
type: str type: str
default: ext4 default: ext4
fs_size: fs_size:
description: description:
- File system Size. - File system Size.
type: str type: str
default: 5G default: 5G
directory: directory:
description: description:
- Place rootfs directory under DIR. - Place rootfs directory under DIR.
type: path type: path
zfs_root: zfs_root:
description: description:
- Create zfs under given zfsroot. - Create zfs under given zfsroot.
type: str type: str
container_command: container_command:
description: description:
- Run a command within a container. - Run a command within a container.
type: str type: str
lxc_path: lxc_path:
description: description:
- Place container under E(PATH). - Place container under E(PATH).
type: path type: path
container_log: container_log:
description: description:
- Enable a container log for host actions to the container. - Enable a container log for host actions to the container.
type: bool type: bool
default: false default: false
container_log_level: container_log_level:
choices: choices:
- Info - Info
- info - info
- INFO - INFO
- Error - Error
- error - error
- ERROR - ERROR
- Debug - Debug
- debug - debug
- DEBUG - DEBUG
description: description:
- Set the log level for a container where O(container_log) was set. - Set the log level for a container where O(container_log) was set.
type: str type: str
required: false required: false
default: INFO default: INFO
clone_name: clone_name:
description: description:
- Name of the new cloned server. - Name of the new cloned server.
- This is only used when state is clone. - This is only used when state is clone.
type: str type: str
clone_snapshot: clone_snapshot:
description: description:
- Create a snapshot a container when cloning. - Create a snapshot a container when cloning.
- This is not supported by all container storage backends. - This is not supported by all container storage backends.
- Enabling this may fail if the backing store does not support snapshots. - Enabling this may fail if the backing store does not support snapshots.
type: bool type: bool
default: false default: false
archive: archive:
description: description:
- Create an archive of a container. - Create an archive of a container.
- This will create a tarball of the running container. - This will create a tarball of the running container.
type: bool type: bool
default: false default: false
archive_path: archive_path:
description: description:
- Path the save the archived container. - Path the save the archived container.
- If the path does not exist the archive method will attempt to create it. - If the path does not exist the archive method will attempt to create it.
type: path type: path
archive_compression: archive_compression:
choices: choices:
- gzip - gzip
- bzip2 - bzip2
- none - none
description: description:
- Type of compression to use when creating an archive of a running - Type of compression to use when creating an archive of a running container.
container. type: str
type: str default: gzip
default: gzip state:
state: choices:
choices: - started
- started - stopped
- stopped - restarted
- restarted - absent
- absent - frozen
- frozen - clone
- clone description:
description: - Define the state of a container.
- Define the state of a container. - If you clone a container using O(clone_name) the newly cloned container created in a stopped state.
- If you clone a container using O(clone_name) the newly cloned - The running container will be stopped while the clone operation is happening and upon completion of the clone the original container state
container created in a stopped state. will be restored.
- The running container will be stopped while the clone operation is type: str
happening and upon completion of the clone the original container default: started
state will be restored. container_config:
type: str description:
default: started - A list of C(key=value) options to use when configuring a container.
container_config: type: list
description: elements: str
- A list of C(key=value) options to use when configuring a container.
type: list
elements: str
requirements: requirements:
- 'lxc >= 2.0 # OS package' - 'lxc >= 2.0 # OS package'
- 'python3 >= 3.5 # OS Package' - 'python3 >= 3.5 # OS Package'
- 'python3-lxc # OS Package' - 'python3-lxc # OS Package'
notes: notes:
- Containers must have a unique name. If you attempt to create a container - Containers must have a unique name. If you attempt to create a container with a name that already exists in the users namespace the module
with a name that already exists in the users namespace the module will will simply return as "unchanged".
simply return as "unchanged". - The O(container_command) can be used with any state except V(absent). If used with state V(stopped) the container will be V(started), the
- The O(container_command) can be used with any state except V(absent). If command executed, and then the container V(stopped) again. Likewise if O(state=stopped) and the container does not exist it will be first
used with state V(stopped) the container will be V(started), the command created, V(started), the command executed, and then V(stopped). If you use a C(|) in the variable you can use common script formatting within
executed, and then the container V(stopped) again. Likewise if O(state=stopped) the variable itself. The O(container_command) option will always execute as C(bash). When using O(container_command), a log file is created in
and the container does not exist it will be first created, the C(/tmp/) directory which contains both C(stdout) and C(stderr) of any command executed.
V(started), the command executed, and then V(stopped). If you use a "|" - If O(archive=true) the system will attempt to create a compressed tarball of the running container. The O(archive) option supports LVM backed
in the variable you can use common script formatting within the variable containers and will create a snapshot of the running container when creating the archive.
itself. The O(container_command) option will always execute as BASH. - If your distro does not have a package for C(python3-lxc), which is a requirement for this module, it can be installed from source at
When using O(container_command), a log file is created in the C(/tmp/) directory U(https://github.com/lxc/python3-lxc) or installed using C(pip install lxc).
which contains both C(stdout) and C(stderr) of any command executed. """
- If O(archive=true) the system will attempt to create a compressed
tarball of the running container. The O(archive) option supports LVM backed
containers and will create a snapshot of the running container when
creating the archive.
- If your distro does not have a package for C(python3-lxc), which is a
requirement for this module, it can be installed from source at
U(https://github.com/lxc/python3-lxc) or installed via pip using the
package name C(lxc).
'''
EXAMPLES = r""" EXAMPLES = r"""
- name: Create a started container - name: Create a started container
@ -382,45 +369,45 @@ EXAMPLES = r"""
RETURN = r""" RETURN = r"""
lxc_container: lxc_container:
description: container information description: Container information.
returned: success returned: success
type: complex type: complex
contains: contains:
name: name:
description: name of the lxc container description: Name of the lxc container.
returned: success returned: success
type: str type: str
sample: test_host sample: test_host
init_pid: init_pid:
description: pid of the lxc init process description: Pid of the lxc init process.
returned: success returned: success
type: int type: int
sample: 19786 sample: 19786
interfaces: interfaces:
description: list of the container's network interfaces description: List of the container's network interfaces.
returned: success returned: success
type: list type: list
sample: [ "eth0", "lo" ] sample: ["eth0", "lo"]
ips: ips:
description: list of ips description: List of ips.
returned: success returned: success
type: list type: list
sample: [ "10.0.3.3" ] sample: ["10.0.3.3"]
state: state:
description: resulting state of the container description: Resulting state of the container.
returned: success returned: success
type: str type: str
sample: "running" sample: "running"
archive: archive:
description: resulting state of the container description: Resulting state of the container.
returned: success, when archive is true returned: success, when archive is true
type: str type: str
sample: "/tmp/test-container-config.tar" sample: "/tmp/test-container-config.tar"
clone: clone:
description: if the container was cloned description: If the container was cloned.
returned: success, when clone_name is specified returned: success, when clone_name is specified
type: bool type: bool
sample: true sample: true
""" """
import os import os

59
plugins/modules/lxca_cmms.py
View File

@ -8,16 +8,14 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
author: author:
- Naval Patel (@navalkp) - Naval Patel (@navalkp)
- Prashant Bhosale (@prabhosa) - Prashant Bhosale (@prabhosa)
module: lxca_cmms module: lxca_cmms
short_description: Custom module for lxca cmms inventory utility short_description: Custom module for lxca cmms inventory utility
description: description:
- This module returns/displays a inventory details of cmms - This module returns/displays a inventory details of cmms.
attributes: attributes:
check_mode: check_mode:
support: none support: none
@ -26,32 +24,28 @@ attributes:
options: options:
uuid: uuid:
description: description: UUID of device, this is string with length greater than 16.
uuid of device, this is string with length greater than 16.
type: str type: str
command_options: command_options:
description: description: Options to filter nodes information.
options to filter nodes information
default: cmms default: cmms
choices: choices:
- cmms - cmms
- cmms_by_uuid - cmms_by_uuid
- cmms_by_chassis_uuid - cmms_by_chassis_uuid
type: str type: str
chassis: chassis:
description: description: UUID of chassis, this is string with length greater than 16.
uuid of chassis, this is string with length greater than 16.
type: str type: str
extends_documentation_fragment: extends_documentation_fragment:
- community.general.lxca_common - community.general.lxca_common
- community.general.attributes - community.general.attributes
"""
''' EXAMPLES = r"""
EXAMPLES = '''
# get all cmms info # get all cmms info
- name: Get nodes data from LXCA - name: Get nodes data from LXCA
community.general.lxca_cmms: community.general.lxca_cmms:
@ -76,28 +70,27 @@ EXAMPLES = '''
auth_url: "https://10.243.15.168" auth_url: "https://10.243.15.168"
chassis: "3C737AA5E31640CE949B10C129A8B01F" chassis: "3C737AA5E31640CE949B10C129A8B01F"
command_options: cmms_by_chassis_uuid command_options: cmms_by_chassis_uuid
"""
''' RETURN = r"""
RETURN = r'''
result: result:
description: cmms detail from lxca description: Cmms detail from lxca.
returned: success returned: success
type: dict type: dict
sample: sample:
cmmList: cmmList:
- machineType: '' - machineType: ''
model: '' model: ''
type: 'CMM' type: 'CMM'
uuid: '118D2C88C8FD11E4947B6EAE8B4BDCDF' uuid: '118D2C88C8FD11E4947B6EAE8B4BDCDF'
# bunch of properties # bunch of properties
- machineType: '' - machineType: ''
model: '' model: ''
type: 'CMM' type: 'CMM'
uuid: '223D2C88C8FD11E4947B6EAE8B4BDCDF' uuid: '223D2C88C8FD11E4947B6EAE8B4BDCDF'
# bunch of properties # bunch of properties
# Multiple cmms details # Multiple cmms details
''' """
import traceback import traceback
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule

63
plugins/modules/lxca_nodes.py
View File

@ -8,16 +8,14 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
author: author:
- Naval Patel (@navalkp) - Naval Patel (@navalkp)
- Prashant Bhosale (@prabhosa) - Prashant Bhosale (@prabhosa)
module: lxca_nodes module: lxca_nodes
short_description: Custom module for lxca nodes inventory utility short_description: Custom module for lxca nodes inventory utility
description: description:
- This module returns/displays a inventory details of nodes - This module returns/displays a inventory details of nodes.
attributes: attributes:
check_mode: check_mode:
support: none support: none
@ -26,34 +24,30 @@ attributes:
options: options:
uuid: uuid:
description: description: UUID of device, this is string with length greater than 16.
uuid of device, this is string with length greater than 16.
type: str type: str
command_options: command_options:
description: description: Options to filter nodes information.
options to filter nodes information
default: nodes default: nodes
choices: choices:
- nodes - nodes
- nodes_by_uuid - nodes_by_uuid
- nodes_by_chassis_uuid - nodes_by_chassis_uuid
- nodes_status_managed - nodes_status_managed
- nodes_status_unmanaged - nodes_status_unmanaged
type: str type: str
chassis: chassis:
description: description: UUID of chassis, this is string with length greater than 16.
uuid of chassis, this is string with length greater than 16.
type: str type: str
extends_documentation_fragment: extends_documentation_fragment:
- community.general.lxca_common - community.general.lxca_common
- community.general.attributes - community.general.attributes
"""
''' EXAMPLES = r"""
EXAMPLES = '''
# get all nodes info # get all nodes info
- name: Get nodes data from LXCA - name: Get nodes data from LXCA
community.general.lxca_nodes: community.general.lxca_nodes:
@ -95,28 +89,27 @@ EXAMPLES = '''
login_password: Password login_password: Password
auth_url: "https://10.243.15.168" auth_url: "https://10.243.15.168"
command_options: nodes_status_unmanaged command_options: nodes_status_unmanaged
"""
''' RETURN = r"""
RETURN = r'''
result: result:
description: nodes detail from lxca description: Nodes detail from lxca.
returned: always returned: always
type: dict type: dict
sample: sample:
nodeList: nodeList:
- machineType: '6241' - machineType: '6241'
model: 'AC1' model: 'AC1'
type: 'Rack-TowerServer' type: 'Rack-TowerServer'
uuid: '118D2C88C8FD11E4947B6EAE8B4BDCDF' uuid: '118D2C88C8FD11E4947B6EAE8B4BDCDF'
# bunch of properties # bunch of properties
- machineType: '8871' - machineType: '8871'
model: 'AC1' model: 'AC1'
type: 'Rack-TowerServer' type: 'Rack-TowerServer'
uuid: '223D2C88C8FD11E4947B6EAE8B4BDCDF' uuid: '223D2C88C8FD11E4947B6EAE8B4BDCDF'
# bunch of properties # bunch of properties
# Multiple nodes details # Multiple nodes details
''' """
import traceback import traceback
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule

370
plugins/modules/lxd_container.py
View File

@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: lxd_container module: lxd_container
short_description: Manage LXD instances short_description: Manage LXD instances
description: description:
@ -19,198 +18,180 @@ author: "Hiroaki Nakamura (@hnakamur)"
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: full support: full
version_added: 6.4.0 version_added: 6.4.0
diff_mode: diff_mode:
support: full support: full
version_added: 6.4.0 version_added: 6.4.0
options: options:
name: name:
description: description:
- Name of an instance. - Name of an instance.
type: str type: str
required: true required: true
project: project:
description: description:
- 'Project of an instance. - Project of an instance.
See U(https://documentation.ubuntu.com/lxd/en/latest/projects/).' - See U(https://documentation.ubuntu.com/lxd/en/latest/projects/).
required: false required: false
type: str type: str
version_added: 4.8.0 version_added: 4.8.0
architecture: architecture:
description: description:
- 'The architecture for the instance (for example V(x86_64) or V(i686)). - The architecture for the instance (for example V(x86_64) or V(i686)).
See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).' - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).
type: str type: str
required: false required: false
config: config:
description: description:
- 'The config for the instance (for example V({"limits.cpu": "2"})). - 'The config for the instance (for example V({"limits.cpu": "2"})).
See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).' - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).'
- If the instance already exists and its "config" values in metadata - If the instance already exists and its "config" values in metadata obtained from the LXD API
obtained from the LXD API U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get) U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get)
are different, then this module tries to apply the configurations are different, then this module tries to apply the configurations U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_put).
U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_put). - The keys starting with C(volatile.) are ignored for this comparison when O(ignore_volatile_options=true).
- The keys starting with C(volatile.) are ignored for this comparison when O(ignore_volatile_options=true). type: dict
type: dict required: false
required: false ignore_volatile_options:
ignore_volatile_options: description:
description: - If set to V(true), options starting with C(volatile.) are ignored. As a result, they are reapplied for each execution.
- If set to V(true), options starting with C(volatile.) are ignored. As a result, - This default behavior can be changed by setting this option to V(false).
they are reapplied for each execution. - The default value changed from V(true) to V(false) in community.general 6.0.0.
- This default behavior can be changed by setting this option to V(false). type: bool
- The default value changed from V(true) to V(false) in community.general 6.0.0. required: false
type: bool default: false
required: false version_added: 3.7.0
default: false profiles:
version_added: 3.7.0 description:
profiles: - Profile to be used by the instance.
description: type: list
- Profile to be used by the instance. elements: str
type: list devices:
elements: str description:
devices: - 'The devices for the instance (for example V({ "rootfs": { "path": "/dev/kvm", "type": "unix-char" }})).
description: - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).'
- 'The devices for the instance type: dict
(for example V({ "rootfs": { "path": "/dev/kvm", "type": "unix-char" }})). required: false
See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).' ephemeral:
type: dict description:
required: false - Whether or not the instance is ephemeral (for example V(true) or V(false)).
ephemeral: - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get).
description: required: false
- Whether or not the instance is ephemeral (for example V(true) or V(false)). type: bool
See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/instances/instance_get). source:
required: false description:
type: bool - 'The source for the instance (for example V({ "type": "image", "mode": "pull", "server": "https://cloud-images.ubuntu.com/releases/",
source: "protocol": "simplestreams", "alias": "22.04" })).'
description: - See U(https://documentation.ubuntu.com/lxd/en/latest/api/) for complete API documentation.
- 'The source for the instance - 'Note that C(protocol) accepts two choices: V(lxd) or V(simplestreams).'
(for example V({ "type": "image", "mode": "pull", "server": "https://cloud-images.ubuntu.com/releases/", required: false
"protocol": "simplestreams", "alias": "22.04" })).' type: dict
- 'See U(https://documentation.ubuntu.com/lxd/en/latest/api/) for complete API documentation.' state:
- 'Note that C(protocol) accepts two choices: V(lxd) or V(simplestreams).' choices:
required: false - started
type: dict - stopped
state: - restarted
choices: - absent
- started - frozen
- stopped description:
- restarted - Define the state of an instance.
- absent required: false
- frozen default: started
description: type: str
- Define the state of an instance. target:
required: false description:
default: started - For cluster deployments. Will attempt to create an instance on a target node. If the instance exists elsewhere in a cluster, then it will
type: str not be replaced or moved. The name should respond to same name of the node you see in C(lxc cluster list).
target: type: str
description: required: false
- For cluster deployments. Will attempt to create an instance on a target node. version_added: 1.0.0
If the instance exists elsewhere in a cluster, then it will not be replaced or moved. timeout:
The name should respond to same name of the node you see in C(lxc cluster list). description:
type: str - A timeout for changing the state of the instance.
required: false - This is also used as a timeout for waiting until IPv4 addresses are set to the all network interfaces in the instance after starting or
version_added: 1.0.0 restarting.
timeout: required: false
description: default: 30
- A timeout for changing the state of the instance. type: int
- This is also used as a timeout for waiting until IPv4 addresses type:
are set to the all network interfaces in the instance after description:
starting or restarting. - Instance type can be either V(virtual-machine) or V(container).
required: false required: false
default: 30 default: container
type: int choices:
type: - container
description: - virtual-machine
- Instance type can be either V(virtual-machine) or V(container). type: str
required: false version_added: 4.1.0
default: container wait_for_ipv4_addresses:
choices: description:
- container - If this is V(true), the C(lxd_container) waits until IPv4 addresses are set to the all network interfaces in the instance after starting
- virtual-machine or restarting.
type: str required: false
version_added: 4.1.0 default: false
wait_for_ipv4_addresses: type: bool
description: wait_for_container:
- If this is V(true), the C(lxd_container) waits until IPv4 addresses description:
are set to the all network interfaces in the instance after - If set to V(true), the tasks will wait till the task reports a success status when performing container operations.
starting or restarting. default: false
required: false type: bool
default: false version_added: 4.4.0
type: bool force_stop:
wait_for_container: description:
description: - If this is V(true), the C(lxd_container) forces to stop the instance when it stops or restarts the instance.
- If set to V(true), the tasks will wait till the task reports a required: false
success status when performing container operations. default: false
default: false type: bool
type: bool url:
version_added: 4.4.0 description:
force_stop: - The unix domain socket path or the https URL for the LXD server.
description: required: false
- If this is V(true), the C(lxd_container) forces to stop the instance default: unix:/var/lib/lxd/unix.socket
when it stops or restarts the instance. type: str
required: false snap_url:
default: false description:
type: bool - The unix domain socket path when LXD is installed by snap package manager.
url: required: false
description: default: unix:/var/snap/lxd/common/lxd/unix.socket
- The unix domain socket path or the https URL for the LXD server. type: str
required: false client_key:
default: unix:/var/lib/lxd/unix.socket description:
type: str - The client certificate key file path.
snap_url: - If not specified, it defaults to C(${HOME}/.config/lxc/client.key).
description: required: false
- The unix domain socket path when LXD is installed by snap package manager. aliases: [key_file]
required: false type: path
default: unix:/var/snap/lxd/common/lxd/unix.socket client_cert:
type: str description:
client_key: - The client certificate file path.
description: - If not specified, it defaults to C(${HOME}/.config/lxc/client.crt).
- The client certificate key file path. required: false
- If not specified, it defaults to C(${HOME}/.config/lxc/client.key). aliases: [cert_file]
required: false type: path
aliases: [ key_file ] trust_password:
type: path description:
client_cert: - The client trusted password.
description: - 'You need to set this password on the LXD server before running this module using the following command: C(lxc config set core.trust_password
- The client certificate file path. <some random password>). See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).'
- If not specified, it defaults to C(${HOME}/.config/lxc/client.crt). - If trust_password is set, this module send a request for authentication before sending any requests.
required: false required: false
aliases: [ cert_file ] type: str
type: path
trust_password:
description:
- The client trusted password.
- 'You need to set this password on the LXD server before
running this module using the following command:
C(lxc config set core.trust_password <some random password>).
See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).'
- If trust_password is set, this module send a request for
authentication before sending any requests.
required: false
type: str
notes: notes:
- Instances can be a container or a virtual machine, both of them must have unique name. If you attempt to create an instance - Instances can be a container or a virtual machine, both of them must have unique name. If you attempt to create an instance with a name that
with a name that already existed in the users namespace the module will already existed in the users namespace the module will simply return as "unchanged".
simply return as "unchanged". - There are two ways to run commands inside a container or virtual machine, using the command module or using the ansible lxd connection plugin
- There are two ways to run commands inside a container or virtual machine, using the command bundled in Ansible >= 2.1, the later requires python to be installed in the instance which can be done with the command module.
module or using the ansible lxd connection plugin bundled in Ansible >= - You can copy a file from the host to the instance with the Ansible M(ansible.builtin.copy) and M(ansible.builtin.template) module and the
2.1, the later requires python to be installed in the instance which can P(community.general.lxd#connection) connection plugin. See the example below.
be done with the command module. - You can copy a file in the created instance to the localhost with C(command=lxc file pull instance_name/dir/filename filename). See the first
- You can copy a file from the host to the instance example below.
with the Ansible M(ansible.builtin.copy) and M(ansible.builtin.template) module - Linuxcontainers.org has phased out LXC/LXD support with March 2024
and the P(community.general.lxd#connection) connection plugin.
See the example below.
- You can copy a file in the created instance to the localhost
with C(command=lxc file pull instance_name/dir/filename filename).
See the first example below.
- linuxcontainers.org has phased out LXC/LXD support with March 2024
(U(https://discuss.linuxcontainers.org/t/important-notice-for-lxd-users-image-server/18479)). (U(https://discuss.linuxcontainers.org/t/important-notice-for-lxd-users-image-server/18479)).
Currently only Ubuntu is still providing images. Currently only Ubuntu is still providing images.
''' """
EXAMPLES = ''' EXAMPLES = r"""
# An example for creating a Ubuntu container and install python # An example for creating a Ubuntu container and install python
- hosts: localhost - hosts: localhost
connection: local connection: local
@ -279,7 +260,7 @@ EXAMPLES = '''
source: source:
type: image type: image
mode: pull mode: pull
# Provides Ubuntu minimal images # Provides Ubuntu minimal images
server: https://cloud-images.ubuntu.com/minimal/releases/ server: https://cloud-images.ubuntu.com/minimal/releases/
protocol: simplestreams protocol: simplestreams
alias: "22.04" alias: "22.04"
@ -400,12 +381,12 @@ EXAMPLES = '''
protocol: simplestreams protocol: simplestreams
type: image type: image
mode: pull mode: pull
server: [...] # URL to the image server server: ['...'] # URL to the image server
alias: debian/11 alias: debian/11
timeout: 600 timeout: 600
''' """
RETURN = ''' RETURN = r"""
addresses: addresses:
description: Mapping from the network device name to a list of IPv4 addresses in the instance. description: Mapping from the network device name to a list of IPv4 addresses in the instance.
returned: when state is started or restarted returned: when state is started or restarted
@ -426,7 +407,8 @@ actions:
returned: success returned: success
type: list type: list
sample: ["create", "start"] sample: ["create", "start"]
''' """
import copy import copy
import datetime import datetime
import os import os

244
plugins/modules/lxd_profile.py
View File

@ -9,126 +9,114 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: lxd_profile module: lxd_profile
short_description: Manage LXD profiles short_description: Manage LXD profiles
description: description:
- Management of LXD profiles - Management of LXD profiles.
author: "Hiroaki Nakamura (@hnakamur)" author: "Hiroaki Nakamura (@hnakamur)"
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: none support: none
diff_mode: diff_mode:
support: none support: none
options: options:
name: name:
description:
- Name of a profile.
required: true
type: str
project:
description:
- 'Project of a profile.
See U(https://documentation.ubuntu.com/lxd/en/latest/projects/).'
type: str
required: false
version_added: 4.8.0
description: description:
description: - Name of a profile.
- Description of the profile. required: true
type: str type: str
config: project:
description: description:
- 'The config for the instance (e.g. {"limits.memory": "4GB"}). - Project of a profile. See U(https://documentation.ubuntu.com/lxd/en/latest/projects/).
See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get).' type: str
- If the profile already exists and its "config" value in metadata required: false
obtained from version_added: 4.8.0
GET /1.0/profiles/<name> description:
U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get) description:
are different, then this module tries to apply the configurations - Description of the profile.
U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_put). type: str
- Not all config values are supported to apply the existing profile. config:
Maybe you need to delete and recreate a profile. description:
required: false - 'The config for the instance (for example V({"limits.memory": "4GB"})).
type: dict - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get).'
devices: - If the profile already exists and its C(config) value in metadata obtained from GET /1.0/profiles/<name>
description: U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get)
- 'The devices for the profile are different, then this module tries to apply the configurations U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_put).
(e.g. {"rootfs": {"path": "/dev/kvm", "type": "unix-char"}). - Not all config values are supported to apply the existing profile. Maybe you need to delete and recreate a profile.
See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get).' required: false
required: false type: dict
type: dict devices:
new_name: description:
description: - 'The devices for the profile (for example V({"rootfs": {"path": "/dev/kvm", "type": "unix-char"})).
- A new name of a profile. - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_get).'
- If this parameter is specified a profile will be renamed to this name. required: false
See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_post). type: dict
required: false new_name:
type: str description:
merge_profile: - A new name of a profile.
description: - If this parameter is specified a profile will be renamed to this name.
- Merge the configuration of the present profile with the new desired configuration, - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/profiles/profile_post).
instead of replacing it. required: false
required: false type: str
default: false merge_profile:
type: bool description:
version_added: 2.1.0 - Merge the configuration of the present profile with the new desired configuration, instead of replacing it.
state: required: false
choices: default: false
- present type: bool
- absent version_added: 2.1.0
description: state:
- Define the state of a profile. choices:
required: false - present
default: present - absent
type: str description:
url: - Define the state of a profile.
description: required: false
- The unix domain socket path or the https URL for the LXD server. default: present
required: false type: str
default: unix:/var/lib/lxd/unix.socket url:
type: str description:
snap_url: - The unix domain socket path or the https URL for the LXD server.
description: required: false
- The unix domain socket path when LXD is installed by snap package manager. default: unix:/var/lib/lxd/unix.socket
required: false type: str
default: unix:/var/snap/lxd/common/lxd/unix.socket snap_url:
type: str description:
client_key: - The unix domain socket path when LXD is installed by snap package manager.
description: required: false
- The client certificate key file path. default: unix:/var/snap/lxd/common/lxd/unix.socket
- If not specified, it defaults to C($HOME/.config/lxc/client.key). type: str
required: false client_key:
aliases: [ key_file ] description:
type: path - The client certificate key file path.
client_cert: - If not specified, it defaults to C($HOME/.config/lxc/client.key).
description: required: false
- The client certificate file path. aliases: [key_file]
- If not specified, it defaults to C($HOME/.config/lxc/client.crt). type: path
required: false client_cert:
aliases: [ cert_file ] description:
type: path - The client certificate file path.
trust_password: - If not specified, it defaults to C($HOME/.config/lxc/client.crt).
description: required: false
- The client trusted password. aliases: [cert_file]
- You need to set this password on the LXD server before type: path
running this module using the following command. trust_password:
lxc config set core.trust_password <some random password> description:
See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/) - The client trusted password.
- If trust_password is set, this module send a request for - You need to set this password on the LXD server before running this module using the following command. lxc config set core.trust_password
authentication before sending any requests. <some random password> See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).
required: false - If trust_password is set, this module send a request for authentication before sending any requests.
type: str required: false
type: str
notes: notes:
- Profiles must have a unique name. If you attempt to create a profile - Profiles must have a unique name. If you attempt to create a profile with a name that already existed in the users namespace the module will
with a name that already existed in the users namespace the module will
simply return as "unchanged". simply return as "unchanged".
''' """
EXAMPLES = ''' EXAMPLES = r"""
# An example for creating a profile # An example for creating a profile
- hosts: localhost - hosts: localhost
connection: local connection: local
@ -162,22 +150,22 @@ EXAMPLES = '''
- hosts: localhost - hosts: localhost
connection: local connection: local
tasks: tasks:
- name: Create macvlan profile - name: Create macvlan profile
community.general.lxd_profile: community.general.lxd_profile:
url: https://127.0.0.1:8443 url: https://127.0.0.1:8443
# These client_cert and client_key values are equal to the default values. # These client_cert and client_key values are equal to the default values.
#client_cert: "{{ lookup('env', 'HOME') }}/.config/lxc/client.crt" #client_cert: "{{ lookup('env', 'HOME') }}/.config/lxc/client.crt"
#client_key: "{{ lookup('env', 'HOME') }}/.config/lxc/client.key" #client_key: "{{ lookup('env', 'HOME') }}/.config/lxc/client.key"
trust_password: mypassword trust_password: mypassword
name: macvlan name: macvlan
state: present state: present
config: {} config: {}
description: my macvlan profile description: my macvlan profile
devices: devices:
eth0: eth0:
nictype: macvlan nictype: macvlan
parent: br0 parent: br0
type: nic type: nic
# An example for modify/merge a profile # An example for modify/merge a profile
- hosts: localhost - hosts: localhost
@ -214,11 +202,11 @@ EXAMPLES = '''
name: macvlan name: macvlan
new_name: macvlan2 new_name: macvlan2
state: present state: present
''' """
RETURN = ''' RETURN = r"""
old_state: old_state:
description: The old state of the profile description: The old state of the profile.
returned: success returned: success
type: str type: str
sample: "absent" sample: "absent"
@ -232,7 +220,7 @@ actions:
returned: success returned: success
type: list type: list
sample: ["create"] sample: ["create"]
''' """
import os import os
from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.basic import AnsibleModule

176
plugins/modules/lxd_project.py
View File

@ -7,8 +7,7 @@
from __future__ import absolute_import, division, print_function from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = r"""
---
module: lxd_project module: lxd_project
short_description: Manage LXD projects short_description: Manage LXD projects
version_added: 4.8.0 version_added: 4.8.0
@ -18,98 +17,91 @@ author: "Raymond Chang (@we10710aa)"
extends_documentation_fragment: extends_documentation_fragment:
- community.general.attributes - community.general.attributes
attributes: attributes:
check_mode: check_mode:
support: none support: none
diff_mode: diff_mode:
support: none support: none
options: options:
name: name:
description:
- Name of the project.
required: true
type: str
description: description:
description: - Name of the project.
- Description of the project. required: true
type: str type: str
config: description:
description: description:
- 'The config for the project (for example V({"features.profiles": "true"})). - Description of the project.
See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_get).' type: str
- If the project already exists and its "config" value in metadata config:
obtained from description:
C(GET /1.0/projects/<name>) - 'The config for the project (for example V({"features.profiles": "true"})).
U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_get) - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_get).'
are different, then this module tries to apply the configurations - If the project already exists and its "config" value in metadata obtained from C(GET /1.0/projects/<name>)
U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_put). U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_get)
type: dict are different, then this module tries to apply the configurations U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_put).
new_name: type: dict
description: new_name:
- A new name of a project. description:
- If this parameter is specified a project will be renamed to this name. - A new name of a project.
See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_post). - If this parameter is specified a project will be renamed to this name.
required: false - See U(https://documentation.ubuntu.com/lxd/en/latest/api/#/projects/project_post).
type: str required: false
merge_project: type: str
description: merge_project:
- Merge the configuration of the present project with the new desired configuration, description:
instead of replacing it. If configuration is the same after merged, no change will be made. - Merge the configuration of the present project with the new desired configuration, instead of replacing it. If configuration is the same
required: false after merged, no change will be made.
default: false required: false
type: bool default: false
state: type: bool
choices: state:
- present choices:
- absent - present
description: - absent
- Define the state of a project. description:
required: false - Define the state of a project.
default: present required: false
type: str default: present
url: type: str
description: url:
- The Unix domain socket path or the https URL for the LXD server. description:
required: false - The Unix domain socket path or the https URL for the LXD server.
default: unix:/var/lib/lxd/unix.socket required: false
type: str default: unix:/var/lib/lxd/unix.socket
snap_url: type: str
description: snap_url:
- The Unix domain socket path when LXD is installed by snap package manager. description:
required: false - The Unix domain socket path when LXD is installed by snap package manager.
default: unix:/var/snap/lxd/common/lxd/unix.socket required: false
type: str default: unix:/var/snap/lxd/common/lxd/unix.socket
client_key: type: str
description: client_key:
- The client certificate key file path. description:
- If not specified, it defaults to C($HOME/.config/lxc/client.key). - The client certificate key file path.
required: false - If not specified, it defaults to C($HOME/.config/lxc/client.key).
aliases: [ key_file ] required: false
type: path aliases: [key_file]
client_cert: type: path
description: client_cert:
- The client certificate file path. description:
- If not specified, it defaults to C($HOME/.config/lxc/client.crt). - The client certificate file path.
required: false - If not specified, it defaults to C($HOME/.config/lxc/client.crt).
aliases: [ cert_file ] required: false
type: path aliases: [cert_file]
trust_password: type: path
description: trust_password:
- The client trusted password. description:
- 'You need to set this password on the LXD server before - The client trusted password.
running this module using the following command: - 'You need to set this password on the LXD server before running this module using the following command: C(lxc config set core.trust_password
C(lxc config set core.trust_password <some random password>) <some random password>) See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).'
See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).' - If O(trust_password) is set, this module send a request for authentication before sending any requests.
- If O(trust_password) is set, this module send a request for required: false
authentication before sending any requests. type: str
required: false
type: str
notes: notes:
- Projects must have a unique name. If you attempt to create a project - Projects must have a unique name. If you attempt to create a project with a name that already existed in the users namespace the module will
with a name that already existed in the users namespace the module will
simply return as "unchanged". simply return as "unchanged".
''' """
EXAMPLES = ''' EXAMPLES = r"""
# An example for creating a project # An example for creating a project
- hosts: localhost - hosts: localhost
connection: local connection: local
@ -132,9 +124,9 @@ EXAMPLES = '''
state: present state: present
config: {} config: {}
description: my new project description: my new project
''' """
RETURN = ''' RETURN = r"""
old_state: old_state:
description: The old state of the project. description: The old state of the project.
returned: success returned: success
@ -184,7 +176,7 @@ actions:
type: list type: list
elements: str elements: str
sample: ["create"] sample: ["create"]
''' """
from ansible_collections.community.general.plugins.module_utils.lxd import ( from ansible_collections.community.general.plugins.module_utils.lxd import (
LXDClient, LXDClientException, default_key_file, default_cert_file LXDClient, LXDClientException, default_key_file, default_cert_file