OnBootSec means the trigger resets every time the system powers up. To ensure reliable execution regardless of uptime, you must use monotonic or calendar-based triggers that account for system state changes and sleep cycles properly.
Understanding Timer Persistence and State
When you enable a systemd timer withsystemctl enable mytimer.timer, you are creating a symlink that tells systemd to start that specific timer unit during the boot process. This action does not guarantee that the timer will fire immediately upon login or after waking from suspend; it only guarantees that the timer daemon will be active and listening for events once the system is fully booted. If your timer configuration relies exclusively on OnBootSec=5min, the countdown begins at the moment the service starts during boot. Consequently, if you wait five minutes after logging in, the event fires. However, if the system reboots or suspends, that specific monotonic counter is lost because it is tied to the current kernel uptime, not wall-clock time.
This behavior often leads users to believe the timer is "inactive" or broken. In reality, the timer is functioning exactly as designed by resetting its internal clock whenever the systemd manager restarts. The confusion arises when users expect a one-time delay that persists across reboots, which is not how standard monotonic timers work. For tasks that need to run relative to the last boot, this is fine. But for scheduled maintenance or recurring jobs, monotonic timers are insufficient because they do not survive suspension or unexpected shutdowns gracefully without manual intervention.
Using Calendar-Based Timers for Reliability
The most robust solution for ensuring a timer runs predictably after any reboot or resume is to switch from monotonic triggers to calendar-based specifications. Calendar timers use real-world time formats defined in theOnCalendar= directive within the .timer file. Because these timers rely on the system clock rather than kernel uptime, they are immune to the reset problem associated with OnBootSec. When the system boots, systemd checks the current time against the calendar specification. If the specified time has passed since the last activation, the corresponding service is triggered immediately.
To implement this, edit your timer unit file, typically located in /etc/systemd/system/ or /usr/lib/systemd/system/. Replace any existing OnBootSec= or OnUnitActiveSec= lines with an OnCalendar= entry. For example, to run a job daily at 2:00 AM, you would use OnCalendar=*-*-* 02:00:00. After making changes, reload the daemon with systemctl daemon-reload and restart the timer using systemctl restart mytimer.timer. You can verify the next activation time by running systemctl status mytimer.timer, which will display the precise date and time the service is scheduled to execute next. This method ensures that even if the system was off during the scheduled time, it will trigger as soon as possible after booting, depending on your specific configuration.
Handling Sleep and Resume Scenarios
While calendar timers solve the reboot issue, they can also behave unexpectedly during suspend if not configured correctly. By default, systemd timers are paused during system sleep states like suspend or hibernate. When the system wakes up, the timer resumes counting down from where it left off. For monotonic timers, this pause effectively extends the delay, which might be desirable. However, for calendar timers, if the wake-up time misses the exact second of the scheduled event, the timer might skip that occurrence entirely until the next cycle. To address this, you can configure the timer to activate immediately upon resume if the scheduled time has been missed. AddPersistent=true to the [Timer] section of your timer unit file. This setting tells systemd to check if the timer was supposed to have fired while the system was asleep. If it did, the service is triggered immediately upon resume. This is crucial for backup scripts or cleanup jobs that must happen at specific intervals regardless of whether the machine was sleeping. Without Persistent=true, a calendar timer might silently skip a day's worth of tasks if the computer was powered off during the execution window. Always test this behavior in a non-production environment to ensure it aligns with your operational requirements.
Debugging Common Issues
If your timer still appears inactive after applying these fixes, check the journal logs for errors. Usejournalctl -u mytimer.timer --since "1 hour ago" to see if systemd attempted to start the service but failed due to permission issues or missing dependencies. Another common pitfall is incorrect syntax in the OnCalendar directive. Systemd uses a strict format for calendar specs; a single typo can cause the timer to never match. You can validate your calendar spec using systemd-analyze calendar "your-spec-here", which will output the next few occurrences or return an error if the format is invalid.
Additionally, ensure that the underlying service file is valid and executable. A malformed service file can prevent the timer from triggering successfully, even if the timer unit itself is active. Check the permissions of the script or binary called by the service. It should be executable by the user or root context defined in the service file. If the service fails to start, the timer may remain in an "active (waiting)" state without producing visible results, leading to the assumption that it is inactive. Reviewing the exit codes and standard output of the service via journalctl is the most effective way to diagnose these silent failures.
For more information on managing service execution timing, see Controlling Timing of Execution in *.service File with systemd.
Frequently Asked Questions
Why does my timer fire immediately after reboot?
This usually happens when using a calendar timer with Persistent=true and the system was suspended past the scheduled time. Upon resume, systemd detects the missed window and triggers the service immediately to catch up. Disable persistence if you want to strictly adhere to the original schedule.
Can I use OnBootSec for recurring tasks?
No, OnBootSec is monotonic and resets every time the system boots. It is suitable for one-time delays after startup but cannot guarantee recurring execution over days or weeks because the counter is lost during reboots and sleeps.
How do I check when a timer will next fire?
Run systemctl status yourtimer.timer to see the "Active" state and the "Next Elapsed" or "Next Trigger" timestamp. This output provides the exact date and time systemd plans to activate the associated service.
What causes a systemd timer to show as failed?
A timer shows as failed if the underlying service it triggers exits with a non-zero status code or encounters an error during execution. Check journalctl -u yourservicename.service for detailed error messages regarding permissions, missing files, or runtime exceptions.
Do timers persist across kernel updates?
Yes, systemd timer configurations are stored in unit files on disk and are independent of the kernel version. They will continue to function normally after a kernel update, provided the systemd package itself is updated correctly.