The service module for macOS
Added 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.
Check that the given service is available.
name (str) -- The name of the service
True if the service is available, otherwise False
bool
CLI Example:
salt '*' service.available com.openssh.sshd
Disable a launchd service. Raises an error if the service fails to be disabled
name (str) -- Service label, file name, or full path
runas (str) -- User to run launchctl commands
True
if successful or if the service is already disabled
bool
CLI Example:
salt '*' service.disable org.cups.cupsd
Check if the specified service is not enabled. This is the opposite of
service.enabled
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.
True if the specified service is NOT enabled, otherwise False
bool
CLI Example:
salt '*' service.disabled org.cups.cupsd
Enable a launchd service. Raises an error if the service fails to be enabled
name (str) -- Service label, file name, or full path
runas (str) -- User to run launchctl commands
True
if successful or if the service is already enabled
bool
CLI Example:
salt '*' service.enable org.cups.cupsd
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.
name (str) -- The name of the service to look up.
runas (str) -- User to run launchctl commands.
True if the specified service enabled, otherwise False
bool
CLI Example:
salt '*' service.enabled org.cups.cupsd
Return a list of services that are enabled or available. Can be used to find the name of a service.
runas (str) -- User to run launchctl commands
A list of all the services available or enabled
list
CLI Example:
salt '*' service.get_all
Return a list of all services that are enabled. Can be used to find the name of a service.
runas (str) -- User to run launchctl commands
A list of all the services enabled on the system
list
CLI Example:
salt '*' service.get_enabled
Run a launchctl command and raise an error if it fails
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
True
if successful, raise CommandExecutionError
if not, or
the stdout of the launchctl command if requested
bool, str
CLI Example:
salt '*' service.launchctl debug org.cups.cupsd
Run launchctl list and return the output
name (str) -- The name of the service to list
runas (str) -- User to run launchctl commands
If a name is passed returns information about the named service, otherwise returns a list of all services and pids
str
CLI Example:
salt '*' service.list
salt '*' service.list org.cups.cupsd
Check if the specified service is loaded.
name (str) -- The name of the service to look up
runas (str) -- User to run launchctl commands
True
if the specified service is loaded, otherwise False
bool
CLI Example:
salt '*' service.loaded org.cups.cupsd
The inverse of service.available Check that the given service is not available.
name (str) -- The name of the service
True if the service is not available, otherwise False
bool
CLI Example:
salt '*' service.missing com.openssh.sshd
Unloads and reloads a launchd service. Raises an error if the service fails to reload
name (str) -- Service label, file name, or full path
runas (str) -- User to run launchctl commands
True
if successful
bool
CLI Example:
salt '*' service.restart org.cups.cupsd
Show properties of a launchctl service
name (str) -- Service label, file name, or full path
The service information if the service is found
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
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.
name (str) -- Service label, file name, or full path
runas (str) -- User to run launchctl commands
True
if successful or if the service is already running
bool
CLI Example:
salt '*' service.start org.cups.cupsd
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.
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.
True if running, otherwise False.
str
CLI Example:
salt '*' service.status cups
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
name (str) -- Service label, file name, or full path
runas (str) -- User to run launchctl commands
True
if successful or if the service is already stopped
bool
CLI Example:
salt '*' service.stop org.cups.cupsd