# 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//`, 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 ``` 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.