Restart Services

When to use it

After you change a configuration file, deploy code that needs a service restarted, or find a service stopped. It is the safe replacement for typing systemctl restart on each server: every name is checked first, each configuration is tested before the service is touched, and the run stops at the first service that does not come back.

Choosing the options

Services — the systemd unit names, one per line or separated by commas, in the order you want them restarted. Use the name systemctl knows, such as nginx, php8.3-fpm (Ubuntu and Debian) or php-fpm (RHEL family), mariadb, redis-server (Ubuntu and Debian) or redis (RHEL family). The .service suffix is optional.

How

• Restart stops and starts each service. Use it after installing a new version or when a service is stuck.
• Reload if the service supports it, otherwise restart re-reads the configuration without dropping connections where the service can do that, as nginx, PHP-FPM and HAProxy can. Use it for configuration changes on a live site.

Put the service that depends on others last. For a PHP site behind nginx, restart php8.3-fpm first and nginx second.

What it does on the server

1. Checks that every name is a service that exists. Sockets, timers, targets and mounts are refused: only services are restarted. If one name fails, nothing is restarted.
2. Refuses services whose restart can cut the server off or break every session: the network (networking, NetworkManager, systemd-networkd, wicked, netplan), firewalls (firewalld, ufw, nftables, iptables, netfilter-persistent, csf, lfd) and the service manager's own plumbing (dbus, systemd-logind, systemd-udevd, polkit). SSH itself can be restarted: its configuration is tested first.
3. Runs the service's own configuration test where it has one: nginx -t, apache2ctl configtest or apachectl configtest, sshd -t, PHP-FPM's -t with the exact binary systemd starts, haproxy -c, postfix check, named-checkconf, and dockerd --validate when /etc/docker/daemon.json exists. A failed test stops the run while the service is still running with its old configuration.
4. Restarts or reloads each service in order and waits for it to report active. A service that was stopped is started.

After the run

Each service's line in the run output says whether it was restarted, reloaded or started. If a later service was not reached, the output lists it under "Not restarted".

Common problems

"There is no service called … on this server. Nothing was restarted." — The unit name is wrong for this distribution. Check it on the server with systemctl list-units --type=service. PHP-FPM is php8.3-fpm on Ubuntu and Debian and php-fpm on the RHEL family.

"… was not restarted: its configuration test failed (above)." — The test output above the error names the file and line. Fix the configuration, then run the playbook again. The service kept running with its previous configuration.

"… is not restarted by this playbook" — The service runs the network, a firewall or the service manager itself. Change firewall rules with Advanced Security, which checks that SSH stays reachable; restart the others from your provider's console.

"… is not a service. This playbook restarts services only." — You named a socket, timer or target. Name the service it starts instead, for example nginx rather than nginx.socket.

"… did not come back after the restart." — The service failed to start. The status and last log lines are in the output. The services after it were not touched and are listed.