How to update rConfig V8 Pro

After reading this page, I can locate the rConfig update interface, verify backup requirements, and apply a system update safely in a production environment.

When to use this

Use this guide when a green update notification appears on the rConfig dashboard, or when your team has scheduled a maintenance window to apply the latest release. If you are setting up rConfig for the first time, complete the V8 Pro Installation steps before using this workflow.

Prerequisites

• Administrator access to rConfig
• SSH access to the server running rConfig
• Your installation is at the default path /var/www/html/rconfig8 (non-standard paths are not supported)
• A verified, tested backup completed before running the update (see Enterprise Backup Requirements below)
• Operating system is RHEL, CentOS, Rocky Linux, Alma Linux, or Ubuntu

Supported installation path only

Update scripts target the default installation path /var/www/html/rconfig8 exclusively. If your instance has been moved, symlinked, or renamed, updates will fail and the system may be left in a broken state. Deployments that deviate from the default path are not eligible for support under your subscription agreement. Verify your path before proceeding, or contact prosupport@rconfig.com first.

Enterprise Backup Requirements

Back up before every update

Production systems must not be updated without verified, tested backups. Complete all of the following before proceeding:

• Database snapshot: Full backup of all configuration data, device inventories, compliance records, and historical data
• Application snapshot: Full system or virtual machine snapshot for virtualised deployments
• Configuration files: Backup all rConfig config files, custom scripts, integration configs, and encryption keys
• Backup validation: Restore from backup to confirm data integrity before the update window
• Rollback documentation: Maintain a documented, tested rollback procedure accessible to your operations team

System failures, data corruption, or compatibility issues during updates can cause extended downtime and data loss. Confirm completion with your system administrator before continuing.

Enterprise Update Best Practices

Production environment checklist

• Staging first: Deploy updates to a staging environment mirroring production before touching production
• Maintenance window: Schedule the update during an approved window with stakeholder notification
• Post-update monitoring: Verify all systems and integrations are functioning immediately after the update
• Rollback ready: Ensure rollback procedures are documented and can be executed quickly if needed
• Integration validation: Test all third-party integrations, API connections, and automated workflows after update completion

License Agreement and Data Responsibility

Your responsibility

By running rConfig system updates, you accept the terms of the rConfig license agreement. All data management, backup procedures, and system administration are performed at your own risk. rConfig and its developers assume no responsibility for data loss, system downtime, or operational issues during update processes. Ensure compliance with your organisation’s data governance policies before proceeding.

Step-by-step walkthrough

1. Check for available updates

When an update is available, a green notification badge appears on the main rConfig dashboard.

2. Open the Update interface

1. Select System Settings from the main navigation sidebar.
2. Under System Management, select Update.

3. Review the available release

The Update interface has three tabs:

• Check Updates: Shows your installed version and available release version
• Instructions: Provides the exact commands to run for your operating system
• Release Notes: Details new features, enhancements, and resolved issues

Select Check Updates to confirm an update is available. If the interface shows “System is up to date” with a green indicator, no action is required.

4. Read the release notes

Select Release Notes and review the changes included in the new version. Note any breaking changes or integration impacts before proceeding.

5. Run the update commands

Select Instructions to see the commands for your operating system. Copy and run the commands appropriate for your deployed OS (RHEL/CentOS/Rocky Linux/Alma Linux or Ubuntu).

Note

The update interface generates OS-specific command sequences. Always run the commands that match your deployed operating system, not the alternative set.

6. Verify the update

After the commands complete, return to Check Updates. The installed version number should reflect the new release, and the status should show “System is up to date.”

Run a post-update smoke test: log in, navigate to a device, and confirm configuration backups are still accessible.

7. Secure Redis (first update to V8.4.1 or later)

From V8.4.1, rConfig requires a password on Redis. The standard and Vector deploy scripts secure Redis automatically on every deploy: they run rconfig:redis-secure --no-restart, which sets a password only if .env has none, and the deploy restarts the workers itself. You do not need to do anything.

