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

```sh
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:

```sh
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`:

```sh
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](configuration.md)). Then:

```sh
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.