Running a Service at Fixed Intervals on Debian

There are many ways to run a service at fixed intervals on Debian, such as: cron, anacron, systemd timers, at, and sleep loop.

This guide uses a systemd timer to run a script that keeps WireGuard (wg0) connected.

Important: the script calls systemctl, which needs root privileges. Install the service and timer as system units (in /etc/systemd/system/, managed with sudo systemctl ...). Do not install them as user units (systemctl --user), or the script will fail with permission errors.

0. Prerequisites

Make sure the WireGuard interface is managed by systemd and starts on boot:

sudo systemctl enable --now wg-quick@wg0

From now on, always control WireGuard with systemctl start|stop|restart wg-quick@wg0. Avoid running wg-quick up/down wg0 by hand (see Troubleshooting).

1. Create the script (if it doesn’t exist)

Make sure you have your script ready. For example, wg-auto-reconnect.sh as shown at the end of this article:

sudo nano /usr/local/bin/wg-auto-reconnect.sh

Paste the script content and grant it execute permissions:

sudo chmod +x /usr/local/bin/wg-auto-reconnect.sh

2. Create a Systemd Service

Create a systemd service file for the script.

sudo nano /etc/systemd/system/wg-auto-reconnect.service

Paste the following content:

[Unit]
Description=Auto reconnect WireGuard if no internet connection
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/wg-auto-reconnect.sh

Type=oneshot is the right type here because the script runs to completion and exits. No User= is set, so the service runs as root.

3. Create a Systemd Timer

Now, create a systemd timer file to activate the service at the desired interval.

sudo nano /etc/systemd/system/wg-auto-reconnect.timer

Add the following content:

[Unit]
Description=Run WireGuard auto-reconnect script every 5 minutes

[Timer]
OnBootSec=3min
OnUnitActiveSec=5min

[Install]
WantedBy=timers.target

In this example:

  • OnBootSec=3min means the timer will run 3 minutes after the system boots.
  • OnUnitActiveSec=5min means the script will be run every 5 minutes after its last execution.

Note: systemd does not support inline comments. A # comment placed after a value on the same line becomes part of that value and can break the unit. Put comments on their own line instead.

4. Enable and Start the Timer

Reload the systemd daemon to recognize the new service and timer:

sudo systemctl daemon-reload

Enable and start the timer in one command:

sudo systemctl enable --now wg-auto-reconnect.timer

5. Check the Timer’s Status

To ensure the timer is working, you can check its status:

sudo systemctl status wg-auto-reconnect.timer
systemctl list-timers | grep wg-auto

This shows whether the timer is active (waiting) and when it will trigger next.

To see what the script did on previous runs, read the service log (use sudo, otherwise some journal files cannot be opened):

sudo journalctl -u wg-auto-reconnect.service -n 30 --no-pager

6. Manual Activation

If you want to test the script immediately without waiting for the timer, you can activate the service manually:

sudo systemctl start wg-auto-reconnect.service
sudo journalctl -u wg-auto-reconnect.service -n 20 --no-pager

Script (wg-auto-reconnect.sh)

The script runs once each time the timer fires and goes through these checks in order:

  1. Check the physical network. The script finds the default gateway (your router) with ip route and pings it. It deliberately does not ping an internet address like 8.8.8.8, because when AllowedIPs = 0.0.0.0/0 that ping travels through the tunnel and gives misleading results. If the gateway is unreachable (for example, the router is still booting after a power outage), the script exits and waits for the next run.
  2. Check the WireGuard service. If wg-quick@wg0 is not active, for example because it failed at boot when the network was not ready, the script starts it.
  3. Check the handshake. The service being active only means the interface was created, not that the tunnel works. The script reads the time of the latest handshake with wg show wg0 latest-handshakes.
  4. Decide.
    • If the last handshake is recent (within MAX_AGE, 180 seconds by default), WireGuard is healthy and the script does nothing.
    • If there has never been a handshake, or the last one is older than MAX_AGE, the tunnel is considered dead and the script restarts wg-quick@wg0. A restart also forces the Endpoint hostname to be resolved again, which fixes the case where a DDNS address changed during the outage.

Note: this logic relies on PersistentKeepalive = 25 in the [Peer] section of wg0.conf. Without it, the handshake becomes stale whenever there is no traffic, and the script would restart a healthy tunnel.

Troubleshooting

Error: wg-quick: `wg0' already exists

wg-quick@wg0 is a oneshot unit with RemainAfterExit=yes, so systemd only knows about start/stop actions it performed itself. If a script or you run wg-quick up/down wg0 directly, the two get out of sync:

  • The interface is up but systemd reports inactive: the script tries to start it again and fails with already exists.
  • The interface is down but systemd reports active: the script thinks WireGuard is running and never brings it back.

To recover, restart the service so both sides agree again:

sudo systemctl restart wg-quick@wg0

Then make sure everything (scripts included) uses systemctl instead of calling wg-quick directly.

The timer runs but nothing happens

  • Confirm the units are in /etc/systemd/system/ and not in ~/.config/systemd/user/.
  • Confirm the script is executable: ls -l /usr/local/bin/wg-auto-reconnect.sh.
  • Check the log: sudo journalctl -u wg-auto-reconnect.service -n 30 --no-pager.