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.

Parameters

Parameter Choices/Defaults Comments
arguments
-
Additional arguments provided on the command line

aliases: args
enabled
boolean
    Choices:
  • no
  • yes
Whether the service should start on boot. At least one of state and enabled are required.
name
- / required
Name of the service.
pattern
-
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 started.
runlevel
-
Default:
"default"
For OpenRC init scripts (ex: Gentoo) only. The runlevel that this service belongs to.
sleep
-
added in 1.3
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
-
    Choices:
  • reloaded
  • restarted
  • started
  • stopped
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
 Default:
"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.

Notes

Note

  • For Windows targets, use the win_service module instead.

Examples

- name: Start service httpd, if not started
  service:
    name: httpd
    state: started

- name: Stop service httpd, if started
  service:
    name: httpd
    state: stopped

- name: Restart service httpd, in all cases
  service:
    name: httpd
    state: restarted

- name: Reload service httpd, in all cases
  service:
    name: httpd
    state: reloaded

- name: Enable service httpd, and not touch the state
  service:
    name: httpd
    enabled: yes

- name: Start service foo, based on running process /usr/bin/foo
  service:
    name: foo
    pattern: /usr/bin/foo
    state: started

- name: Restart network service for interface eth0
  service:
    name: network
    state: restarted
    args: eth0

Status

Red Hat Support

More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.

Authors

  • Ansible Core Team
  • Michael DeHaan

Hint

If you notice any issues in this documentation you can edit this document to improve it.