salt.modules.mac_service module

The service module for macOS .. versionadded:: 2016.3.0

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=u'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 '*' service.get_enabled running=True
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, 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