community.general.launchd module – Manage macOS services

Note

This module is part of the community.general collection (version 7.5.2).

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. You need further requirements to be able to use this module, see Requirements for details.

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

New in community.general 1.0.0

Synopsis

  • Manage launchd services on target macOS hosts.

Aliases: system.launchd

Requirements

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

  • A system managed by launchd

  • The plistlib python library

Parameters

Parameter

Comments

enabled

boolean

Whether the service should start on boot.

At least one of state and enabled are required.

Choices:

  • false

  • true

force_stop

boolean

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 true to let this module change the ‘KeepAlive’ attribute to false.

Choices:

  • false ← (default)

  • true

name

string / required

Name of the service.

state

string

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.

Choices:

  • "reloaded"

  • "restarted"

  • "started"

  • "stopped"

  • "unloaded"

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

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

- 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

Description

status

dictionary

Metadata about service status

Returned: always

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

Authors

  • Martin Migasiewicz (@martinm82)