salt.modules.mac_service module¶

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.

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

Generated on August 05, 2021 at 04:04:00 UTC.

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

saltstack.com