Backup and restore

Nexus offers two kinds of backup, and they are not interchangeable:

	Data-directory backup	Configuration backup
What it is	A copy of the whole data directory	A .rnbk file downloaded from the web interface
Covers	Everything: configuration, accounts, stored passwords, history, alarms, audit log, certificates, licence	Configuration only (see below)
Needs	Access to the server, and either a short outage or an online database copy	An administrator sign-in
Use it as	Your backup	A change-control snapshot before you edit something

Take data-directory backups on a schedule. Take a configuration backup before any change you might want to undo.

What is in the data directory

Everything Nexus stores lives in one directory, so a copy of it is a complete backup. The program files are not worth backing up — reinstalling gets those.

File or folder	Contents	In a configuration backup?
raylux_project.json	Projects, screens, providers, tags and their alarm and history settings, devices, historian connections, tag groups, scripts, email/SMS/SSO settings, and Nexus's own ports and bind address.	Yes
raylux_users.json	User accounts, roles and password hashes.	No
raylux_refresh_tokens.json	Active sign-in sessions.	No
raylux_secrets.json	The key that signs sign-in tokens, and every stored password — devices, email, SMS, databases, SSO.	No — the configuration only names them
raylux_history.db	Recorded process history. Usually the largest file.	No
raylux_history_buffer.db	History not yet written to its final destination.	No
raylux_alarms.db	The alarm journal.	No
raylux_audit.db	Who changed what, and who wrote to which tag.	No
raylux_esignature_chain.db, raylux_esignature_secret.key	The electronic-signature record and the key that seals it. Keep the two together.	No
raylux_memory.db, raylux_memory_<PROVIDER>.db	The current values of persistent memory tags.	No — tags come back at their initial value
raylux_report_runs.db, runs/	Generated reports.	No
raylux_system.db, raylux_user_prefs.db, raylux_notification_state.json	Nexus internals, user preferences and alarm-notification progress.	No
raylux_license.raylux-license, raylux_trial.json	The installed licence and the trial clock.	No
raylux_license_key.json	The licence key entered on the License page. Readable by the Nexus service account only.	No
certs/	The TLS certificate and private key.	No
assets/	Images and files uploaded to projects.	No
templates/	Project templates.	No
downloads/	Studio and Lens setup programs served by the Downloads page.	No
logs/, uploads/, raylux_first_boot.txt	The log, temporary upload space, and the one-time commissioning token. Not needed for a restore.	No

Some of these appear only once the feature that writes them has been used. Copy the directory as a whole rather than picking files, so that a file created by a feature you have not thought of yet is not left behind.

A backup is as sensitive as the server

raylux_secrets.json holds every stored password in the clear. On the server it is locked to the Nexus service account; in your backup it is protected only by wherever you keep the backup. The same goes for the TLS private key in certs/. Store backups somewhere with access control, and encrypt them if they leave the site.

History in an external database is not in the data directory

If a historian connection points at MariaDB or PostgreSQL, the history recorded there lives in that database. Back it up with that database's own tools. Only history held in raylux_history.db is covered here.

Settings held outside the directory

If you set RAYLUX_JWT_SECRET or RAYLUX_ESIGNATURE_HMAC_KEY as environment variables, the values are not in the data directory. Record them wherever you keep your backups; the electronic-signature record cannot be verified without its key.

Taking a data-directory backup

With Nexus stopped

This is the simplest method, and the one to use unless the outage is a problem. Nexus finishes writing every database as it stops, so the copy is complete and self-contained.

Windows

Stop-Service RayluxNexus
$stamp = Get-Date -Format 'yyyy-MM-dd'
Copy-Item 'C:\ProgramData\Raylux' "D:\Backups\Raylux-$stamp" -Recurse
Start-Service RayluxNexus

Linux

sudo systemctl stop raylux-nexus
sudo tar czf "/backups/raylux-$(date +%F).tar.gz" -C /var/lib raylux
sudo systemctl start raylux-nexus

Use Stop-Service rather than sc stop in a script: sc stop returns while the service is still stopping, so a copy that follows it immediately can start before Nexus has closed its databases.

The outage lasts as long as the copy takes, so most sites run this nightly, out of hours.

With Nexus running

Nexus's databases are SQLite, running in write-ahead-log mode: recent changes sit in a -wal file beside each .db until they are folded in. Two consequences:

• Never copy the .db files alone. A copy without the matching -wal files can be missing everything recent — in testing, such a copy started cleanly and had lost its history, alarm journal, audit log and persistent tag values, with no error to say so.
• A plain file copy of a running database is not safe either. It can capture a database and its log at different moments, mid-write.

To back up without stopping Nexus, copy each database with SQLite's own online backup, and copy everything else normally. The sqlite3 command-line tool does this with .backup. It is not part of Raylux: install the sqlite3 package on Linux, or download the command-line tools from sqlite.org on Windows.

Windows

$src  = 'C:\ProgramData\Raylux'
$dest = "D:\Backups\Raylux-$(Get-Date -Format 'yyyy-MM-dd')"
New-Item -ItemType Directory $dest | Out-Null
# Everything except the databases and their -wal/-shm companions
robocopy $src $dest /E /XF *.db *.db-wal *.db-shm
# Each database through SQLite's online backup
Get-ChildItem $src -Filter *.db | ForEach-Object {
    sqlite3.exe $_.FullName ".backup '$dest\$($_.Name)'"
}

