# salt.states.service

## Starting or restarting of services and daemons

Services are defined as system daemons and are typically launched using system init or rc scripts. This service state uses whichever service module is loaded on the minion with the virtualname of `service`. Services can be defined as either running or dead.

If you need to know if your init system is supported, see the list of supported `service modules` for your desired init system (systemd, sysvinit, launchctl, etc.).

Note that Salt's service execution module, and therefore this service state, uses OS grains to ascertain which service module should be loaded and used to execute service functions. As existing distributions change init systems or new distributions are created, OS detection can sometimes be incomplete. If your service states are running into trouble with init system detection, please see the Overriding Virtual Module Providers section of Salt's module documentation to work around possible errors.

For services managed by systemd, the systemd_service module includes a built-in feature to reload the daemon when unit files are changed or extended. This feature is used automatically by the service state and the systemd_service module when running on a systemd minion, so there is no need to set up your own methods of reloading the daemon. If you need to manually reload the daemon for some reason, you can use the `systemd_service.systemctl_reload` function provided by Salt.

Note

The current status of a service is determined by the return code of the init/rc script status command. A status return code of 0 it is considered running. Any other return code is considered dead.

    httpd:
      service.running: []

The service can also be set to start at runtime via the enable option:

    openvpn:
      service.running:
        - enable: True

By default if a service is triggered to refresh due to a watch statement the service is restarted. If the desired behavior is to reload the service, then set the reload value to True:

    redis:
      service.running:
        - enable: True
        - reload: True
        - watch:
          - pkg: redis

Note

More details regarding `watch` can be found in the Requisites documentation.

salt.states.service.dead(name, enable=None, sig=None, init_delay=None, **kwargs)

  Ensure that the named service is dead by stopping the service if it is running

  name

    The name of the init or rc script used to manage the service

  enable

    Set the service to be enabled at boot time, `True` sets the service to be enabled, `False` sets the named service to be disabled. The default is `None`, which does not enable or disable anything.

  sig

    The string to search for when looking for the service process with ps

  init_delay

    Add a sleep command (in seconds) before the check to make sure service is killed.

    Added in version 2017.7.0.

  no_blockFalse

    For systemd minions only. Stops the service using `--no-block`.

    Added in version 2017.7.0.

  timeout

    For Windows minions only.

    The time in seconds to wait for the service to stop before returning. Default is the default for `win_service.stop`.

    Added in version 2017.7.9,2018.3.4.

salt.states.service.disabled(name, **kwargs)

  Ensure that the service is disabled on boot, only use this state if you don't want to manage the running process, remember that if you want to disable a service to use the enable: False option for the running or dead function.

  name

    The name of the init or rc script used to manage the service

salt.states.service.enabled(name, **kwargs)

  Ensure that the service is enabled on boot, only use this state if you don't want to manage the running process, remember that if you want to enable a running service to use the enable: True option for the running or dead function.

  name

    The name of the init or rc script used to manage the service

salt.states.service.masked(name, runtime=False)

  Added in version 2017.7.0.

  Note

  This state is only available on minions which use systemd.

  Ensures that the named service is masked (i.e. prevented from being started).

  name

    Name of the service to mask

  runtimeFalse

    By default, this state will manage an indefinite mask for the named service. Set this argument to `True` to runtime mask the service.

  Note

  It is possible for a service to have both indefinite and runtime masks set for it. Therefore, this state will manage a runtime or indefinite mask independently of each other. This means that if the service is already indefinitely masked, running this state with `runtime` set to `True` will _not_ remove the indefinite mask before setting a runtime mask. In these cases, if it is desirable to ensure that the service is runtime masked and not indefinitely masked, pair this state with a `service.unmasked` state, like so:

      mask_runtime_foo:
        service.masked:
          - name: foo
          - runtime: True

      unmask_indefinite_foo:
        service.unmasked:
          - name: foo
          - runtime: False

salt.states.service.mod_beacon(name, **kwargs)

  Create a beacon to monitor a service based on a beacon state argument.

  Note

  This state exists to support special handling of the `beacon` state argument for supported state functions. It should not be called directly.

salt.states.service.mod_watch(name, sfun=None, sig=None, reload=False, full_restart=False, init_delay=None, force=False, **kwargs)

  The service watcher, called to invoke the watch command. When called, it will restart or reload the named service.

  Note

  This state exists to support special handling of the `watch` requisite. It should not be called directly.

  Parameters for this function should be set by the watching service (e.g. `service.running`).

  name

    The name of the service to control.

  sfun

    The original function which triggered the mod_watch call (service.running, for example).

  sig

    The string to search for when looking for the service process with ps.

  reload

    When set, reload the service instead of restarting it (e.g. `service nginx reload`).

  full_restart

    Perform a full stop/start of a service by passing `--full-restart`. This option is ignored if `reload` is set and is supported by only a few `service modules`.

  force

    Use service.force_reload instead of reload (needs reload to be set to True).

  init_delay

    Add a sleep command (in seconds) before the service is restarted/reloaded.

salt.states.service.running(name, enable=None, sig=None, init_delay=None, **kwargs)

  Ensure that the service is running

  name

    The name of the init or rc script used to manage the service

  enable

    Set the service to be enabled at boot time, `True` sets the service to be enabled, `False` sets the named service to be disabled. The default is `None`, which does not enable or disable anything.

  sig

    The string to search for when looking for the service process with ps

  init_delay

    Some services may not be truly available for a short period after their startup script indicates to the system that they are. Provide an 'init_delay' to specify that this state should wait an additional given number of seconds after a service has started before returning. Useful for requisite states wherein a dependent state might assume a service has started but is not yet fully initialized.

  no_blockFalse

    For systemd minions only. Starts the service using `--no-block`.

    Added in version 2017.7.0.

  timeout

    For Windows minions only.

    The time in seconds to wait for the service to start before returning. Default is the default for `win_service.start`.

    Added in version 2017.7.9,2018.3.4.

  unmaskFalse

    For systemd minions only. Set to `True` to remove an indefinite mask before attempting to start the service.

    Added in version 2017.7.0: In previous releases, Salt would simply unmask a service before making any changes. This behavior is no longer the default.

  unmask_runtimeFalse

    For systemd minions only. Set to `True` to remove a runtime mask before attempting to start the service.

    Added in version 2017.7.0: In previous releases, Salt would simply unmask a service before making any changes. This behavior is no longer the default.

  wait3

    For systemd minions only. Passed through when using `service.status` to determine whether the service is running or not.

    Added in version 2019.2.3.

  Note

  `watch` can be used with service.running to restart a service when

    another state changes ( example: a file.managed state that creates the service's config file ). More details regarding `watch` can be found in the Requisites documentation.

salt.states.service.unmasked(name, runtime=False)

  Added in version 2017.7.0.

  Note

  This state is only available on minions which use systemd.

  Ensures that the named service is unmasked

  name

    Name of the service to unmask

  runtimeFalse

    By default, this state will manage an indefinite mask for the named service. Set this argument to `True` to ensure that the service is runtime masked.

  Note

  It is possible for a service to have both indefinite and runtime masks set for it. Therefore, this state will manage a runtime or indefinite mask independently of each other. This means that if the service is indefinitely masked, running this state with `runtime` set to `True` will _not_ remove the indefinite mask.