## 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.