W3cubDocs

/Ansible

community.general.launchd module – Manage macOS services

Note

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

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.

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 causes 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.

plist

string

added in community.general 10.1.0

Name of the .plist file for the service.

Defaults to {name}.plist.

state

string

started/stopped are idempotent actions that do not run commands unless necessary.

launchd does not support restarted nor reloaded natively. These states 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

- name: restart sshd
  community.general.launchd:
    name: com.openssh.sshd
    plist: ssh.plist
    state: restarted

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)

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