Troubleshooting¶
Incident-response checklist¶
- Determine scope: one service, one host, or network-wide.
- Check DNS before changing applications.
- Test the proxy and the upstream separately.
- Review container and host logs.
- Confirm resource pressure in metrics.
- Stop automated restarts if diagnosis requires stability.
- Document cause, action and follow-up.
Useful validation steps are in the validation sequence and the Caddy change procedure.
Incident log template (mock)¶
MOCK EXAMPLE, illustrative, not a real incident
The entry below is a template built only from components described in the manual. It does not record an actual event.
Summary¶
| Field | Value |
|---|---|
| Incident ID | MOCK-001 |
| Scope | One service (primary AdGuard Home instance) |
| Impact | None expected for clients; redundant instance continued DNS |
Incident Timeline¶
| Step | Event |
|---|---|
| 1 | The primary AdGuard Home instance stops answering. |
| 2 | The redundant AdGuard Home instance continues serving DNS; the service FQDN still resolves to Caddy. |
| 3 | The scheduled health script detects the failure on its next run (process state and DNS lookup check). |
| 4 | The script restarts the workload and increments the failure counter (first and second failures). |
| 5 | If the third consecutive failure occurs, automated recovery stops and a notification is sent; the counter remains for investigation. |
| 6 | Operator follows the incident-response checklist and validates DNS, proxy and upstream separately. |
Root Cause Analysis¶
Illustrative only: the primary instance failed its protocol-specific DNS
check (DNS resolution failed on port 53). Process state alone would not have
shown an application-layer failure, which is why the script probes the
service directly. Cause would be determined from container and host logs and
confirmed against resource metrics in Grafana.
Remediation¶
- Restore service on the primary instance, rebuilding from the baseline configuration stored on Unraid if required.
- Confirm the two instances are synchronized again.
- Confirm the failure counter has reset and the Prometheus target is healthy.
- Document cause, action and follow-up.