# salt.modules.mac_service

The service module for macOS

New in version 2016.3.0.

This module has support for services in the following locations.

    /System/Library/LaunchDaemons/
    /System/Library/LaunchAgents/
    /Library/LaunchDaemons/
    /Library/LaunchAgents/

    # As of version "2019.2.0" support for user-specific services were added.
    /Users/foo/Library/LaunchAgents/

Note

As of the 2019.2.0 release, if a service is located in a `LaunchAgent` path and a `runas` user is NOT specified, the current console user will be used to properly interact with the service.

Note

As of the 3002 release, if a service name of `salt-minion` is passed this module will convert it over to it's macOS equivalent name, in this case to `com.saltstack.salt.minion`. This is true for `salt-master` `salt-api`, and `salt-syndic` as well.

salt.modules.mac_service.available(name)

  Check that the given service is available.

  Parameters:

    name (str) -- The name of the service

  Returns:

    True if the service is available, otherwise False

  Return type:

    bool

  CLI Example:

      salt '*' service.available com.openssh.sshd

salt.modules.mac_service.disable(name, runas=None)

  Disable a launchd service. Raises an error if the service fails to be disabled

  Parameters:

    - name (str) -- Service label, file name, or full path

    - runas (str) -- User to run launchctl commands

  Returns:

    `True` if successful or if the service is already disabled

  Return type:

    bool

  CLI Example:

      salt '*' service.disable org.cups.cupsd

salt.modules.mac_service.disabled(name, runas=None, domain='system')

  Check if the specified service is not enabled. This is the opposite of `service.enabled`

  Parameters:

    - name (str) -- The name to look up

    - runas (str) -- User to run launchctl commands

    - domain (str) -- domain to check for disabled services. Default is system.

  Returns:

    True if the specified service is NOT enabled, otherwise False

  Return type:

    bool

  CLI Example:

      salt '*' service.disabled org.cups.cupsd

salt.modules.mac_service.enable(name, runas=None)

  Enable a launchd service. Raises an error if the service fails to be enabled

  Parameters:

    - name (str) -- Service label, file name, or full path

    - runas (str) -- User to run launchctl commands

  Returns:

    `True` if successful or if the service is already enabled

  Return type:

    bool

  CLI Example:

      salt '*' service.enable org.cups.cupsd

salt.modules.mac_service.enabled(name, runas=None)

  Check if the specified service is enabled (not disabled, capable of being loaded/bootstrapped).

  Note

  Previously this function would see if the service is loaded via `launchctl list` to determine if the service is enabled. This was not an accurate way to do so. The new behavior checks to make sure its not disabled to determine the status. Please use `service.loaded` for the previous behavior.

  Parameters:

    - name (str) -- The name of the service to look up.

    - runas (str) -- User to run launchctl commands.

  Returns:

    True if the specified service enabled, otherwise False

  Return type:

    bool

  CLI Example:

      salt '*' service.enabled org.cups.cupsd

salt.modules.mac_service.get_all(runas=None)

  Return a list of services that are enabled or available. Can be used to find the name of a service.

  Parameters:

    runas (str) -- User to run launchctl commands

  Returns:

    A list of all the services available or enabled

  Return type:

    list

  CLI Example:

      salt '*' service.get_all

salt.modules.mac_service.get_enabled(runas=None)

  Return a list of all services that are enabled. Can be used to find the name of a service.

  Parameters:

    runas (str) -- User to run launchctl commands

  Returns:

    A list of all the services enabled on the system

  Return type:

    list

  CLI Example:

      salt '*' service.get_enabled

