Backup and Restore

Last updated

Backup (admin section of the sidebar) has six cards: Export Backup, Scheduled Backups, Import Backup, Selective Export, Selective Import, and the database tools (health check, subsystem reset, reset to defaults). Admin only. This article covers the full backup; see Selective Export and Import and Database Health and Resets for the rest.

What a full backup contains

The download is a single SQLite file (scadaink-backup-YYYY-MM-DDTHH-MM-SS.db) that merges both of the appliance's databases and the configuration files kept beside them:

• Included, from the databases: users (with password hashes), roles, per-user access, security levels, devices and tag subscriptions, local and expression tags, dashboards, templates, scripts and libraries, custom pages, workflows, ladder logic, alarm rules and pipelines, notification groups, recipes, work orders and instructions, OEE/downtime/quality configuration and events, SPC, reports and schedules, settings (including the license key and feature toggles), secrets and 2FA secrets (encrypted), the audit log, and every data table with its rows.
• Included, from disk: everything on the Files page (apps/api/data/uploads) — the images, stylesheets and documents your dashboards and custom pages point at; vision test images; and the OPC-UA client certificates you have trusted, with their issuing CAs. These are stored inside the same .db file, so a backup is still one file to copy.
• Not included: historian data in InfluxDB (or the SQL historian's external database); archived vision captures; generated report files; the TLS certificate and its key; the OPC-UA server's own certificate and key; the JWT secret files; network settings (those live in the appliance's network manager).

The card shows the combined Database size, with the file part called out separately.

Why some things are left out

• Historian data, report files and vision captures are output, not configuration. They are produced again by the next shift and would grow every backup without limit — and a backup too large to take is a backup nobody has.
• Private keys — the TLS key, the OPC-UA server key and the JWT secret files — are left out on purpose. A backup travels on a memory stick and through email, and it already holds every stored credential in a form only those keys open. Leaving the keys out is what keeps the file from being a credential dump. The certificates are generated again on the appliance that restores the backup.

Back up before upgrades, before importing anything, and on a schedule you can keep off the appliance.

Export

1. Open Backup.
2. Click Download Backup. The browser saves the .db file.

The export checkpoints the database first, so it contains every committed change. It can be taken while the appliance is running.

Warning: The file contains password hashes, the license key and encrypted credentials. Store it like a password.

Scheduled backups

The Scheduled Backups card takes the same full backup automatically.

Field	Default	Notes
Back up on a schedule	off	Turns the schedule on
Frequency	Daily	Daily or Weekly (then pick the Day)
Time	02:00	In the appliance's time zone (Appliance → System)
Keep newest	7	1–365. After each run, older scheduled backups in the destination beyond this number are deleted. Only scheduled backups (scadaink-scheduled-….db) are ever deleted; downloads and the safety backups taken before a reset are not
Destination folder	empty	Empty writes to the default backups folder beside the database (the hint under the field shows the full path). Otherwise a full path, such as a USB drive or network share mounted on the appliance

Click Save schedule. A destination is checked when you save: it must be a full path to a folder that already exists and that the appliance can write to (… does not exist. Plug in or mount the drive first, or create the folder.). The appliance does not create or mount it: a mount point that quietly turned into an ordinary folder while the drive was unplugged would fill the appliance's own storage. Mounting a network share is done on the appliance itself, outside the web interface.

Run now takes a scheduled backup immediately, into the same destination, and prunes the same way. Next: shows when the schedule fires next.

The box below shows the last run: Last run … : file (size), or Last run … failed: reason — for example a drive that was unplugged since the schedule was saved. A failed scheduled run also raises a Scheduled Backup Failed notification and is written to the service log. The list at the bottom shows the scheduled backups now in the destination, newest first, each with a download button.

• A file is written under a temporary name (.partial) and renamed when complete, so a power cut or a pulled drive never leaves a file that looks like a whole backup.
• A run missed while the appliance was off is not made up later; the next one runs at its next scheduled time.
• Restore a scheduled backup exactly like a downloaded one: download it from the list (or copy it off the drive) and import it below.

Restore

1. Export a backup of the current state first, if it matters.
2. In Import Backup, drop a .db file on the drop zone or click Browse Files.
3. Confirm twice (WARNING: Importing a backup will REPLACE ALL current data… and Final confirmation…).
4. On success the message reads Backup imported successfully. Please restart the server for changes to take effect., followed by how many files were written back to disk.
5. Restart the API immediately: Appliance → System → Restart API (see Appliance System). Until it restarts the API has no database and every page fails.
6. After the restart, the restored database's activity log gets an import / backup entry naming who restored it and whether the restored audit trail verifies (The restored audit trail verifies.). The import cannot be logged before the restart because the database is closed. See Audit Log.
7. Sign in with an account from the backup.

What the import does: it checks the file is SQLite with users and devices tables, closes the live databases, copies the file over the configuration database, and deletes the separate data-tables database so the restored data tables are split back out on the next start. It then writes the backup's files back to disk. A backup from older software is brought up to date by the database migrations on the next start, and one taken before backups carried files simply restores no files.

Restoring files overwrites but never deletes. A file the backup does not contain is left where it is, so a mistaken import cannot destroy the appliance's only copy of a drawing; once the rows naming it are gone it is simply unreachable.

Restoring onto a different appliance

A backup can clone configuration onto a replacement unit, with these consequences:

• License: keys are locked to the hardware ID. The restored key will not verify on different hardware; activate a key for the new appliance.
• Secrets and 2FA: encrypted with the original appliance's JWT secret, which a backup deliberately does not carry, so they cannot be decrypted. Re-enter secrets; users with 2FA sign in with a recovery code or have an admin reset it. To avoid this, copy apps/api/data/.jwt-secret and .jwt-refresh-secret from the old unit by hand before restoring.
• Files come across in the backup, so uploads, vision test images and the OPC-UA trust list need no separate step.
• Historian data and certificates must be moved separately, or recreated. The new appliance generates its own TLS and OPC-UA server certificates; clients that pinned the old ones have to trust the new ones.

Troubleshooting

Message	Cause	Fix
Only .db files are accepted	Wrong file type	Use the .db from Download Backup; JSON files go to Selective Import
Invalid backup: missing tables: users, devices	Not a Scada.Ink backup	Pick the right file
Invalid backup file: file is not a database	Damaged or wrong file	Use another copy
Every page errors after a successful import	The API was not restarted	Restart API from Appliance → System, or reboot
Failed to build backup: …	Disk full or unreadable database	Free disk space; run the health check
The appliance cannot write to …	The destination folder's permissions don't let the appliance's service user write	Fix the folder's permissions or mount options on the appliance
Scheduled backup failed: … does not exist	The drive was unplugged or the share unmounted	Reconnect it, then Run now to check
Email/2FA broken after restoring on new hardware	Different JWT secret	See Restoring onto a different appliance

Method	Endpoint	Purpose
GET	/api/admin/backup/info	Database sizes and paths
GET	/api/admin/backup/export	Download the merged .db
POST	/api/admin/backup/import	Multipart field backup; replaces the database
GET	/api/admin/backup/schedule	The schedule, its last run, next run, and the scheduled backups in the destination
PUT	/api/admin/backup/schedule	{ "enabled": true, "frequency": "weekly", "dayOfWeek": 0, "timeOfDay": "02:00", "retentionCount": 4, "destination": "/media/usb/backups" } — any subset
POST	/api/admin/backup/schedule/run	Take a scheduled backup now
GET	/api/admin/backup/schedule/files/:filename	Download one scheduled backup

See also

• Selective Export and Import
• Database Health, Subsystem Reset and Factory Reset
• Secrets
• Historian Storage, Outages and Retention
• File Manager
• Configuration Bundles and Entity Types
• Software updates
• Activating a license key