Ansible service Module: Start, Stop, Restart Services (Complete Guide)
By Luca Berton · Published 2024-01-01 · Category: installation
How to manage services with Ansible service and systemd modules. Start, stop, restart, enable services.
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: startedStop a Service
- name: Stop nginx
ansible.builtin.service:
name: nginx
state: stoppedRestart a Service
- name: Restart nginx
ansible.builtin.service:
name: nginx
state: restartedReload a Service
- name: Reload nginx configuration
ansible.builtin.service:
name: nginx
state: reloadedEnable at Boot
- name: Enable nginx on boot
ansible.builtin.service:
name: nginx
enabled: trueStart and Enable Together
- name: Ensure nginx is running and enabled
ansible.builtin.service:
name: nginx
state: started
enabled: trueansible.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: trueManage User Services
- name: Start user-level service
ansible.builtin.systemd:
name: myapp
state: started
scope: userMask/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: falseSee 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: reloadedManaging 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
- bluetoothSee 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: 30service 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 |
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
Category: installation