Migration guides

Moving to rConfig V8 is one of two jobs, sometimes both: upgrading an existing rConfig install, or bringing devices across from another system. These guides explain the paths the docs support, what each one carries over and what it leaves behind, and the decisions to make before you start. The step-by-step procedures stay in the main docs, starting with the V7 to V8 Pro Upgrade Guide.

Pick your path

Starting point	Path	Main docs
rConfig V7 Professional	In-place upgrade with the V8 upgrade script	V7 to V8 Pro Upgrade Guide
rConfig Vector V7	In-place upgrade with the same script, run for Vector	Vector V7 to V8 Upgrade
rConfig V8 Professional, moving to Vector	In-place migration once support has provisioned a Vector Server licence	V8 Pro to Vector Server Upgrade
An earlier V8 Pro release	Update from the Update page in rConfig	V8 Pro Update Process
Self-managed Docker container	Move to a traditional server install	Docker Deployments
Oxidized, RANCID, NetMRI or SolarWinds NCM	Command-line import tool for the device inventory	Oxidized, RANCID, NetMRI, SolarWinds
A spreadsheet, CMDB or source of truth	CSV import, REST API or Device Sync	Device Import Workbook

rConfig V6 Core and V8 Core are the community editions, with their own repositories on GitHub. This site documents the Pro, Enterprise and Vector editions, and doesn’t include a V6 upgrade procedure. Documentation for older releases is at v7docs.rconfig.com and v6docs.rconfig.com.

Upgrading in place from V7

The V7 to V8 upgrade is an in-place migration rather than an export and re-import. The V8 deployment script detects the V7 install, keeps its data and configuration settings, removes the legacy Envoy deployment components and moves the install onto the V8 deployment system. Existing data, configurations and customisations are preserved.

That design brings some fixed constraints:

Update V7 first. The installation docs ask for V7.4.0 or later before upgrading.
Default paths only. The script expects V7 at its default location and deploys V8 to /var/www/html/rconfig8. Moved, symlinked or renamed installs fail and fall outside supported configuration. Restore the default layout first, or talk to support before you start.
Some clean-up after the script. Database references to older rconfig5, rconfig6 or rconfig7 folders are updated, the web server document root may need pointing at the V8 folder, and configs carried over from V7 keep their old, more open file modes until you reset them.

The alternative is a fresh V8 install. The upgrade guide points to the installation guide for clean environments, including ones deployed alongside the upgrade. For an existing estate, the in-place path is the one that preserves its data.

Vector follows the same pattern with its own script mode, and moving from V8 Pro to Vector Server is also in place: devices, configurations and history remain intact.

Protect the old system first

Every upgrade page starts with the same requirement: a complete, tested backup stored off the server. rConfig removed its built-in system backups in V8.4.1, so this is done with your own tooling: VM snapshots, enterprise backup software, or database dumps plus file copies.

A usable backup has four parts. Missing any one leaves a restore incomplete.

Component	Why it matters
Database	Devices, tasks, policies, users and compliance history
Storage directory	Downloaded configurations, templates and reports
`.env` file	Database connection, mail and application settings
`APP_KEY` in `.env`	Decrypts stored device credentials. A restore without it leaves every credential unreadable.

Restore onto the same rConfig version the backup was taken from, then upgrade. Restoring an older database under newer application code can leave migrations half-applied. See Backups.

Expect behaviour changes after the upgrade

An upgrade that crosses several V8 releases picks up every behaviour change in between. Some are visible straight away and look like regressions when they are not. Two examples from the release notes and the update process checklists:

From V8.4.1, nothing runs as root. Scripts that relied on root access, and hand-edited Supervisor configs, need attention.
From V8.4.2, every rule in a CIC definition must pass, and backups that hit a rejected enable password or a prompt timeout fail instead of saving partial output. Configs that showed as Valid, and backups that showed as successful, can now show as Failed.

Work through the “After upgrading” checklist for each release you pass through.

Moving between install types

Besides the standard Linux server install, V8 Pro has an official Docker deployment that uses rConfig’s published images and is a supported production path.

Self-managed containers, built on your own Dockerfile or compose setup, are a different case. The Docker Deployments page explains the problems support has seen with them at scale and gives a migration path off them: back up the container, export the database, copy the configuration files from the Docker volumes, install rConfig on a traditional server and import both. The docs don’t have a dedicated procedure for moving an existing server install into the official container. The backup components above are what any move between hosts has to carry.

Bringing devices in from other systems

Dependencies come first

Every device references a vendor, a connection template, a command group and usually a credential set and tags. The Device Import Workbook sets the order: vendors, templates, commands, command groups, tags, credential sets, then devices. Imports fail or produce devices that can’t back up when these are missing. It also suggests treating the migration as a chance to clean up naming, tag taxonomy and credentials before they reach rConfig.

Choose an import method

Method	Fits	Trade-off
Oxidized, RANCID, NetMRI or SolarWinds NCM import tool	Leaving one of those systems	Command line only. Device type mappings to rConfig templates must be built first.
CSV import	One-time migrations from any source	Every prerequisite ID must exist. The workbook recommends files of 500 devices or fewer.
REST API	CMDB or IPAM integration, custom migration scripts	Needs development work and error handling
Device Sync V2	An upstream platform stays the source of truth	Ongoing reconciliation rather than a one-off copy

The import tools share one shape: build mappings from the old system’s device types to rConfig templates, vendors and categories, load the source inventory into an import file, then import it. NetMRI and SolarWinds add a first step to set up the API connection. All four need templates and at least one credential set in rConfig before you start.

They move the inventory, not the history. The RANCID page spells this out: configurations already collected stay in RANCID’s version control, no backup tasks are created, and RANCID itself isn’t modified. History in rConfig starts with the first backup after import, and each import tool’s page ends with setting up backup schedules. Run the old and new systems in parallel until the imported devices back up cleanly.

One-off import or ongoing sync

The workbook’s rule of thumb is CSV for one-time migrations and the API for continuous sync. Device Sync V2 goes further for teams with a source of truth or monitoring platform already in place. Each run passes through the same stages, from setup validation to apply. A preview run makes every decision without writing anything, and reconciliation matches upstream records to existing devices, so a device already in rConfig is updated rather than created again. Device Profiles carry template, vendor, category and credentials, so upstream hosts reference a profile instead of carrying per-host mapping tags. The Device Sync V2 overview lists the supported platforms and their test status.