service¶

Collection Note

This module is part of the ansible.builtin collection. To install the collection, use:

ansible-galaxy collection install ansible.builtin

Added in version 0.1.

Synopsis¶

Controls services on remote hosts. Supported init systems include BSD init, OpenRC, SysV, Solaris SMF, systemd, upstart.
This module acts as a proxy to the underlying service manager module. While all arguments will be passed to the underlying module, not all modules support the same arguments. This documentation only covers the minimum intersection of module arguments that all service manager modules support.
This module is a proxy for multiple more specific service manager modules (such as M(ansible.builtin.systemd) and M(ansible.builtin.sysvinit)). This allows management of a heterogeneous environment of machines without creating a specific task for each service manager. The module to be executed is determined by the O(use) option, which defaults to the service manager discovered by M(ansible.builtin.setup). If M(ansible.builtin.setup) was not yet run, this module may run it.
For Windows targets, use the M(ansible.windows.win_service) module instead.

Parameters¶

Parameter	Defaults / Choices	Comments
arguments str		Additional arguments provided on the command line. While using remote hosts with systemd this setting will be ignored.
enabled bool		Whether the service should start on boot. At least one of O(state) and O(enabled) are required.
name str required		Name of the service.
pattern str		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 C(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. Version Added: 0.7
runlevel str	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 int		If the service is being V(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. Version Added: 1.3
state str	Choices: reloaded, restarted, started, stopped	V(started)/V(stopped) are idempotent actions that will not run commands unless necessary. V(restarted) will always bounce the service. V(reloaded) will always reload. At least one of O(state) and O(enabled) are required. Note that V(reloaded) will start the service if it is not already started, even if your chosen init system wouldn't normally.
use str	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 C(ansible_service_mgr) fact and falls back to the C(ansible.legacy.service) module when none matching is found. The 'old service module' still uses autodetection and in no way does it correspond to the C(service) command. Version Added: 2.2

Notes¶

Note

For AIX, group subsystem names can be used.
The C(service) command line utility is not part of any service manager system but a convenience. It does not have a standard implementation across systems, and this action cannot use it directly. Though it might be used if found in certain circumstances, the detected system service manager is normally preferred.

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