Upgrades and rollback

An upgrade is a new bundle applied by the same installer, in the same order as the first install. Nothing about the procedure is special-cased for upgrades, which is deliberate: one code path, exercised every time.

Learning that a new version exists

After a successful heartbeat the appliance asks the Nyxtrace server whether a newer version exists and shows the answer — version, channel, release date, whether it is a security release, and a short notice — in the interface. It is a notice only: nothing is downloaded, nothing is replaced, and there is no auto-update. With NDR_TELEMETRY=off the check does not happen and you watch the release page instead. See instance registration and telemetry.

The sequence

# 1. Back up first, and verify it is readable.
# 2. Stage and verify the new bundle.
export NDR_ARTIFACT_DIR=/root/nyxtrace-release
/root/nyxtrace-release/install-appliance            # preview, changes nothing
/root/nyxtrace-release/install-appliance --apply    # apply

# 3. Validate before restarting anything.
ndr validate-config

# 4. Restart, then check.
systemctl restart ndr-api ndr-web vector
ndr-health

A repeat apply preserves your secrets byte for byte. It does replace the generated policy files with the exact bundled versions and removes legacy duplicate keys from the older environment files, so a setting you hand-edited into one of those generated files will not survive — put local overrides where the documentation says they belong.

Migrations

Schema migrations are additive and repeatable, and the service unit runs them as a pre-start step before every start. You do not run migrations by hand on a healthy system.

Three properties worth knowing:

• Migration artifacts are validated before any database connection is opened. A missing or empty migration file fails before anything is mutated.
• An upgrade that changes a table’s identity keeps the old table and backfills the new one. The old data is retained rather than dropped, so a rollback has something to go back to.
• The migration ledger is repeatable: running it twice produces the same state, and it records what it did.

Version pinning

The bundle pins its own component versions: the database, Grafana, the packet source, the flow collector and the transport. Third-party artifacts are verified against recorded checksums before install, and the database and Grafana are accepted only as exact candidate versions from preconfigured signed repositories.

The transport is a privately built runtime, shipped inside the checksum-covered archive and never downloaded by the appliance. The reason is specific: stock builds reported source progress before the asynchronous disk write had completed, which under low volume could lose buffered records on shutdown. The fix waits for write completion before advancing progress.

If you rebuild that runtime, repeat its regression gate — ten consecutive runs of the buffer test and ten of the end-to-end topology test under the race detector. A version bump and one clean run is not equivalent proof; that is how the original problem survived a release.

Rolling back

The previous release directory is kept, so a bad web or binary release can be reverted by pointing back at it and restarting.

For anything that touched the schema or the host configuration, the way back is the backup: boot the preserved disk or restore the pre-upgrade machine configuration, and keep the newer data archived rather than merging it.

A removal of Nyxtrace touches only what Nyxtrace owns — its units, its configuration, its own firewall table, its own capture resources. It never reloads management networking, and it never removes firewall, DNS or proxy objects you created yourself. Those are yours; the rollback does not assume it may delete them.

Firewall-side changes

If an upgrade changes the firewall feed configuration, treat it as a firewall change and not as an application upgrade: configuration backup first, written rollback, standby node before the active one, and verification of the cluster state, packet filter, interfaces, DNS, management access and one real cross-VLAN path after each step. See firewall feeds.