xavierkandCommandCodeBot
c45b07003a
Migration runbook at docs/install/migrate-from-makeinstall.md covers the mandatory remove-then-install path, why over-install is forbidden, no-move continuity guarantees, and reset-to-dormant expectations. Acceptance criteria MG-1 through MG-4 added to the install criteria section. Containerized tests verify no-move continuity: existing group makes sysusers a no-op, existing store dir makes tmpfiles a no-op, hand-edited config survives as a non-database file, and store schema is caught up by the upgrade-path migration. Dead code from a prior merge removed. Co-authored-by: CommandCodeBot <noreply@commandcode.ai>
88 lines
4.6 KiB
Markdown
88 lines
4.6 KiB
Markdown
# Migrating from make-install to packages
|
|
|
|
This runbook covers the transition from a `sudo make install` system to the native deb or rpm package. Packages are the primary delivery; `make install` remains as the dev fallback. The two deliveries are **mutually exclusive** per machine.
|
|
|
|
## Why over-install is forbidden
|
|
|
|
Installing a package over a make-install system silently breaks things:
|
|
|
|
- **Stale admin units shadow vendor units.** `make install` places `fenris-collect.timer` and `fenris-collect.service` in `/etc/systemd/system/`. The package installs them in `/usr/lib/systemd/system/` (vendor placement). Systemd loads admin units first — the stale copy takes precedence, and the package update never reaches the running system.
|
|
- **The local wrapper shadows the package wrapper.** `make install` places the `fenris` wrapper at `/usr/local/bin/fenris`. The package places it at `/usr/bin/fenris`. The shell finds `/usr/local/bin` first on PATH — the old checkout-relative wrapper runs instead of the package wrapper.
|
|
|
|
Neither condition is reversible by reinstalling the package. The only safe path is remove-then-install.
|
|
|
|
## Pre-migration checklist
|
|
|
|
1. Confirm no monitoring period is actively running that you want to preserve across the gap:
|
|
```
|
|
fenris status
|
|
```
|
|
The migration resets the system to dormant (see [No-move continuity](#no-move-continuity) below). You opt back in with `fenris monitor resume`.
|
|
|
|
2. If you have hand-edited configuration at `/etc/fenris/fenris.conf`, note it. The config survives the migration in place (see below).
|
|
|
|
## Remove step
|
|
|
|
```
|
|
sudo make uninstall
|
|
```
|
|
|
|
This performs the **sanctioned disable** (`fenris-monitor disable --now`), closing the current monitoring period as `user_disabled`. It then removes all make-install artifacts: the venv at `/opt/fenris`, the wrapper at `/usr/local/bin/fenris`, the helpers at `/usr/libexec/fenris/`, the units in `/etc/systemd/system/`, and the polkit policy. The placement manifest at `/var/lib/fenris/manifest.txt` is removed.
|
|
|
|
**What survives the remove:**
|
|
|
|
- `/var/lib/fenris/observations.db` (and WAL sidecars, `.bak`) — the observation store
|
|
- `/var/lib/fenris/` directory itself — root-written, group-read
|
|
- `/etc/fenris/fenris.conf` — your hand-written configuration
|
|
- The `fenris` system group — created by `groupadd -f` during make-install
|
|
- Journal entries — age out naturally
|
|
|
|
## Install step
|
|
|
|
```
|
|
sudo apt install fenris # Debian/Ubuntu
|
|
sudo dnf install fenris # Fedora
|
|
```
|
|
|
|
The package installs into its own layout without touching the surviving store, config, or group.
|
|
|
|
## No-move continuity
|
|
|
|
These invariants are verified by the containerized acceptance tests (issue #50):
|
|
|
|
| Asset | Make-install state | Package post-install | Mechanism |
|
|
|---|---|---|---|
|
|
| `fenris` group | Exists (`groupadd -f`) | Unchanged | `systemd-sysusers` is a no-op when the group already exists |
|
|
| `/var/lib/fenris` directory | Exists (mode 2750, root:fenris) | Unchanged | `systemd-tmpfiles --create` is a no-op when the directory already exists |
|
|
| `observations.db` + sidecars | Present from prior monitoring | Unchanged, never owned by the package | Package owns the directory only; store contents are never ghosted |
|
|
| `/etc/fenris/fenris.conf` | Hand-edited device selector | Survives in place; package default lands as `.dpkg-new` / `.rpmnew` | dpkg conffile / rpm `%config(noreplace)` semantics |
|
|
| Store schema | Version from prior Fenris release | Caught up by the upgrade-path migration | `postinst` / `%post` runs `migrate_to_latest()` on upgrade |
|
|
|
|
The package detects the make-install system has been removed by the absence of the two markers:
|
|
- `/var/lib/fenris/manifest.txt` (the placement manifest)
|
|
- `/etc/systemd/system/fenris-collect.timer` (pre-manifest make installs)
|
|
|
|
If either marker exists, the package installation aborts with a pointer to this runbook.
|
|
|
|
## Reset-to-dormant
|
|
|
|
`make uninstall`'s sanctioned disable closes the open monitoring period as `user_disabled`. After the package install, the system is dormant — the timer is installed but disabled, nothing is running, no monitoring period is open.
|
|
|
|
To resume monitoring:
|
|
|
|
```
|
|
fenris monitor resume
|
|
```
|
|
|
|
This is the sanctioned opt-in. It enables the timer and opens the first monitoring period in one step. The migration costs at most one short sample gap (the interval between `make uninstall` and `fenris monitor resume`), honestly recorded in the endurance timeline.
|
|
|
|
## Verification
|
|
|
|
After migration, confirm the package is correctly installed:
|
|
|
|
```
|
|
fenris status
|
|
```
|
|
|
|
The status command should show the dormant state: timer disabled, no active monitoring period, and the observation store intact from the prior make-install system.
|