Docs
This commit is contained in:
144
docs/INSTALLATION.md
Normal file
144
docs/INSTALLATION.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user