Linux

src=/var/lib/raylux
dest="/backups/raylux-$(date +%F)"
sudo mkdir -p "$dest"
# Everything except the databases and their -wal/-shm companions
sudo rsync -a --exclude='*.db' --exclude='*.db-wal' --exclude='*.db-shm' "$src/" "$dest/"
# Each database through SQLite's online backup
for db in "$src"/*.db; do
    sudo sqlite3 "$db" ".backup '$dest/$(basename "$db")'"
done

Each database copy is consistent in itself, but the copies are taken one after another, not at a single instant. That is fine for a restore. If you need one exact point in time across every file, stop Nexus.

Taking a configuration backup

Sign in as an administrator, open Nexus's Backup & Restore page (under System), and choose Download Backup. Nexus keeps running. The file is named raylux_backup_<date>.rnbk; it is JSON inside.

A configuration backup carries the configuration file with two deliberate omissions:

• No user accounts or roles. Those live in raylux_users.json. Restoring a configuration leaves the accounts on the target Nexus exactly as they are.
• No stored passwords. Device, email, SMS, database and SSO passwords appear only as references to raylux_secrets.json, so none travel with the file.

It also does not carry anything in the "No" rows of the table above: history, alarm journal, audit log, persistent tag values, uploaded project files, certificates or the licence.

Restoring

The whole Nexus, from a data-directory backup

1. Install the same version of Raylux that the backup came from.
2. Stop Nexus.
3. Move the current data directory aside — rename it rather than deleting it, in case you need something from it.
4. Put the backup in its place.
5. Start Nexus.

Windows

Stop-Service RayluxNexus
Rename-Item 'C:\ProgramData\Raylux' 'Raylux.before-restore'
Copy-Item 'D:\Backups\Raylux-2026-09-01' 'C:\ProgramData\Raylux' -Recurse
Start-Service RayluxNexus

Linux

sudo systemctl stop raylux-nexus
sudo mv /var/lib/raylux /var/lib/raylux.before-restore
sudo tar xzf /backups/raylux-2026-09-01.tar.gz -C /var/lib
sudo chown -R raylux:raylux /var/lib/raylux
sudo systemctl start raylux-nexus

Nexus finds its files relative to the data directory, so a backup restores into a different path as readily as into the original one. The exception is any absolute path you configured yourself, such as a certificate path.

Everyone signs in with the passwords they had when the backup was taken.

Restore into the same version

Nexus refuses to start on a configuration written by a newer version than itself — the log says so and names both schema versions. Restoring a newer backup onto an older build will not work; install the matching version first.

Restoring onto a different machine

The licence is tied to the hardware of the machine it was issued for. On a different machine, Nexus starts with the restored configuration but reports the licence as not valid on its License page, and runs in the unlicensed tier until a licence for the new machine is installed. On the new machine's License page, enter the licence key and follow the three Offline activation steps (download the request file, upload it at rayluxscada.com/activate, upload the licence file you get back), and plan the move before the old machine is gone.

Alarms that were active at backup time

The alarm journal comes back with the rest of the data, but the list of active alarms does not. An alarm that was active when the backup was taken is raised again the next time its tag's value changes, as a new journal entry; the earlier entry stays in the journal as it was.

Configuration only, from a .rnbk file

On the Backup & Restore page, choose the file or drag it onto the page. Nexus shows what the file contains — schema version, projects, providers and devices — before you confirm. Restoring replaces the whole configuration file. Backups downloaded from older versions carry a .json extension and can still be restored.

Nexus refuses a file written by a newer version than itself, rather than accepting a configuration it would then fail to start on.

Restart Nexus after a configuration restore

A configuration restore replaces the configuration file, but the running Nexus picks up only part of it straight away:

Applies immediately	Applies only after a restart
Projects and screens	Tags added or removed by the restore
What the configuration pages display	Devices added or removed by the restore
	Alarm limits, history settings and tag groups
	Email and SMS delivery settings

Until the restart, screens from the backup can refer to tags that do not yet exist, and alarms are still evaluated against the limits that were in force before the restore. Restart Nexus as soon as the restore completes.

This is a known limitation: Raylux aims for no configuration change to need a gateway restart, and restore does not meet that yet.

When the target is a different Nexus from the one the backup came from:

• Re-enter stored passwords. The file names them without carrying them. At start-up the log lists every credential the configuration refers to that this Nexus does not hold, and those features stay unconfigured until you enter the password again.
• Check the network settings. The file carries the source Nexus's ports, bind address and certificate paths, and they take effect at the restart.
• Accounts are not copied. People sign in with the accounts, and the passwords, that already exist on the target Nexus.

Verify your backups

An untested backup is a hope, not a plan. At least once — and again after any change to how you take backups — restore onto a spare machine or a VM and confirm:

1. Nexus starts, and the log has no errors about the configuration.
2. You can sign in with an existing account.
3. Screens load, and tags show live values.
4. Devices connect.
5. History for a known tag goes back to before the backup was taken.
6. The alarm journal and audit log hold their earlier entries.

Do this before you rely on the backup, not after you need it.

What is not covered

• No automatic scheduled backups. Use your normal backup system, or a scheduled task around the commands above.
• No incremental historian backup. Every copy is a full copy, which matters once the historian is large.
• No live configuration restore. See the restart note above.