salt.modules.mac_service module

The service module for macOS

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/

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

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

Parameters:	name (str) -- Used to find the service from launchctl. Can be any part of the service name or a regex expression. sig (str) -- Find the service with status.pid instead. Note that name must still be provided. runas (str) -- User to run launchctl commands
Returns:	The PID for the service if it is running, or 'loaded' if the service should not always have a PID, or otherwise an empty string
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