Ansible service Module: Start, Stop, Restart Services (Complete Guide)

Ansible service Module: Start, Stop, Restart Services (Complete Guide)

The ansible.builtin.service and ansible.builtin.systemd modules manage services across Linux hosts. Start, stop, restart, and enable services at boot — all idempotently.

See also: Ansible service Module: Start, Stop & Restart Services (ansible.builtin.service)

ansible.builtin.service — Generic Service Management

The service module works across init systems (systemd, SysVinit, Upstart, OpenRC).

Start a Service

- name: Ensure nginx is started
  ansible.builtin.service:
    name: nginx
    state: started

Stop a Service

- name: Stop nginx
  ansible.builtin.service:
    name: nginx
    state: stopped

Restart a Service

- name: Restart nginx
  ansible.builtin.service:
    name: nginx
    state: restarted

Reload a Service

- name: Reload nginx configuration
  ansible.builtin.service:
    name: nginx
    state: reloaded

Enable at Boot

- name: Enable nginx on boot
  ansible.builtin.service:
    name: nginx
    enabled: true

Start and Enable Together

- name: Ensure nginx is running and enabled
  ansible.builtin.service:
    name: nginx
    state: started
    enabled: true

ansible.builtin.systemd — Systemd-Specific

Use systemd when you need systemd-specific features like daemon_reload.

Daemon Reload

- name: Deploy custom service unit
  ansible.builtin.template:
    src: myapp.service.j2
    dest: /etc/systemd/system/myapp.service
  notify: restart myapp
- name: Reload systemd daemon
  ansible.builtin.systemd:
    daemon_reload: true
- name: Start custom service
  ansible.builtin.systemd:
    name: myapp
    state: started
    enabled: true

Manage User Services

- name: Start user-level service
  ansible.builtin.systemd:
    name: myapp
    state: started
    scope: user

Mask/Unmask Services

- name: Mask a service (prevent starting)
  ansible.builtin.systemd:
    name: cups
    masked: true
- name: Unmask a service
  ansible.builtin.systemd:
    name: cups
    masked: false

See also: Ansible on Arch Linux Automation Complete Guide

Using Handlers for Service Restarts

The best practice is to use handlers — they only restart when a change actually occurs.

- hosts: webservers
  become: true
  tasks:
    - name: Deploy nginx config
      ansible.builtin.template:
        src: nginx.conf.j2
        dest: /etc/nginx/nginx.conf
        validate: nginx -t -c %s
      notify: restart nginx
- name: Deploy SSL certificate
      ansible.builtin.copy:
        src: files/ssl/cert.pem
        dest: /etc/nginx/ssl/cert.pem
      notify: reload nginx
handlers:
    - name: restart nginx
      ansible.builtin.service:
        name: nginx
        state: restarted
- name: reload nginx
      ansible.builtin.service:
        name: nginx
        state: reloaded

Managing Multiple Services

- name: Ensure all app services are running
  ansible.builtin.service:
    name: "{{ item }}"
    state: started
    enabled: true
  loop:
    - nginx
    - postgresql
    - redis-server
    - myapp
- name: Stop unnecessary services
  ansible.builtin.service:
    name: "{{ item }}"
    state: stopped
    enabled: false
  loop:
    - cups
    - avahi-daemon
    - bluetooth

See also: Ansible on Debian 12 Bookworm Automation Complete Guide

Check if Service Exists

- name: Get service facts
  ansible.builtin.service_facts:
- name: Start Docker only if installed
  ansible.builtin.service:
    name: docker
    state: started
  when: "'docker.service' in services"

Wait for Service to Be Ready

- name: Start PostgreSQL
  ansible.builtin.service:
    name: postgresql
    state: started
- name: Wait for PostgreSQL to accept connections
  ansible.builtin.wait_for:
    port: 5432
    delay: 2
    timeout: 30

service vs systemd — When to Use Each

| Feature | service | systemd | |---------|---------|---------| | Init system support | All (systemd, SysV, Upstart) | systemd only | | daemon_reload | ❌ | ✅ | | User services (scope) | ❌ | ✅ | | Mask/unmask | ❌ | ✅ | | Portability | High | systemd only |

Rule of thumb: Use ansible.builtin.service for basic start/stop/restart/enable. Use ansible.builtin.systemd when you need daemon_reload, user scope, or masking.

FAQ

How do I restart a service in Ansible?

Use ansible.builtin.service: name=myservice state=restarted. For conditional restarts (only when config changes), use handlers with notify.

What is the difference between service and systemd modules?

ansible.builtin.service is generic and works with any init system. ansible.builtin.systemd is systemd-specific and adds features like daemon_reload, scope: user, and masked. Use service for portability, systemd for systemd-specific features.

How do I enable a service at boot with Ansible?

Set enabled: true on the service or systemd module: ansible.builtin.service: name=nginx enabled=true. Combine with state: started to also start it immediately.

Should I use handlers or direct tasks for service restarts?

Use handlers. They only execute when notified by a changed task, preventing unnecessary restarts. Direct state: restarted runs every time the playbook runs, which is wasteful and can cause downtime.

How do I reload systemd after adding a new service file?

Use ansible.builtin.systemd: daemon_reload=true after copying a .service file to /etc/systemd/system/. This is equivalent to running systemctl daemon-reload.

Conclusion

Service management is a core Ansible capability. Use ansible.builtin.service for portable service control and ansible.builtin.systemd for systemd-specific features. Always use handlers for restart/reload to avoid unnecessary service disruptions.

Related Articles

• Ansible Handlers: Run Tasks on Change • Ansible systemd Module Guide • Ansible wait_for Module