Docs4dev
Docs
ansible / latest / collections / community / general / launchd_module.html

community.general.launchd – Manage macOS services

Note

This plugin is part of the community.general collection (version 3.8.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.launchd.

New in version 1.0.0: of community.general

Synopsis

  • Manage launchd services on target macOS hosts.

Requirements

The below requirements are needed on the host that executes this module.

  • A system managed by launchd
  • The plistlib python library

Parameters

Parameter Choices/Defaults Comments
enabled
boolean
    Choices:
  • no
  • yes
Whether the service should start on boot.
At least one of state and enabled are required.
force_stop
boolean
    Choices:
  • no ←
  • yes
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 yes to let this module change the 'KeepAlive' attribute to false.
name
string / required
Name of the service.
state
string
    Choices:
  • reloaded
  • restarted
  • started
  • stopped
  • unloaded
started/stopped are idempotent actions that will not run commands unless necessary.
Launchd does not support restarted nor reloaded natively. These will trigger a stop/start (restarted) or an unload/load (reloaded).
restarted unloads and loads the service before start to ensure that the latest job definition (plist) is used.
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.

Notes

Note

  • A user must privileged to manage services using this module.

Examples

- 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: yes

- name: Restart memcached
  community.general.launchd:
    name: org.memcached
    state: restarted

- name: Unload memcached
  community.general.launchd:
    name: org.memcached
    state: unloaded

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
status
dictionary
always
Metadata about service status

Sample:
{'current_pid': '-', 'current_state': 'stopped', 'previous_pid': '82636', 'previous_state': 'running'}


Authors

  • Martin Migasiewicz (@martinm82)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/launchd_module.html