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 withsudo 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=3minmeans the timer will run 3 minutes after the system boots.OnUnitActiveSec=5minmeans the script will be run every 5 minutes after its last execution.
Note: systemd does not support inline comments. A
# commentplaced 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:
- Check the physical network. The script finds the default gateway (your router) with
ip routeand pings it. It deliberately does not ping an internet address like8.8.8.8, because whenAllowedIPs = 0.0.0.0/0that 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. - Check the WireGuard service. If
wg-quick@wg0is not active, for example because it failed at boot when the network was not ready, the script starts it. - 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. - 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 restartswg-quick@wg0. A restart also forces theEndpointhostname to be resolved again, which fixes the case where a DDNS address changed during the outage.
- If the last handshake is recent (within
Note: this logic relies on
PersistentKeepalive = 25in the[Peer]section ofwg0.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 withalready 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.