Documentation

service - Manage services.

Synopsis

  • Controls services on remote hosts. Supported init systems include BSD init, OpenRC, SysV, Solaris SMF, systemd, upstart.
  • For Windows targets, use the win_service module instead.

Options

parameter required default choices comments
arguments
 no
Additional arguments provided on the command line

aliases: args
enabled
 no
  • yes
  • no
Whether the service should start on boot. At least one of state and enabled are required.
name
 yes
Name of the service.
pattern
 no
If the service does not respond to the status command, name a substring to look for as would be found in the output of the ps command as a stand-in for a status result. If the string is found, the service will be assumed to be running.
runlevel
 no default
For OpenRC init scripts (ex: Gentoo) only. The runlevel that this service belongs to.
sleep
(added in 1.3)
 no
If the service is being restarted then sleep this many seconds between the stop and start command. This helps to workaround badly behaving init scripts that exit immediately after signaling a process to stop.
state
 no
  • started
  • stopped
  • restarted
  • reloaded
started/stopped are idempotent actions that will not run commands unless necessary. restarted will always bounce the service. reloaded will always reload. At least one of state and enabled are required. Note that reloaded will start the service if it is not already started, even if your chosen init system wouldn't normally.
use
(added in 2.2)
 no auto
The service module actually uses system specific modules, normally through auto detection, this setting can force a specific module.
Normally it uses the value of the 'ansible_service_mgr' fact and falls back to the old 'service' module when none matching is found.

Examples

# Example action to start service httpd, if not running
- service:
    name: httpd
    state: started

# Example action to stop service httpd, if running
- service:
    name: httpd
    state: stopped

# Example action to restart service httpd, in all cases
- service:
    name: httpd
    state: restarted

# Example action to reload service httpd, in all cases
- service:
    name: httpd
    state: reloaded

# Example action to enable service httpd, and not touch the running state
- service:
    name: httpd
    enabled: yes

# Example action to start service foo, based on running process /usr/bin/foo
- service:
    name: foo
    pattern: /usr/bin/foo
    state: started

# Example action to restart network service for interface eth0
- service:
    name: network
    state: restarted
    args: eth0

Notes

Note

  • For Windows targets, use the win_service module instead.

Status

This module is flagged as stableinterface which means that the maintainers for this module guarantee that no backward incompatible interface changes will be made.

Maintenance Info

For more information about Red Hat’s this support of this module, please refer to this knowledge base article<https://access.redhat.com/articles/rhel-top-support-policies>

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.