Ansible service Module Tutorial + Examples


Percy Grunwald's Profile Picture

Written by Percy Grunwald

— Last Updated February 22, 2019

What does the Ansible service module do?

Ansible’s service module controls services on remote hosts and is useful for these common tasks:

  • Start, stop or restart a service on a remote host
- name: ensure nginx service is started
  service:
    name: nginx
    state: started
  become: true
- name: ensure nginx service is stopped
  service:
    name: nginx
    state: stopped
  become: true
- name: restart the nginx service
  service:
    name: nginx
    state: restarted
  become: true
  • Ensure that a service is started on system boot
- name: ensure nginx service is started and also starts on boot
  service:
    name: nginx
    state: started
    enabled: true
  become: true

You will usually need to set become: true when using the service module because root or superuser permissions are required when managing services on most systems.

The service module supports BSD init, OpenRC, SysV, Solaris SMF, systemd, upstart.

Examples

How to start a service

Set the name parameter to the service name and the state parameter to started to start a service. If the service is already running, Ansible will do nothing.

- name: ensure nginx service is started
  service:
    name: nginx
    state: started
  become: true

How to stop a service

Set the name parameter to the service name and the state parameter to stopped to stop a service. If the service is not running, Ansible will do nothing.

- name: ensure nginx service is stopped
  service:
    name: nginx
    state: stopped
  become: true

How to restart a service

Set the name parameter to the service name and the state parameter to restarted to restart a service.

- name: restart the nginx service
  service:
    name: nginx
    state: restarted
  become: true

How to restart multiple services in a loop

Use the loop keyword and {{ item }} to restart multiple services in a loop.

- name: restart multiple services in a loop
  service:
    name: "{{ item }}"
    state: started
    enabled: true
  become: true
  loop:
    - nginx
    - rsyslog

How to ensure a service starts on boot/reboot

Set the name parameter to the service name and the enabled parameter to true to ensure a service starts on system boot/reboot. It’s possible to set the state and enabled parameters at the same time.

- name: ensure nginx service is started and also starts on boot/reboot
  service:
    name: nginx
    state: started
    enabled: true
  become: true

How to capture service module output

Use the register keyword to capture the output of the service module.

- name: ensure nginx service is started and also starts on boot
  service:
    name: nginx
    state: started
    enabled: true
  become: true
  register: service_output

- debug: var=service_output

The debug task above will output the following:

ok: [123.123.123.123] => {
    "service_output": {
        "changed": true,
        "enabled": true,
        "failed": false,
        "name": "nginx",
        "state": "started",
        "status": {...}
    }
}

How to capture service module output from a loop

When using the service module in a loop, the output of each item in the loop will go into the results key of the registered variable.

- name: restart multiple services in a loop
  service:
    name: "{{ item }}"
    state: started
    enabled: true
  become: true
  register: service_output
  loop:
    - nginx
    - rsyslog

- debug: var=service_output
ok: [123.123.123.123] => {
    "service_output": {
        "changed": false,
        "msg": "All items completed",
        "results": [
            {
                ...
                "changed": false,
                "enabled": true,
                "failed": false,
                "invocation": {...},
                "item": "nginx",
                "name": "nginx",
                "state": "started",
                "status": {...}
            },
            {
                ...
                "changed": false,
                "enabled": true,
                "failed": false,
                "invocation": {...},
                "item": "rsyslog",
                "name": "rsyslog",
                "state": "started",
                "status": {...}
            }
        ]
    }
}

Further reading

Ansible service Module on Ansible Docs

Comments