145 lines
6.4 KiB
Markdown
145 lines
6.4 KiB
Markdown
# 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.
|