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