rXg upgrade path: getting ready for kernel upgrade
October 11, 2025
Summary
This document outlines the correct and mandatory upgrade procedure for the RG Nets rXg platform, detailing the technical justification for the required sequence.
The correct upgrade path is always a two-step process:
- Upgrade the rXg software to the latest version compatible with your current FreeBSD operating system.
-
Upgrade the FreeBSD OS using the specific ISO image provided by RG Nets.
This sequence is critical for system stability, data integrity, and a successful upgrade, regardless of whether the process is initiated from the local rXg GUI or orchestrated via the rXg Fleet Manager (FM).
The Correct Upgrade Procedure
Following this two-step process ensures a seamless transition between major versions.
Step 1: Upgrade rXg Software
Before any changes are made to the underlying operating system, the rXg application software must be upgraded first.
- Action: Using the rXg GUI or FM, perform a software update to the latest available version.
-
What Happens: This process updates the rXg application, its associated services, and most importantly, performs critical pre-migration tasks. The new software version is specifically designed to be "forward-aware" of the upcoming FreeBSD OS environment. It stages the system by:
- Running database migration scripts ($ rxg_db_migrate $) to update the database schema to a format compatible with the new version.
- Modifying configuration files and system parameters in preparation for the new OS kernel and libraries.
- Placing the necessary boot-time scripts to ensure rXg services start correctly after the OS upgrade is complete.
Step 2: Upgrade FreeBSD Operating System
After the rXg software upgrade has successfully completed, the system is ready for the operating system upgrade.
- Action: Boot the rXg appliance using the custom-built FreeBSD ISO provided by RG Nets.
-
What Happens: The RG Nets installer is not a standard FreeBSD installer. It is specifically engineered to:
- Detect an existing, prepared rXg installation.
- Perform an in-place upgrade of the operating system on the primary partition.
- Carefully preserve the data partition (typically mounted at $ /rxg $), which contains all configuration, database, and user data.
- Re-integrate the preserved data partition into the newly installed operating system.
Technical Justification: Why This Order is Critical
Deviating from this upgrade path by upgrading the FreeBSD OS first will lead to system failure and potential data loss. The rationale is based on dependency management, data structure integrity, and configuration compatibility.
Dependency and Compatibility
The rXg software is tightly coupled with the specific kernel versions, system libraries, and drivers of its underlying FreeBSD OS. An older rXg software version is not designed to run on a newer major FreeBSD release.
Attempting to boot an old rXg version on a new OS will almost certainly fail because of:
- Library Mismatches: The rXg binaries will be linked against libraries that no longer exist or have changed significantly in the new OS.
-
Kernel Incompatibility: System calls and kernel modules that the old rXg software relies on may be altered or deprecated in the new FreeBSD kernel.
The correct process ensures the application is ready for the new environment before it's placed in it. Think of it like packing your belongings (data) into correctly labeled boxes (new schema) before the movers (OS upgrade) transport them to your new house (new OS).
Database Schema Migration
This is the most critical reason for the prescribed order. rXg versions often introduce changes to the database schema to support new features or improve performance.
- The rXg software upgrade contains the logic to safely migrate the existing database from its old schema to the new one. This is a delicate operation that must be completed in the known-good, stable environment of the old operating system.
- If you upgrade the OS first, the old rXg software will likely be unable to start due to the compatibility issues mentioned above. If the software cannot run, it cannot perform the necessary database migration. The new rXg software, upon a later installation, would not know how to interpret the old, un-migrated database format, leading to data corruption or a complete failure to launch services.
Configuration Integrity
The rXg software upgrade process intelligently modifies system-level configuration files (e.g., $ /etc/rc.conf $, $ /boot/loader.conf $, network interface configurations) to align with the requirements of the next FreeBSD version.
If you upgrade the OS first with a generic installer, these critical configurations could be overwritten with defaults, severing the connection between the OS and the rXg application and data partitions. The custom RG Nets ISO, in contrast, is designed to work with a system that has been pre-configured by the rXg software update, ensuring all settings are preserved and correctly applied in the new environment.
Consequences of an Incorrect Upgrade Path
Upgrading the FreeBSD OS before the rXg software will result in a non-functional system. The typical outcomes include:
- Complete Service Failure: The main rXg daemon and its supporting services will fail to start.
- Data Inaccessibility: The system will be unable to read its configuration from the database, effectively reverting to a "default" or broken state.
-
Significant Downtime: The only recovery path is typically a full system re-installation from scratch and a manual restoration from a known-good backup, a time-consuming and service-impacting procedure.
To ensure a successful and supported upgrade, you must always upgrade the rXg software first, followed by the FreeBSD OS using the provided RG Nets ISO.
