diff --git a/galaxy.yml b/galaxy.yml index 7f09051..cbc6142 100644 --- a/galaxy.yml +++ b/galaxy.yml @@ -1,7 +1,7 @@ --- namespace: sebastian name: systemd -version: 0.4.3 +version: 0.4.4 readme: README.md @@ -13,7 +13,7 @@ tags: - systemd - linux dependencies: - sebastian.base: ">=0.4.3" + sebastian.base: ">=0.5.0" repository: https://gitea.sebastian-tobie.de/ansible/ansible-systemd.git # documentation: http://docs.example.com homepage: https://gitea.sebastian-tobie.de/ansible/ansible-systemd diff --git a/plugins/modules/link.py b/plugins/modules/link.py index e94de62..110a82a 100644 --- a/plugins/modules/link.py +++ b/plugins/modules/link.py @@ -101,7 +101,7 @@ class Module(SystemdUnitModule): # type: ignore self.module.run_command(args, check_rc=True) -DOCUMENTATION = """--- +DOCUMENTATION = r"""--- description: - generates an systemd-networkd link module: link diff --git a/plugins/modules/mount.py b/plugins/modules/mount.py index 4adc8c9..f2583ab 100644 --- a/plugins/modules/mount.py +++ b/plugins/modules/mount.py @@ -66,7 +66,7 @@ class Module(SystemdUnitModule, SystemdReloadMixin): # type: ignore[misc] return "[Mount]\n" + "".join(options) -DOCUMENTATION = """--- +DOCUMENTATION = r"""--- description: - Creates an systemd mount module: mount diff --git a/plugins/modules/netdev.py b/plugins/modules/netdev.py index cffd113..9e08f89 100644 --- a/plugins/modules/netdev.py +++ b/plugins/modules/netdev.py @@ -135,7 +135,7 @@ class Module(SystemdUnitModule): # type:ignore[reportGeneralTypeIssues] return "[Vlan]\n" + "".join(options) -DOCUMENTATION = """--- +DOCUMENTATION = r"""--- description: - Creates an netdev unit that creates an virtual devices module: netdev @@ -200,7 +200,9 @@ options: required: false type: bool virtualization: - required: true + description: + - Virtualization that is checked against + required: false type: str short_description: Creates an netdev unit that creates an virtual devices """ diff --git a/plugins/modules/network.py b/plugins/modules/network.py index 2ef0436..0602f0e 100644 --- a/plugins/modules/network.py +++ b/plugins/modules/network.py @@ -106,7 +106,7 @@ class Module(SystemdUnitModule): # type: ignore return "\n".join(output) -DOCUMENTATION = """--- +DOCUMENTATION = r"""--- description: - Sets up the systemd network unit module: network diff --git a/plugins/modules/socket.py b/plugins/modules/socket.py index 47b99dc..95e2deb 100644 --- a/plugins/modules/socket.py +++ b/plugins/modules/socket.py @@ -19,21 +19,27 @@ class Module(SystemdUnitModule, SystemdReloadMixin): # type: ignore argument_spec=dict( name=Types.str(required=True, help="Name of the socket"), stream=Types.list( - Types.str( + help="Ip-Addresses or paths for Stream-sockets, e.g. normal unix-sockets or TCP sockets", + elements=Types.str( help="Name of the stream socket. The name can be a path, an portnumber or an ip with an port. addresses in square brackets are always ipv6 addresses" - ) + ), ), datagram=Types.list( - Types.str( + help="Ip-Addresses or paths for Datagram-sockets, e.g. Datagram unix-sockets or UDP sockets", + elements=Types.str( help="Name of the datagram socket. The name can be a path, an portnumber or an ip with an port. addresses in square brackets are always ipv6 addresses" - ) + ), ), sequential=Types.list( - Types.str( + help="Ip-Addresses or paths for Sequential Sockets.", + elements=Types.str( help="Name of the sequential socket. The name can be a path, an portnumber or an ip with an port. addresses in square brackets are always ipv6 addresses" - ) + ), + ), + fifo=Types.list( + help="List of paths for FIFOs(First In First Out)", + elements=Types.path(help="Name of the fifo. The name must be an absolute path"), ), - fifo=Types.list(Types.path(help="Name of the fifo. The name must be an absolute path")), socketuser=Types.str(help="User that owns the socket/fifo"), socketgroup=Types.str(help="Group that owns the socket/fifo"), socketmode=Types.str(help="mode of the socket in octal notation", default="0666"), @@ -71,7 +77,7 @@ class Module(SystemdUnitModule, SystemdReloadMixin): # type: ignore return self.__unit -DOCUMENTATION = """--- +DOCUMENTATION = r"""--- description: - Creates socket units. module: socket @@ -92,6 +98,9 @@ options: type: list datagram: default: [] + description: + - Ip-Addresses or paths for Datagram-sockets, e.g. Datagram unix-sockets or UDP + sockets elements: str required: false type: list @@ -109,6 +118,8 @@ options: type: list fifo: default: [] + description: + - List of paths for FIFOs(First In First Out) elements: path required: false type: list @@ -143,6 +154,8 @@ options: type: list sequential: default: [] + description: + - Ip-Addresses or paths for Sequential Sockets. elements: str required: false type: list @@ -171,6 +184,8 @@ options: type: str stream: default: [] + description: + - Ip-Addresses or paths for Stream-sockets, e.g. normal unix-sockets or TCP sockets elements: str required: false type: list diff --git a/plugins/modules/system_service.py b/plugins/modules/system_service.py index 6831c1d..29e293b 100644 --- a/plugins/modules/system_service.py +++ b/plugins/modules/system_service.py @@ -46,6 +46,7 @@ class Module(SystemdUnitModule, SystemdReloadMixin): # type: ignore[misc] ), environment=Types.list( elements=Types.dict( + help="An Environment Variable", name=Types.str(help="name of the Environment variable", required=True), value=Types.str(help="value of the Environment variable", required=True), ), @@ -55,23 +56,23 @@ class Module(SystemdUnitModule, SystemdReloadMixin): # type: ignore[misc] help="The Directory that is used for the processes as current working directory", ), rwpath=Types.list( - elements=Types.path(), + elements=Types.path(help="An Read and writable Path"), help="Path(s) that are readable and writable (if permission allow)", ), ropath=Types.list( - elements=Types.path(), + elements=Types.path(help="An Read and writable Path"), help="Path(s) that are read only", ), notreadablepath=Types.list( - elements=Types.path(), + elements=Types.path(help="An Read and writable Path"), help="Path(s) that are not accessible by the applications", ), execpath=Types.list( - elements=Types.path(), + elements=Types.path(help="An Read and writable Path"), help="Path(s) where executable files are", ), noexecpath=Types.list( - elements=Types.path(), + elements=Types.path(help="An Read and writable Path"), help="Path(s) which are never executable (uploaded files, user accessible paths)", ), protecthome=Types.str( @@ -91,8 +92,23 @@ class Module(SystemdUnitModule, SystemdReloadMixin): # type: ignore[misc] runtimedirectory=Types.str( help="creates an unit specific runtime directory in /run and sets the env var RUNTIME_DIRECTORY with the path to it. Its cleaned up after the unit is stopped" ), - restart=Types.str(), - restartsec=Types.str(), + restart=Types.str( + help=[ + "Controls when the service is automatically restarted", + "no means never", + "on-success when it exits with an exitcode of 0 or one of the SuccessExitStatus(not implemented) values", + "on-failure is the reverse of the on-success value", + "on-abnormal is when an service has to be killed or doesn't react to notifications from systemd, if its of the notify type", + "on-abort means if it has to be killed, because it didn't react to signals", + "on-watchdog when services missed the regular ping or other important messages", + "always means what it is: restart it whenever it is stopped", + "This setting is invalid for oneshot services", + ], + choices=("no", "on-success", "on-failure", "on-abnormal", "on-watchdog", "on-abort", "always"), + ), + restartsec=Types.str( + help="this is the time it is waited between the stop of an service and its restart. this can be an time in seconds or an timespan like '5m 20s'" + ), ), ) @@ -145,9 +161,11 @@ class Module(SystemdUnitModule, SystemdReloadMixin): # type: ignore[misc] return self.__unit -DOCUMENTATION = """--- +DOCUMENTATION = r"""--- description: - Creates System Services units +extends_documentation_fragment: +- ansible.builtin.files module: system_service options: after: @@ -301,9 +319,32 @@ options: required: false type: list restart: + choices: + - 'no' + - on-success + - on-failure + - on-abnormal + - on-watchdog + - on-abort + - always + description: + - Controls when the service is automatically restarted + - no means never + - on-success when it exits with an exitcode of 0 or one of the SuccessExitStatus(not + implemented) values + - on-failure is the reverse of the on-success value + - on-abnormal is when an service has to be killed or doesn't react to notifications + from systemd, if its of the notify type + - on-abort means if it has to be killed, because it didn't react to signals + - on-watchdog when services missed the regular ping or other important messages + - 'always means what it is: restart it whenever it is stopped' + - This setting is invalid for oneshot services required: false type: str restartsec: + description: + - this is the time it is waited between the stop of an service and its restart. + this can be an time in seconds or an timespan like '5m 20s' required: false type: str ropath: diff --git a/plugins/modules/target.py b/plugins/modules/target.py index 4d559b5..7c281b3 100644 --- a/plugins/modules/target.py +++ b/plugins/modules/target.py @@ -3,10 +3,10 @@ import pathlib from typing import List, Union try: - from ansible_module.module_utils.generic import SYSTEMD_SERVICE_CONFIG, Types, systemdbool # type: ignore[reportMissingImports] + from ansible_module.module_utils.generic import SYSTEMD_SERVICE_CONFIG, Types, systemdbool, modspec # type: ignore[reportMissingImports] from ansible_module.module_utils.module import SystemdReloadMixin, SystemdUnitModule, installable # type: ignore[reportMissingImports] except ImportError: - from ansible_collections.sebastian.base.plugins.module_utils.generic import SYSTEMD_SERVICE_CONFIG, Types, systemdbool + from ansible_collections.sebastian.base.plugins.module_utils.generic import SYSTEMD_SERVICE_CONFIG, Types, systemdbool, modspec from ansible_collections.sebastian.base.plugins.module_utils.module import SystemdReloadMixin, SystemdUnitModule, installable __module_name__ = "TargetModule" @@ -17,7 +17,7 @@ class TargetModule(SystemdUnitModule, SystemdReloadMixin): # type: ignore[misc] """Creates Target units""" name = "target" - module_spec = dict( + module_spec = modspec( argument_spec=dict( description=Types.str(help="description of the target"), name=Types.str(required=True, help="name of the target"), @@ -49,7 +49,7 @@ class TargetModule(SystemdUnitModule, SystemdReloadMixin): # type: ignore[misc] return self.__unit -DOCUMENTATION = """--- +DOCUMENTATION = r"""--- description: - Creates Target units module: target diff --git a/plugins/modules/timer.py b/plugins/modules/timer.py index 3b98577..685bf02 100644 --- a/plugins/modules/timer.py +++ b/plugins/modules/timer.py @@ -24,27 +24,27 @@ class TimerModule(SystemdUnitModule, SystemdReloadMixin): # type: ignore[misc] description=Types.str(help="Description of the timer"), onactive=Types.list( help="Starts the service x seconds after this timer was activated", - elements=Types.str(), + elements=Types.str(help="Takes the time in seconds or an timespan like '5m 20s'"), ), onboot=Types.list( help="Starts the service x seconds after the device was booted or the container was started", - elements=Types.str(), + elements=Types.str(help="Takes the time in seconds or an timespan like '5m 20s'"), ), onstartup=Types.list( help="Starts the service x seconds after the System's/User's systemd instance was started", - elements=Types.str(), + elements=Types.str(help="Takes the time in seconds or an timespan like '5m 20s'"), ), onunitactive=Types.list( help="Starts the service x seconds after the unit this timer activates was last activated", - elements=Types.str(), + elements=Types.str(help="Takes the time in seconds or an timespan like '5m 20s'"), ), onunitinactive=Types.list( help="Starts the service x seconds after the unit this timer activates was last deactivated", - elements=Types.str(), + elements=Types.str(help="Takes the time in seconds or an timespan like '5m 20s'"), ), oncalendar=Types.list( help="Uses an Time string to start the unit.", - elements=Types.str(), + elements=Types.str(help="Takes an Value representing a specific date or dates"), ), persistent=Types.bool( help="If the system was down in the time the timer would have started the unit, start the unit as soon as possible." @@ -103,7 +103,7 @@ class TimerModule(SystemdUnitModule, SystemdReloadMixin): # type: ignore[misc] return self.__unit -DOCUMENTATION = """--- +DOCUMENTATION = r"""--- description: - Creates Timer units module: timer