W3cubDocs

/Ansible 2.11

ansible.builtin.service – Manage services

Note

This module is part of ansible-base and included in all Ansible installations. In most cases, you can use the short module name service even without specifying the collections: keyword. Despite that, we recommend you use the FQCN for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.

New in version 0.1: of ansible.builtin

Synopsis

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

Note

This module has a corresponding action plugin.

Parameters

Parameter Choices/Defaults Comments
arguments
string
Additional arguments provided on the command line.
While using remote hosts with systemd this setting will be ignored.

aliases: args
enabled
boolean
    Choices:
  • no
  • yes
Whether the service should start on boot.
At least one of state and enabled are required.
name
string / required
Name of the service.
pattern
string
added in 0.7 of ansible.builtin
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.
While using remote hosts with systemd this setting will be ignored.
runlevel
string
Default:
"default"
For OpenRC init scripts (e.g. Gentoo) only.
The runlevel that this service belongs to.
While using remote hosts with systemd this setting will be ignored.
sleep
integer
added in 1.3 of ansible.builtin
If the service is being restarted then sleep this many seconds between the stop and start command.
This helps to work around badly-behaving init scripts that exit immediately after signaling a process to stop.
Not all service managers support sleep, i.e when using systemd this setting will be ignored.
state
string
    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
string
added in 2.2 of ansible.builtin
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 AIX, group subsystem names can be used.
  • Supports check_mode.

See Also

See also

ansible.windows.win_service

The official documentation on the ansible.windows.win_service module.

Examples

- name: Start service httpd, if not started
  ansible.builtin.service:
    name: httpd
    state: started

- name: Stop service httpd, if started
  ansible.builtin.service:
    name: httpd
    state: stopped

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

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

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

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

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

Authors

  • Ansible Core Team
  • Michael DeHaan

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.11/collections/ansible/builtin/service_module.html