Run it by hand only for a manual install, or if the deploy printed a warning that the Redis step was skipped or failed. From the rConfig folder:

cd /var/www/html/rconfig8/current
php artisan rconfig:redis-security-check

# Only if the check reports "Redis has no password set"
sudo php artisan rconfig:redis-secure

The command writes the password to REDIS_PASSWORD in .env, requires it on Redis, and restarts Horizon, the queue workers, and the SNMP trap handler. It is safe to re-run. If other rConfig nodes share this Redis, they are locked out until they get the same password, so read Redis Authentication before running it.

After upgrading to V8.4.1

V8.4.1 stops rConfig running anything as root. The deploy now:

• writes the Horizon Supervisor config as a root-owned file with user= set to the web server user, and replaces any symlink or hand-edited copy (see Horizon Queue Manager)
• stops Horizon before it changes any files, waits for running jobs to finish, and starts it again at the end
• keeps the scheduler in the web user’s crontab and removes any schedule:run line from root’s crontab
• moves an SNMP trap receiver set up under Supervisor to the systemd service rconfig-snmptrap
• installs the xFTP Docker helper and locks down the xFTP folder where it can
• stops opening storage to every local user
• runs rconfig:check-worker-user as its last step

The SNMP and xFTP steps print a warning and the deploy carries on if they cannot finish. Check the deploy output for warnings, then work through this list once.

1. Check the Worker Privilege alert. Open the dashboard Health Status panel, or run the check from the rConfig folder:

   cd /var/www/html/rconfig8/current
   sudo php artisan rconfig:check-worker-user

   Every line should read OK or SKIP. For anything else, see Worker Privilege.

2. Recreate the xFTP containers, then lock down the folder. Containers started before V8.4.1 need a folder every local user can write to, so the folder stays open until they are replaced. For each running service, run sudo php artisan rconfig:xftp-toggle, stop it, then run it again and start it. Then run:

   sudo php artisan rconfig:xftp-toggle --fix-permissions

   If you added the web server user to the docker group by hand, remove it with sudo gpasswd -d apache docker (www-data on Ubuntu). See xFTP Server.

3. Check the SNMP trap receiver, if you use SNMP traps. It now runs under systemd, not Supervisor:

   systemctl status rconfig-snmptrap

   On Ubuntu, a receiver set up with the old .ini file never ran, so the upgrade installs it but leaves it off. Turn it on with sudo php artisan rconfig:snmp-trap-service install. See SNMP Trap Receiver Service.

4. Use the new Vector agent install command. The old curl … install.sh?bootstrap_token=… | sudo bash command no longer installs anything. Copy a new command from Vector Agents and update any automation that runs the old one. Agents already installed keep working. See Vector agent installation.

5. Check scripts that ran as root. Script connections now run as the web server user. A script that read root-only files or called sudo without a rule stops working. See Which user runs your scripts?.

6. Set permissions on configs saved before the upgrade. New configs are saved 0440, but configs from earlier versions stay readable by every local user until you run:

   cd /var/www/html/rconfig8/current
   sudo php artisan rconfig:set-config-permissions --dry-run
   sudo php artisan rconfig:set-config-permissions

   The first run can change thousands of files. It is safe to re-run. Then open Settings > System Management > System Optimization and check that every storage row on the Security & privileges card is OK. See Storage permissions.

7. Check who gets health check alerts. From V8.4.1, failing health checks send Health Check Failed and Health Check Recovered notifications through the normal notification channels instead of spatie’s own email, which was never switched on. In-app and email are on by default for every user with notifications enabled. To also post them to Slack or Teams, switch them on in Settings → Notifications, or tick them on a webhook.

8. Vector installs only: check the Vector Hub helper. The Vector deploy scripts install it, and the deploy fails if they cannot. After a manual upgrade, install it with sudo php artisan rconfig:vector-hub-install-helper and restart Horizon. See Vector Hub.

