Files
LEAF/docs/INSTALLATION.md

145 lines
6.4 KiB
Markdown
Raw Normal View History

2026-11-15 17:43:04 +01:00
# Installation and operations
## Prerequisites
Use a Linux sensor with systemd, Python 3, `requests`, `PyYAML`, Suricata 7,
OpenSSH and tcpdump. Live tests also require Python 3 and ping on the test hosts.
The supplied service uses `/usr/bin/python3`; install its dependencies for that
interpreter. On Debian-based sensors, use the `python3-requests` and
`python3-yaml` packages. A separate virtual environment can be used for local
tests with `controller/requirements.txt`.
The supplied lab configuration uses sensor capture interface `eth1`, P2P
address `10.0.249.1/31`, VyOS API `https://10.0.249.0:8443`, and address group
`IDS-BLOCK`. Test hosts are `172.19.32.3` and `172.19.32.5`. These are example
site settings; inspect and adapt them for another network.
Provision mirroring, API access and firewall hooks before starting the sensor.
Both source and destination drop hooks must be reachable before accept rules
that would bypass enforcement. The controller verifies hooks but does not
provision routing or mirroring. The file in `vyos/` is an illustrative template,
not a complete router configuration.
## Configuration and credentials
The installer preserves an existing `/etc/leaf-controller/config.yaml`. For a
new installation, it seeds that file from `config/prototype-vyos.yaml`.
`controller/config.yaml` is a generic example with different API/TLS settings;
it is not the installer's lab default.
Review these settings before installation:
- API URL, timeout, retry count and TLS certificate fingerprint or CA bundle.
- Protected networks, allowed SIDs, source actions, threshold, TTL and block cap.
- Capture interface in the Suricata configuration and service unit.
- Socket, EVE, SQLite and audit paths.
The lab API uses a certificate fingerprint because its self-signed certificate
has no matching IP subject alternative name. Verify the fingerprint through a
trusted channel before setting `vyos.tls_cert_pin`. For a CA-issued certificate,
configure the appropriate CA bundle and hostname. Keep TLS verification enabled.
Create `/etc/leaf-controller/env`, owned by root with mode `0600`, containing:
```text
LEAF_VYOS_KEY='replace-with-existing-api-key'
```
Use a root editor or secret-management mechanism. Do not commit the real value
or place it in command arguments. The credential file is read by systemd.
The router address group must be dedicated to this controller. With
`adopt_foreign_members: false`, foreign members are removed during reconciliation.
The optional adoption setting imports eligible foreign members only at startup.
## Log storage and installation
The installer requires `/var/log/suricata-leaf` to be on tmpfs. On a new sensor,
review and run the provisioning script before installing:
```bash
sudo env TMPFS_SIZE=8G bash scripts/provision-ids-tmpfs.sh
sudo bash scripts/install-sensor.sh
```
Allow enough memory and swap headroom for the configured tmpfs cap and Suricata.
The provisioning script writes fstab and runs `mount -a`; review existing mounts
first. Mounting over a nonempty directory hides its previous contents. EVE files
on tmpfs are lost at reboot. SQLite and controller audit remain on persistent disk.
The installer stops the sensor/controller for upgrade, backs up existing files,
units and SQLite under `/var/backups/leaf-proto/<timestamp>/`, installs the code
and helpers, and enables these units:
- `leaf-controller.service`
- `suricata-leaf.service`
- `leaf-eve-rotate.timer`
It restores the previous deployment on installation failure. Backups can contain
credentials and must stay private. The controller runs as `leafctrl`; Suricata
runs as root with group `leafctrl`. The controller reports readiness after its
socket is bound, allowing the sensor to start afterward.
## Status and diagnostics
```bash
sudo systemctl status leaf-controller suricata-leaf leaf-eve-rotate.timer
sudo journalctl -u leaf-controller -f
sudo python3 /opt/leaf-controller/tools/vyos_smoke.py
sudo python3 /opt/leaf-controller/tools/vyos_ctl.py members
```
The smoke check reads API information, members and enforcement hooks.
`vyos_show.py` reads scoped configuration and redacts sensitive fields.
These diagnostic scripts do not write router configuration.
| Resource | Installed path |
|---|---|
| Controller | `/opt/leaf-controller/controller/leaf_controller/` |
| Configuration | `/etc/leaf-controller/config.yaml` |
| Credential | `/etc/leaf-controller/env` |
| SQLite WAL state | `/var/lib/leaf-controller/state.sqlite` |
| Decision audit | `/var/log/leaf-controller/decisions.jsonl` |
| Capture metrics | `/var/log/leaf-controller/capture.log` |
| EVE stats | `/var/log/suricata-leaf/eve.json` |
| Alert socket | `/run/suricata/alerts.sock` |
The retention timer checks each minute after an initial two-minute delay. It
renames EVE hourly or at 64 MiB, asks Suricata to reopen it, and retains six
archives. A startup grace period prevents signalling a newly started engine.
Retention can overshoot between timer runs; tmpfs capacity is the hard limit.
Audit defaults to 16 MiB with three archives; capture metrics default to 10 MiB
with six archives.
`save_config: false` leaves transient membership out of router boot configuration.
SQLite supplies desired state when the router returns. If saving is enabled,
failed saves remain dirty in SQLite and are retried.
## Credential rotation
Identify the controller's existing key ID before rotating:
```bash
sudo python3 /opt/leaf-controller/tools/rotate-vyos-key.py --old-id <controller-key-id>
```
The tool requires the selected ID to match the current credential. It creates
and verifies a candidate, saves both keys, switches the local environment file,
restarts the service, then retires only the selected old ID and saves again.
Other API users' IDs are preserved.
Switch failures restore the local credential. A failure after retirement requires
inspection before retrying; deleting arbitrary IDs is not a recovery procedure.
No credential values are printed by the tool.
## Rollback
Stop Suricata, the controller and the rotation timer. Restore the selected file
archive and its matching SQLite backup, reload systemd, and restart the previous
units. Keep SQLite closed while replacing its files. When reverting a schema
migration, restore the matching database as well as the code.
Do not clear the live database or shared router configuration as an upgrade or
test shortcut. Live tests operate on existing routes and enforcement hooks;
uplink, OSPF and static-route changes are outside their scope.