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

Generated on December 18, 2024 at 17:29:25 UTC.

You are viewing docs for the latest stable release, 3007.1. Switch to docs for the previous stable release, 3006.9, or to a recent doc build from the master branch.

saltproject.io