125 lines
3.1 KiB
Markdown
125 lines
3.1 KiB
Markdown
## Timer as a service — quick manual
|
|
|
|
This short guide shows how to set up a systemd timer that runs a job, how to enable/start it, and how to list and inspect existing timers.
|
|
|
|
### Checklist
|
|
- Create a `.service` that performs the work
|
|
- Create a corresponding `.timer` with the schedule
|
|
- Reload systemd, enable and start the timer
|
|
- List timers and inspect logs for failures
|
|
|
|
### Units: example
|
|
System-wide units live under `/etc/systemd/system`. For per-user timers use `~/.config/systemd/user/` and `systemctl --user`.
|
|
|
|
Create `/etc/systemd/system/my-job.service`:
|
|
```ini
|
|
[Unit]
|
|
Description=My scheduled job
|
|
|
|
[Service]
|
|
Type=oneshot
|
|
ExecStart=/usr/local/bin/my-job.sh
|
|
```
|
|
|
|
Create `/etc/systemd/system/my-job.timer`:
|
|
```ini
|
|
[Unit]
|
|
Description=Run my-job every day at 02:30
|
|
|
|
[Timer]
|
|
OnCalendar=*-*-* 02:30:00
|
|
Persistent=true
|
|
|
|
[Install]
|
|
WantedBy=timers.target
|
|
```
|
|
|
|
Notes:
|
|
- `Type=oneshot` is appropriate for short scripts that exit.
|
|
- `Persistent=true` makes missed runs (while the machine was down) run on next boot.
|
|
|
|
### Install, enable and start
|
|
After creating or editing unit files run:
|
|
```bash
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable --now my-job.timer
|
|
```
|
|
|
|
For a user timer (no sudo):
|
|
```bash
|
|
systemctl --user daemon-reload
|
|
systemctl --user enable --now my-job.timer
|
|
```
|
|
|
|
### List existing timers
|
|
Show all timers (system):
|
|
```bash
|
|
systemctl list-timers --all
|
|
```
|
|
This shows UNIT, ACTIVATES, NEXT, LEFT, LAST and PASSED columns. `NEXT` is the next trigger time.
|
|
|
|
User timers:
|
|
```bash
|
|
systemctl --user list-timers --all
|
|
```
|
|
|
|
Filter for a specific timer:
|
|
```bash
|
|
systemctl list-timers --all | grep my-job
|
|
systemctl status my-job.timer
|
|
systemctl status my-job.service
|
|
```
|
|
|
|
### Logs and debugging
|
|
View recent service logs:
|
|
```bash
|
|
journalctl -u my-job.service -b
|
|
```
|
|
View timer logs:
|
|
```bash
|
|
journalctl -u my-job.timer -b
|
|
```
|
|
|
|
If the job never ran, check:
|
|
- `systemctl status my-job.timer` for errors
|
|
- `ExecStart` path and executable permissions
|
|
- run the `ExecStart` command manually to verify behavior
|
|
- `OnCalendar` syntax (see `man systemd.time`)
|
|
|
|
Common fixes:
|
|
- `sudo systemctl daemon-reload` after edits
|
|
- ensure `my-job.service` is reachable and executable by the user that runs it
|
|
- for user timers, make sure the user session is running or enable linger if run outside a login session
|
|
|
|
### Helpful examples
|
|
Run the job 10 seconds after boot and every 5 minutes:
|
|
```ini
|
|
[Timer]
|
|
OnBootSec=10s
|
|
OnUnitActiveSec=5min
|
|
Persistent=true
|
|
```
|
|
|
|
Use environment variables inside the service:
|
|
```ini
|
|
[Service]
|
|
Environment=ENVIRONMENT=production
|
|
EnvironmentFile=/etc/default/my-job
|
|
```
|
|
|
|
### Remove or disable a timer
|
|
```bash
|
|
sudo systemctl disable --now my-job.timer
|
|
sudo rm /etc/systemd/system/my-job.timer /etc/systemd/system/my-job.service
|
|
sudo systemctl daemon-reload
|
|
```
|
|
|
|
### Quick troubleshooting checklist
|
|
- Confirm unit files are syntactically correct
|
|
- Check permissions and shebang on the script
|
|
- `journalctl -u <unit>` for errors
|
|
- For user timers: check `systemctl --user status` and enable linger with `loginctl enable-linger <user>` if needed
|
|
|
|
---
|
|
This file provides a compact reference; tell me if you want a tailored example script and a ready-to-install pair of units added to the repo.
|