salt.modules.mac_service.launchctl(sub_cmd, *args, **kwargs)

  Run a launchctl command and raise an error if it fails

  Parameters:

    - sub_cmd (str) -- Sub command supplied to launchctl

    - args (tuple) -- Tuple containing additional arguments to pass to launchctl

    - kwargs (dict) -- Dictionary containing arguments to pass to `cmd.run_all`

    - return_stdout (bool) -- A keyword argument. If true return the stdout of the launchctl command

  Returns:

    `True` if successful, raise `CommandExecutionError` if not, or the stdout of the launchctl command if requested

  Return type:

    bool, str

  CLI Example:

      salt '*' service.launchctl debug org.cups.cupsd

salt.modules.mac_service.list_(name=None, runas=None)

  Run launchctl list and return the output

  Parameters:

    - name (str) -- The name of the service to list

    - runas (str) -- User to run launchctl commands

  Returns:

    If a name is passed returns information about the named service, otherwise returns a list of all services and pids

  Return type:

    str

  CLI Example:

      salt '*' service.list
      salt '*' service.list org.cups.cupsd

salt.modules.mac_service.loaded(name, runas=None)

  Check if the specified service is loaded.

  Parameters:

    - name (str) -- The name of the service to look up

    - runas (str) -- User to run launchctl commands

  Returns:

    `True` if the specified service is loaded, otherwise `False`

  Return type:

    bool

  CLI Example:

      salt '*' service.loaded org.cups.cupsd

salt.modules.mac_service.missing(name)

  The inverse of service.available Check that the given service is not available.

  Parameters:

    name (str) -- The name of the service

  Returns:

    True if the service is not available, otherwise False

  Return type:

    bool

  CLI Example:

      salt '*' service.missing com.openssh.sshd

salt.modules.mac_service.restart(name, runas=None)

  Unloads and reloads a launchd service. Raises an error if the service fails to reload

  Parameters:

    - name (str) -- Service label, file name, or full path

    - runas (str) -- User to run launchctl commands

  Returns:

    `True` if successful

  Return type:

    bool

  CLI Example:

      salt '*' service.restart org.cups.cupsd

salt.modules.mac_service.show(name)

  Show properties of a launchctl service

  Parameters:

    name (str) -- Service label, file name, or full path

  Returns:

    The service information if the service is found

  Return type:

    dict

  CLI Example:

      salt '*' service.show org.cups.cupsd  # service label
      salt '*' service.show org.cups.cupsd.plist  # file name
      salt '*' service.show /System/Library/LaunchDaemons/org.cups.cupsd.plist  # full path

salt.modules.mac_service.start(name, runas=None)

  Start a launchd service. Raises an error if the service fails to start

  Note

  To start a service in macOS the service must be enabled first. Use `service.enable` to enable the service.

  Parameters:

    - name (str) -- Service label, file name, or full path

    - runas (str) -- User to run launchctl commands

  Returns:

    `True` if successful or if the service is already running

  Return type:

    bool

  CLI Example:

      salt '*' service.start org.cups.cupsd

salt.modules.mac_service.status(name, sig=None, runas=None)

  Return the status for a service.

  Note

  Previously this function would return a PID for a running service with a PID or 'loaded' for a loaded service without a PID. This was changed to have better parity with other service modules that return True/False.

  Parameters:

    - name (str) -- Used to find the service from launchctl. Can be the service Label, file name, or path to the service file. (normally a plist)

    - sig (str) -- Find the service with status.pid instead. Note that `name` must still be provided.

    - runas (str) -- User to run launchctl commands.

  Returns:

    True if running, otherwise False.

  Return type:

    str

  CLI Example:

      salt '*' service.status cups

salt.modules.mac_service.stop(name, runas=None)

  Stop a launchd service. Raises an error if the service fails to stop

  Note

  Though `service.stop` will unload a service in macOS, the service will start on next boot unless it is disabled. Use `service.disable` to disable the service

  Parameters:

    - name (str) -- Service label, file name, or full path

    - runas (str) -- User to run launchctl commands

  Returns:

    `True` if successful or if the service is already stopped

  Return type:

    bool

  CLI Example:

      salt '*' service.stop org.cups.cupsd