9. Still on HTTP? Switch to HTTPS. From V8.4.1, the dashboard shows an HTTPS alert while APP_URL starts with http://. For a self-signed certificate, run:

   cd /var/www/html/rconfig8/current
   sudo php artisan rconfig:ssl-self-signed --dry-run
   sudo php artisan rconfig:ssl-self-signed

   If you already serve rConfig over HTTPS but APP_URL still says http://, set it to your https:// address instead. See SSL Configuration.

10. Optional: NetBox or Nautobot devices behind NAT. From V8.4.1, the V2 NetBox and Nautobot integrations can manage a device on its NAT (outside) address instead of an unreachable primary IPv4. If you hand-edited device IPs to work around this, turn on Prefer NAT (Outside) IPv4 in the integration’s Setup tab and check Sync Preview before the next Apply. See Devices behind NAT.

11. Optional: turn on snippet error detection. From V8.4.1, rConfig can report a snippet send as Failed when the device rejects a line, instead of showing it green. Existing templates don’t have the snippet_errors block that turns this on, so their sends are reported as Success (not checked) and behave as before. Add the block to the templates you use for snippets, or re-import the Cisco IOS templates from the repository. See Snippet Error Detection.

12. Check who can send snippets to many devices. From V8.4.1, Send to devices… in the Snippets list sends one snippet to many devices at once. It needs the snippet.view and config.create permissions, and only shows snippets assigned to the user’s role. Make sure the roles that should use it have both, and restart Horizon after the update so it picks up the new batch jobs. See Send to many devices from the Snippets list.

13. Check the HorizonOne worker count. From V8.4.1, HORIZON_MAX_PROCESS in .env also sets the worker count for the general queues (compliance, notifications, SNMP traps), not just downloads. Those queues keep all their workers running, so a standard .env goes from 5 to 10 always-on workers. If you raised HORIZON_MAX_PROCESS, they now run that many too. Check memory and database max_connections, then restart Horizon. See Horizon Queue Manager.

14. Vector installs only: update agents to 2.0.1 to use an outbound source address. From V8.4.1, with vector-server-pkg 2.0.11, an agent can connect to its devices from a chosen local address (Settings > Agents > edit > Configuration > Advanced > Outbound Source Address). Agents older than 2.0.1 ignore it and show Agent update needed. Make 2.0.1 the active binary on Binary Admin, then on each agent host run the installer again with sudo bash vector-agent-install.sh --server 'https://<rconfig>'. Skip vector-server-pkg 2.0.10: its installer refuses the published 2.0.1 binary. See Outbound source address.

After upgrading to V8.4.2

V8.4.2 changes how CIC definitions are applied to backups and adds two device sync drivers. Check these once:

1. Expect some configs to move from Valid to Failed. From V8.4.2, every rule in a CIC definition must pass. Before, only the last rule counted, so a definition with several rules could pass even when an earlier rule failed. Run CIC Recheck on a few devices to see the effect straight away, and use Test against a config in the definition editor to find the failing rule. See Multiple Validation Strings.

2. Look for flagged CIC definitions. Open Compliance → CIC Definitions. A warning icon marks a definition with problems in its file, or one that couldn’t run during a backup. Definitions saved before V8.4.1, or edited directly on disk, are the usual cause. Open each one; the editor underlines the problem. See Finding broken definitions.

3. Unknown CIC status no longer means a failed download. A CIC definition that can’t run now leaves the config saved as Unknown instead of failing the download. To see why, filter Settings → Application Logs by Event type cic.

4. New LibreNMS, Observium and OpenNMS device sync drivers. From V8.4.2, Platform → Integrations → + Add Driver lists LibreNMS, Observium and OpenNMS. If they are missing, run php artisan rconfig:integration-v2-sync-definitions, then rebuild the front end with npm run build so their logos and filter card show. Observium needs the Professional or Enterprise edition and is not yet tested against a live instance. See LibreNMS Device Sync V2, Observium Device Sync V2 and OpenNMS Device Sync V2.

