ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-04-24 03:11:24 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

Unflatmap community.general (#5461)

Browse source 
* Move files.

* Update imports and references.

* Move wrongly placed files.

* Reverse redirects, deprecate long → short name redirects.

* Simplify contribution guidelines for new modules.

* Rewrite BOTMETA.

* Add changelog fragment.

* Fix ignore.txt files.
This commit is contained in:
Felix Fontein 2022-11-02 21:42:29 +01:00 • committed by GitHub
parent 2b0bebc8fc
commit b531ecdc9b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1033 changed files with 4802 additions and 1989 deletions
Download patch file Download diff file Expand all files Collapse all files

515
plugins/modules/launchd.py Normal file
View file

@ -0,0 +1,515 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright (c) 2018, Martin Migasiewicz <migasiew.nk@gmail.com>
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
module: launchd
author:
- Martin Migasiewicz (@martinm82)
short_description: Manage macOS services
version_added: 1.0.0
description:
- Manage launchd services on target macOS hosts.
options:
name:
description:
- Name of the service.
type: str
required: true
state:
description:
- C(started)/C(stopped) are idempotent actions that will not run
commands unless necessary.
- Launchd does not support C(restarted) nor C(reloaded) natively.
These will trigger a stop/start (restarted) or an unload/load
(reloaded).
- C(restarted) unloads and loads the service before start to ensure
that the latest job definition (plist) is used.
- C(reloaded) unloads and loads the service to ensure that the latest
job definition (plist) is used. Whether a service is started or
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.
- B(At least one of state and enabled are required.)
type: bool
force_stop:
description:
- Whether the service should not be restarted automatically by launchd.
- Services might have the 'KeepAlive' attribute set to true in a launchd configuration.
In case this is set to true, stopping a service will cause that launchd starts the service again.
- Set this option to C(true) to let this module change the 'KeepAlive' attribute to false.
type: bool
default: false
notes:
- A user must privileged to manage services using this module.
requirements:
- A system managed by launchd
- The plistlib python library
'''
EXAMPLES = r'''
- name: Make sure spotify webhelper is started
community.general.launchd:
name: com.spotify.webhelper
state: started
- name: Deploy custom memcached job definition
template:
src: org.memcached.plist.j2
dest: /Library/LaunchDaemons/org.memcached.plist
- name: Run memcached
community.general.launchd:
name: org.memcached
state: started
- name: Stop memcached
community.general.launchd:
name: org.memcached
state: stopped
- name: Stop memcached
community.general.launchd:
name: org.memcached
state: stopped
force_stop: true
- name: Restart memcached
community.general.launchd:
name: org.memcached
state: restarted
- name: Unload memcached
community.general.launchd:
name: org.memcached
state: unloaded
'''
RETURN = r'''
status:
description: Metadata about service status
returned: always
type: dict
sample:
{
"current_pid": "-",
"current_state": "stopped",
"previous_pid": "82636",
"previous_state": "running"
}
'''
import os
import plistlib
from abc import ABCMeta, abstractmethod
from time import sleep
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.common.text.converters import to_native
class ServiceState:
UNKNOWN = 0
LOADED = 1
STOPPED = 2
STARTED = 3
UNLOADED = 4
@staticmethod
def to_string(state):
strings = {
ServiceState.UNKNOWN: 'unknown',
ServiceState.LOADED: 'loaded',
ServiceState.STOPPED: 'stopped',
ServiceState.STARTED: 'started',
ServiceState.UNLOADED: 'unloaded'
}
return strings[state]
class Plist:
def __init__(self, module, service):
self.__changed = False
self.__service = service
state, pid, dummy, dummy = LaunchCtlList(module, self.__service).run()
# Check if readPlist is available or not
self.old_plistlib = hasattr(plistlib, 'readPlist')
self.__file = self.__find_service_plist(self.__service)
if self.__file is None:
msg = 'Unable to infer the path of %s service plist file' % self.__service
if pid is None and state == ServiceState.UNLOADED:
msg += ' and it was not found among active services'
module.fail_json(msg=msg)
self.__update(module)
@staticmethod
def __find_service_plist(service_name):
"""Finds the plist file associated with a service"""
launchd_paths = [
os.path.join(os.getenv('HOME'), 'Library/LaunchAgents'),
'/Library/LaunchAgents',
'/Library/LaunchDaemons',
'/System/Library/LaunchAgents',
'/System/Library/LaunchDaemons'
]
for path in launchd_paths:
try:
files = os.listdir(path)
except OSError:
continue
filename = '%s.plist' % service_name
if filename in files:
return os.path.join(path, filename)
return None
def __update(self, module):
self.__handle_param_enabled(module)
self.__handle_param_force_stop(module)
def __read_plist_file(self, module):
service_plist = {}
if self.old_plistlib:
return plistlib.readPlist(self.__file)
# readPlist is deprecated in Python 3 and onwards
try:
with open(self.__file, 'rb') as plist_fp:
service_plist = plistlib.load(plist_fp)
except Exception as e:
module.fail_json(msg="Failed to read plist file "
"%s due to %s" % (self.__file, to_native(e)))
return service_plist
def __write_plist_file(self, module, service_plist=None):
if not service_plist:
service_plist = {}
if self.old_plistlib:
plistlib.writePlist(service_plist, self.__file)
return
# writePlist is deprecated in Python 3 and onwards
try:
with open(self.__file, 'wb') as plist_fp:
plistlib.dump(service_plist, plist_fp)
except Exception as e:
module.fail_json(msg="Failed to write to plist file "
" %s due to %s" % (self.__file, to_native(e)))
def __handle_param_enabled(self, module):
if module.params['enabled'] is not None:
service_plist = self.__read_plist_file(module)
# Enable/disable service startup at boot if requested
# Launchctl does not expose functionality to set the RunAtLoad
# attribute of a job definition. So we parse and modify the job
# definition plist file directly for this purpose.
if module.params['enabled'] is not None:
enabled = service_plist.get('RunAtLoad', False)
if module.params['enabled'] != enabled:
service_plist['RunAtLoad'] = module.params['enabled']
# Update the plist with one of the changes done.
if not module.check_mode:
self.__write_plist_file(module, service_plist)
self.__changed = True
def __handle_param_force_stop(self, module):
if module.params['force_stop'] is not None:
service_plist = self.__read_plist_file(module)
# Set KeepAlive to false in case force_stop is defined to avoid
# that the service gets restarted when stopping was requested.
if module.params['force_stop'] is not None:
keep_alive = service_plist.get('KeepAlive', False)
if module.params['force_stop'] and keep_alive:
service_plist['KeepAlive'] = not module.params['force_stop']
# Update the plist with one of the changes done.
if not module.check_mode:
self.__write_plist_file(module, service_plist)
self.__changed = True
def is_changed(self):
return self.__changed
def get_file(self):
return self.__file
class LaunchCtlTask(object):
__metaclass__ = ABCMeta
WAITING_TIME = 5 # seconds
def __init__(self, module, service, plist):
self._module = module
self._service = service
self._plist = plist
self._launch = self._module.get_bin_path('launchctl', True)
def run(self):
"""Runs a launchd command like 'load', 'unload', 'start', 'stop', etc.
and returns the new state and pid.
"""
self.runCommand()
return self.get_state()
@abstractmethod
def runCommand(self):
pass
def get_state(self):
rc, out, err = self._launchctl("list")
if rc != 0:
self._module.fail_json(
msg='Failed to get status of %s' % (self._launch))
state = ServiceState.UNLOADED
service_pid = "-"
status_code = None
for line in out.splitlines():
if line.strip():
pid, last_exit_code, label = line.split('\t')
if label.strip() == self._service:
service_pid = pid
status_code = last_exit_code
# From launchctl man page:
# If the number [...] is negative, it represents the
# negative of the signal which killed the job. Thus,
# "-15" would indicate that the job was terminated with
# SIGTERM.
if last_exit_code not in ['0', '-2', '-3', '-9', '-15']:
# Something strange happened and we have no clue in
# which state the service is now. Therefore we mark
# the service state as UNKNOWN.
state = ServiceState.UNKNOWN
elif pid != '-':
# PID seems to be an integer so we assume the service
# is started.
state = ServiceState.STARTED
else:
# Exit code is 0 and PID is not available so we assume
# the service is stopped.
state = ServiceState.STOPPED
break
return (state, service_pid, status_code, err)
def start(self):
rc, out, err = self._launchctl("start")
# Unfortunately launchd does not wait until the process really started.
sleep(self.WAITING_TIME)
return (rc, out, err)
def stop(self):
rc, out, err = self._launchctl("stop")
# Unfortunately launchd does not wait until the process really stopped.
sleep(self.WAITING_TIME)
return (rc, out, err)
def restart(self):
# TODO: check for rc, out, err
self.stop()
return self.start()
def reload(self):
# TODO: check for rc, out, err
self.unload()
return self.load()
def load(self):
return self._launchctl("load")
def unload(self):
return self._launchctl("unload")
def _launchctl(self, command):
service_or_plist = self._plist.get_file() if command in [
'load', 'unload'] else self._service if command in ['start', 'stop'] else ""
rc, out, err = self._module.run_command(
'%s %s %s' % (self._launch, command, service_or_plist))
if rc != 0:
msg = "Unable to %s '%s' (%s): '%s'" % (
command, self._service, self._plist.get_file(), err)
self._module.fail_json(msg=msg)
return (rc, out, err)
class LaunchCtlStart(LaunchCtlTask):
def __init__(self, module, service, plist):
super(LaunchCtlStart, self).__init__(module, service, plist)
def runCommand(self):
state, dummy, dummy, dummy = self.get_state()
if state in (ServiceState.STOPPED, ServiceState.LOADED):
self.reload()
self.start()
elif state == ServiceState.STARTED:
# In case the service is already in started state but the
# job definition was changed we need to unload/load the
# service and start the service again.
if self._plist.is_changed():
self.reload()
self.start()
elif state == ServiceState.UNLOADED:
self.load()
self.start()
elif state == ServiceState.UNKNOWN:
# We are in an unknown state, let's try to reload the config
# and start the service again.
self.reload()
self.start()
class LaunchCtlStop(LaunchCtlTask):
def __init__(self, module, service, plist):
super(LaunchCtlStop, self).__init__(module, service, plist)
def runCommand(self):
state, dummy, dummy, dummy = self.get_state()
if state == ServiceState.STOPPED:
# In case the service is stopped and we might later decide
# to start it, we need to reload the job definition by
# forcing an unload and load first.
# Afterwards we need to stop it as it might have been
# started again (KeepAlive or RunAtLoad).
if self._plist.is_changed():
self.reload()
self.stop()
elif state in (ServiceState.STARTED, ServiceState.LOADED):
if self._plist.is_changed():
self.reload()
self.stop()
elif state == ServiceState.UNKNOWN:
# We are in an unknown state, let's try to reload the config
# and stop the service gracefully.
self.reload()
self.stop()
class LaunchCtlReload(LaunchCtlTask):
def __init__(self, module, service, plist):
super(LaunchCtlReload, self).__init__(module, service, plist)
def runCommand(self):
state, dummy, dummy, dummy = self.get_state()
if state == ServiceState.UNLOADED:
# launchd throws an error if we do an unload on an already
# unloaded service.
self.load()
else:
self.reload()
class LaunchCtlUnload(LaunchCtlTask):
def __init__(self, module, service, plist):
super(LaunchCtlUnload, self).__init__(module, service, plist)
def runCommand(self):
state, dummy, dummy, dummy = self.get_state()
self.unload()
class LaunchCtlRestart(LaunchCtlReload):
def __init__(self, module, service, plist):
super(LaunchCtlRestart, self).__init__(module, service, plist)
def runCommand(self):
super(LaunchCtlRestart, self).runCommand()
self.start()
class LaunchCtlList(LaunchCtlTask):
def __init__(self, module, service):
super(LaunchCtlList, self).__init__(module, service, None)
def runCommand(self):
# Do nothing, the list functionality is done by the
# base class run method.
pass
def main():
module = AnsibleModule(
argument_spec=dict(
name=dict(type='str', required=True),
state=dict(type='str', choices=['reloaded', 'restarted', 'started', 'stopped', 'unloaded']),
enabled=dict(type='bool'),
force_stop=dict(type='bool', default=False),
),
supports_check_mode=True,
required_one_of=[
['state', 'enabled'],
],
)
service = module.params['name']
action = module.params['state']
rc = 0
out = err = ''
result = {
'name': service,
'changed': False,
'status': {},
}
# We will tailor the plist file in case one of the options
# (enabled, force_stop) was specified.
plist = Plist(module, service)
result['changed'] = plist.is_changed()
# Gather information about the service to be controlled.
state, pid, dummy, dummy = LaunchCtlList(module, service).run()
result['status']['previous_state'] = ServiceState.to_string(state)
result['status']['previous_pid'] = pid
# Map the actions to specific tasks
tasks = {
'started': LaunchCtlStart(module, service, plist),
'stopped': LaunchCtlStop(module, service, plist),
'restarted': LaunchCtlRestart(module, service, plist),
'reloaded': LaunchCtlReload(module, service, plist),
'unloaded': LaunchCtlUnload(module, service, plist)
}
status_code = '0'
# Run the requested task
if not module.check_mode:
state, pid, status_code, err = tasks[action].run()
result['status']['current_state'] = ServiceState.to_string(state)
result['status']['current_pid'] = pid
result['status']['status_code'] = status_code
result['status']['error'] = err
if (result['status']['current_state'] != result['status']['previous_state'] or
result['status']['current_pid'] != result['status']['previous_pid']):
result['changed'] = True
if module.check_mode:
result['changed'] = True
module.exit_json(**result)
if __name__ == '__main__':
main()