6.4 KiB
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:
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:
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.servicesuricata-leaf.serviceleaf-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
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:
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.