5. Optional: whole-config checksum rules. From V8.4.2, a compliance policy definition can check a config against a checksum with #[must_match_checksum] or #[must_match_any_checksum]. Copy a config’s checksum from the fingerprint button (Policy Checksums) in the config toolbar. Nothing changes for existing definitions. If you use config obfuscation, read the caution on that page first. Rebuild the front end with npm run build so the policy editor and results show the new methods. See Whole-config checksums.

6. AI Center answers may change slightly. From V8.4.2, the upgrade loads rConfig’s built-in networking knowledge, which earlier versions never loaded, and keeps at least 40% of each AI feature’s knowledge budget for your customer knowledge entries. Nothing to do unless you’ve added customer entries: check that long ones still fit. See Teach the AI your conventions.

7. More AI providers, and the Azure endpoint moves into the form. From V8.4.2, AI Center → AI Settings also offers Mistral, xAI (Grok), DeepSeek, Groq, Cohere and OpenRouter, and OpenAI-Compatible takes an optional API key in the form. Azure OpenAI now has an Endpoint field; existing Azure providers keep reading AZURE_OPENAI_URL from .env until you edit them and add the endpoint. Rebuild the front end with npm run build so the new provider forms show. See Set up an AI provider.

8. MCP agents can ask for the running config by name, and read older versions. From V8.4.2, the get_latest_config MCP tool takes an optional command filter, so an agent asking for the running config no longer gets show version output on devices that collect both. A new get_config tool returns any stored version by its ID, so agents can answer “what did it look like on June 1?”. Nothing to change on the server. If you installed the rConfig Core Skill, download it again from AI Center → Skills so your agent’s instructions mention the filter. See MCP Server.

9. Vector agent provisioning needs a token with agents.write. From V8.4.2, POST /api/v2/agents/provision refuses tokens without the new Provision Vector agents ability, and the token owner needs agent.create (or agent.update for an existing agent). No existing token has the ability, so any Ansible, Terraform or CI runbook that provisions agents returns 403 until you create a new token under Settings → REST API → Tokens with Provision Vector agents ticked and swap it in. Token abilities can’t be edited. See Automated Agent Deployment.

10. MCP tokens: a new permission, expiry, and admin oversight. From V8.4.2:

    • New permission. aicenter.mcptoken lets a role create and revoke its own MCP tokens without AI settings rights. rconfig:update-rbac-data asks to grant it to every role that already has aicenter.update, so nobody loses access. Give it to engineers’ roles where you want self-service.
    • Admin oversight. Users with aicenter.update see and revoke the tokens of users they manage, and can create a token for a service user under Token for.
    • Expiry. New tokens expire after a year unless you choose otherwise. Existing tokens keep working with no expiry, so revoke and replace any you want to expire.
    • Rebuild the front end with npm run build so the MCP Server tab shows the new fields.

    See MCP Server.

11. Role templates replace the preset roles. From V8.4.2, Add Role and Edit Role offer templates (Read-Only, Read-Only + Device Edit, Standard User, AI Center User, and Vector User when Vector is installed) that fill the permission matrix for you. Your existing preset roles and the Guest role stay as they are, and preset roles can now be deleted unless LDAP or RADIUS uses one as its default. Nothing to do on upgrade. Rebuild the front end with npm run build so the dialog shows the templates. See Role templates.

12. Expect some API Collections to show as Down. From V8.4.2, an endpoint that returns an HTTP error (401, 404, 500 and so on) or can’t be reached is a failed download, and the collection is marked Down with the reason. Before, the error page was saved as a config and the collection could still show Up, so these collections were already failing. The API Categories and API Tags task types now work. Rebuild the front end with npm run build so the task wizard shows their pickers. See When a Download Fails.

