abrown38andClaude Opus 5.5
941d4fb10d
make dist builds tarballs for linux/amd64 and linux/arm64. A pushed v* tag runs .gitea/workflows/release.yml, which checks the tag against VERSION and the CHANGELOG, tests, builds the tarballs and the .debs (amd64, arm64) and publishes them with scripts/gitea-release.sh: a Gitea release, and the .debs in the Debian registry (stable, or testing for a release candidate). As in Housecarl and Steward; no cli-dist, Guard is Linux only. docs/development.md has the steps, docs/install.md the apt source. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3.3 KiB
Installing Guard
Guard runs on any Linux machine whose logs it should watch: a web server behind the firewall, a mail server, the firewall itself. It needs Housecarl 0.2 or later (ban lists) on the firewall, reachable from the machine.
1. A ban list and a token, in Housecarl
On the firewall, make a ban list for this machine, and a user with a token that may ban into it and nothing else:
hc banlist add web --scope hosts --host 10.0.10.57 --host 2001:db8:10::57
hc user add guard-web --no-password --grant bans:write:web
sudo hc token create web --user guard-web
The scope says what a banned address is kept from:
hosts: this machine (its addresses), the usual choice for a server behind the firewall. Port forwards to it are covered too.firewall: the firewall itself, for Guard running on the firewall.everything: the firewall and everything behind it.
A watch that reads Housecarl's own log (housecarl-drops) also needs
--grant log:read.
2. The package
Guard's releases publish its Debian package to the same Gitea registry
as Jarl's, Steward's and Housecarl's: stable for releases, testing
for release candidates. If apt already has it, sudo apt install guard
is all it takes. Otherwise add it:
sudo install -d /etc/apt/keyrings
sudo curl -fsSL https://gitea.adbraun.lol/api/packages/adam/debian/repository.key -o /etc/apt/keyrings/gitea-adam.asc
echo "deb [signed-by=/etc/apt/keyrings/gitea-adam.asc] https://gitea.adbraun.lol/api/packages/adam/debian stable main" \
| sudo tee /etc/apt/sources.list.d/gitea-adam.list
sudo apt update
sudo apt install guard
For release candidates too, add the testing distribution: the same
deb line with testing instead of stable. The release page also has
the .deb files (sudo apt install ./guard_0.1.0_amd64.deb) and
tarballs for Linux amd64 and arm64.
The package makes the guard user (in the adm and systemd-journal groups,
to read logs), installs guard.service without starting it, and writes
an example /etc/guard/guard.yaml.
From source instead (Go 1.27): make && sudo make install, then
sudo systemd-sysusers guard.conf && sudo chgrp guard /etc/guard /etc/guard/guard.yaml && sudo systemctl daemon-reload.
3. The configuration
Put the token in /etc/guard/token:
sudo install -m 0640 -g guard /dev/stdin /etc/guard/token <<< 'housecarl_…'
and edit /etc/guard/guard.yaml: Housecarl's URL, the ban list, and the
watches (configuration.md). Then:
sudo -u guard guard check # the file, the patterns, Housecarl
sudo -u guard guard test ssh # what the ssh watch finds in the journal
sudo systemctl enable --now guard
guard status # as root
On the firewall itself, use Housecarl's local socket instead of the URL
(housecarl.socket: /run/housecarl/housecarl.sock), and give the guard
user access to it: SupplementaryGroups=adm systemd-journal housecarl
in systemctl edit guard. A token is still needed: Housecarl trusts
only root and its own user on the socket without one.
fail2ban instead
If you already run fail2ban, Housecarl ships an action for it that bans into a ban list the same way (Housecarl's docs/bans.md). Guard and fail2ban can also run side by side, on different machines or watching different logs.