Reload guard.yaml without losing the bounties

systemctl reload guard, guard reload or SIGHUP reads the configuration
again: a watch keeps its bounties and counts under the same name and
takes its new settings at once; its source starts again only if it
changed; watches gone stop, new ones start; a file with a mistake is
refused. The Housecarl connection, state, socket and log wait for a
restart, and guard reload says so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/cli.md

@@ -12,6 +12,7 @@ One binary is the daemon and its tools. Every command reads
 | `guard presets [PRESET]` | the presets, or one's patterns |
 | `guard test WATCH [FILE\|-] [--lines N] [--all]` | what a watch's patterns find in a log, and whom they would ban ([presets.md](presets.md)) |
 | `guard status` | the running Guard: each watch's lines, matches, bans and highest bounties, the recent bans and why any failed, and bans waiting for Housecarl. Asks the socket: as root or the guard user |
+| `guard reload` | make the running Guard read guard.yaml again, keeping its bounties, and show what changed (as `systemctl reload guard` does; [configuration.md](configuration.md#reloading)). Asks the socket |
 | `guard bans [--list L]` | the ban list's active bans, from Housecarl |
 | `guard ban ADDRESS [--list L] [--protocol tcp --port 22]... [--time 1d] [--reason R]` | ban by hand |
 | `guard unban ADDRESS [--list L]` | lift an address's bans |

docs/configuration.md

@@ -3,8 +3,9 @@
 `/etc/guard/guard.yaml` is Guard's whole configuration. `guard config
 --example` prints a commented one. Unknown settings are an error;
 `guard check` checks the file, compiles every pattern and asks Housecarl
-for the ban lists. Guard reads it when it starts:
-`systemctl restart guard` after a change.
+for the ban lists. After a change, `systemctl reload guard` (or `guard
+reload`) puts it to work without losing what Guard has counted (see
+[Reloading](#reloading)).
 
 ## housecarl
 
@@ -116,6 +117,29 @@ every 30 seconds, for the time it has left. A ban Housecarl refuses (an
 address it never bans, a list the token doesn't cover) isn't sent again:
 `guard status` and the log say why.
 
+## Reloading
+
+`systemctl reload guard`, `guard reload` or a SIGHUP makes the running
+Guard read guard.yaml again. `guard reload` checks the file first and
+shows what changed; a file with a mistake is refused, and Guard goes on
+as it was.
+
+* A watch is known by its **name**: one that keeps its name keeps its
+  bounties and counts, and takes its new patterns, hits, window and ban
+  at once. If its source changed (another file, journal unit, …), the
+  source starts again; a file is then followed from its end, as when
+  Guard starts.
+* Watches gone (or disabled) stop; new ones start.
+* `never_ban` and `defaults.repeat` apply to the next matches and bans.
+  Bans already made stay as they are, in Housecarl.
+* `housecarl`'s connection (`url`, `socket`, the token, `ca_cert`,
+  `insecure`), `state`, `socket` and `log` only change on a restart:
+  `guard reload` says so. `housecarl.list` reloads (it only fills in the
+  watches' lists).
+
+Changing `hits` doesn't ban at once: an address over the new hits is
+banned on its next match.
+
 ## state, socket, log
 
 | Setting | Default | |