13. Backup failures now show why. From V8.4.2, a failed device or API Collection backup records a reason, such as Authentication failed: Username or password rejected for 'admin' (SSH). You see it on the status icon in the Devices table, beside Last Config, on the device page and in the failure notification and email. The Status filter adds Last Backup Failed and Last Backup: Conn/Auth. Reasons start with each device’s first backup after the upgrade, so devices show nothing until then. Run php artisan migrate (the update does this) and rebuild the front end with npm run build. Two side effects:

    • Telnet and TL1 devices that can’t be reached send one failure notification instead of two.
    • The download_method in device events now names the real protocol instead of always saying ssh.

    See Why the Last Backup Failed.

14. Device Sync passwords and tokens are stored encrypted. From V8.4.2, the upgrade encrypts the passwords, API tokens and API keys saved for every Device Sync V2 integration, so they are no longer readable in the database or in what rConfig sends to the browser. Syncs keep working, with nothing to re-enter. On the integration’s Setup tab, a saved secret field now shows Saved. Leave blank to keep it. instead of the value. Leave it blank to keep the stored secret, or type a new one to replace it. Run php artisan migrate (the update does this) and rebuild the front end with npm run build. Preview runs also no longer change device links: only a Full Sync acts on devices missing from the source.

15. Reports, the digest and the dashboard show failure reasons. From V8.4.2:

    • Task reports add a Reason column and a count of failures by type. CIC-failed configs get their own icon.
    • Failure only report emails are also sent when a config fails its CIC check, so you may get a few more of them.
    • The Latest Error Devices dashboard card shows why each device’s last backup failed.
    • The digest’s Configuration Downloads figure counts only saved device and agent configs. Before, it also counted failed attempts, snippets and API Collection downloads, so expect a lower number in the first digest after the upgrade. The digest now shows failed backups and devices with Connection/Auth failures, which before always counted 0.

    Nothing to do. See Why a Device Failed.

16. Some backups that “succeeded” before may now fail. From V8.4.2, a backup fails instead of saving a bad config when:

    • the device refuses the enable password, or
    • a command never gets back to the device prompt (partial output).

    Before, these saved non-enable or cut-off output as a good backup. After upgrading, filter the Devices table by Last Backup Failed and look for Enable password rejected or Timed out waiting for the device prompt. Fix the enable password, or raise the template timeout for slow devices and very large configs. See Why the Last Backup Failed.

17. Key vault settings move into the UI, and two new vaults arrive (early access). From V8.4.2, key vaults are set up on their own pages under Platform → Integrations → Device Credentials instead of in .env, and more than one vault can be switched on at once. Two new vaults are available in early access: Palo Alto Networks Idira (CyberArk), through the Central Credential Provider, and Delinea Secret Server. If you already use HashiCorp Vault from .env, nothing breaks: rConfig keeps reading .env until you open the Hashicorp Vault page and click Save, which copies the address and token into rConfig (stored encrypted). After that the VAULT_HASHICORP_* lines in .env are ignored. Existing vault credential sets keep working. Run php artisan migrate (the update does this) and rebuild the front end with npm run build. See the Vault Credentials Overview, Idira (CyberArk) Setup and Delinea Secret Server Setup.

Common gotchas

Common update mistakes

• Non-standard install path: Running the update from a path other than /var/www/html/rconfig8 will fail. Verify your path with ls /var/www/html/rconfig8 before starting.
• No backup: Proceeding without a tested backup is the single highest-risk action. A failed update without a backup can result in unrecoverable data loss.
• Wrong user: Running update commands as the wrong system user can cause permission errors or leave files owned incorrectly. Confirm the correct user with your system administrator or check the Instructions tab.
• Wrong OS commands: The update interface shows both RHEL-family and Ubuntu commands. Running the wrong set on your OS will produce errors.

What’s next

• V8 Pro Installation - Review the original installation steps if you are rebuilding or moving the system
• Docker deployment for rConfig V8 Pro - If you operate a containerised stack, review the Docker-specific update guidance
• rConfig V8 Features Overview - Understand what capabilities the latest release adds