Backup & Restore

The Settings > Diagnostics & Info > Backup & Restore tab (/settings/diagnostics/backup, Admin only, Core only; /settings/backup redirects there) makes and restores a backup that is two files:

Drivers you downloaded from a vendor catalog (HP, Dell, Lenovo, Microsoft Surface) are not in the assets backup. The settings backup records where each came from and its SHA-256, and a restore downloads them again in the background, which is what keeps file 2 small. See Catalog drivers come back by themselves.

Take file 2 first, then file 1: the settings file records which assets backup it was taken against (a backup id), so a restore can tell that the two belong together.

Settings Backup (file 1)#

Download Backup exports a single JSON file containing:

• All application settings
• Deployment recipes (including their task sequences)
• Relay groups (with their recipe and driver assignments)
• Notification channels
• Answer file templates
• The list of Windows images (name, SHA-256, whether built here or uploaded) and of the vendor catalog drivers (download address, SHA-256, model) - descriptions only, not the files
• The id of the assets backup it was taken against

Machines and logs are not included, the large files (images, ISOs, manually uploaded drivers) are in the assets backup, and no user account is ever created or changed by a restore (user metadata is listed for reference only). No password, and no password hash, is exported.

Sensitive Settings and the Passphrase#

Sensitive values (SMTP password, agent passwords, Azure secrets, the relay registration key) are omitted from the export unless you supply a passphrase. To include them, enter a passphrase before downloading: those values are then encrypted with AES-GCM using a key derived from the passphrase (PBKDF2-SHA256, 210,000 iterations). The passphrase is not stored anywhere - keep it with the backup.

A passphrase does a second job, described under Integrity below: it is also what lets a restore prove the file has not been altered. Take backups with a passphrase.

A backup without a passphrase is not an encrypted file. Omitting the secret settings is not the same as the file being safe to email or attach to a ticket. A passphrase-less export still contains, in plain text:

• Notification channel configuration (ConfigJson) other than its credentials - your SMTP server address and sender identity, a Webex room id. From backup format v5 the credential fields (Slack and Teams webhook URLs, the Webex bot token, Pushover tokens) are treated like sensitive settings: omitted without a passphrase (re-enter them after restoring), encrypted with one. Older backups carry them in plain text.
• Every user account's email address, display name and role.
• Every non-secret setting: organization name, domain and OU for domain join, server addresses, retention policy, and so on.

The local admin password hash is not in the file at any passphrase - it is excluded from the export outright, because a restore never applies it. Backups taken before 1.4.2 do contain it; treat those files as credential material.

The WinPE boot password is in the same position. Both its readable value and its hash are treated as secrets now, so a passphrase-less export carries neither. Backups taken before this release contain the hash in plain text, and it is offline-crackable: treat those files as credential material too.

The trial start date is never exported and never restored, in either direction. The evaluation clock belongs to the install it started on - a backup cannot move it, and restoring one cannot extend or shorten your trial.

The ACME account (its key and account URL), the external-account HMAC key, and any staged certificate are in the same position: never exported, never restored. They are encrypted with a key belonging to the machine that created them, so a copy restored elsewhere could not be read there anyway - it would only turn a working server into one that refuses every certificate request. An absent account is simply registered afresh on the next request, which is why dropping it is the better failure. Your ACME configuration - directory URL, certificate names, contact, CA root, external-account key ID - does travel, so a restored server points at the same CA and only needs its account back. See Certificate Authority for Reset ACME account, which is also the fix if you restore an older backup file that still contains one.

Restoring a backup#

Restore asks for both files. Each is optional on its own, and the page tells you in plain words what leaving one out costs before you click Restore:

• No assets backup chosen: ISOs, Windows images and manually uploaded drivers are not restored. Recipes that use an image this server does not already have cannot be restored until you add it.
• No settings backup chosen: settings, recipes, notification channels, answer file templates and relay groups are not restored.
• An assets backup that left things out on purpose (you can exclude ISOs, Windows images or manual drivers when you make it) says so, and the restore repeats it. Leaving out Windows images you built here is the risky one: Windows updates change over time, so a built image cannot be rebuilt exactly from its ISO.

Before anything is written, FluxDeploy checks everything it can:

1. The settings file's version, passphrase and signature.
2. The assets folder's manifest.
3. That the two belong together: if the settings file names a different assets backup than the folder you chose, the restore is refused and nothing changes.
4. When the settings file is verified, that every Windows image in the assets folder has a SHA-256 the settings file recorded. The folder's own manifest is not signed, so a swapped image with a recomputed manifest hash is caught here, before anything is copied.

Scripts and API clients that call POST /api/settings/restore (or certificate/upload) with a session cookie must send an X-FluxDeploy-Request header (any value), or authenticate with an API token. A form submitted from another web page cannot set that header, which is what keeps a page elsewhere on your network from submitting a restore in your browser.

Then the assets go back first (each file is checked against its recorded SHA-256 while it is copied, and the Windows image, ISO and driver are registered, so they show up under Images, ISO Library and Drivers), and then the settings, which now find the images their recipes need. If one assets file fails its checksum, the whole assets restore is refused and the files copied so far are removed: you never end up with half an image library.

Choose the .json file, enter the passphrase if one was used at export, optionally enter the assets folder (and click Check to see what is in it), and click Restore. Restoring the settings file:

• Overwrites all settings, recipes, notification channels, answer file templates, and relay groups with the backup's contents
• Never touches user accounts - users are skipped on import
• Never overwrites the admin password
• Runs as a single transaction - a failed restore changes nothing
• Is refused before anything is written if the file's contents cannot be shown to be unaltered - see Integrity
• Is refused before anything is written if a value in the file is longer than the column that holds it, naming the setting, channel, recipe or task step at fault so you can correct the file
• Keeps each machine's assigned recipe, and each relay site's group membership, by matching on name. Anything whose recipe or group is not in the backup is left unassigned rather than blocking the restore, and the result message says how many

If the backup contains encrypted sensitive settings, the matching passphrase is required - a backup created with a passphrase cannot be restored without it.

Integrity: what a restore can and cannot verify#

A restore installs deployment recipes, and a recipe carries task steps that run as SYSTEM on every machine deployed from it afterwards. So the backup file itself is a thing an attacker would like to edit - on a shared drive, in a support-ticket attachment, on an operator's laptop. Nothing about it needs a FluxDeploy account.

From 1.4.3 the file therefore carries an integrity value covering everything in it - every setting, recipe, task step, answer file template, notification channel and image reference - and the restore checks it before it parses or applies anything.

Each encrypted value is also bound to the setting it belongs to, so a value cannot be moved from one setting to another inside the file.

When a restore is refused#

The message says which of these you have. What to do about each:

A restore accepted without verification is recorded as such: the result message and the audit log entry both begin with "Integrity NOT verified". Every export is audited with its integrity value too, so an older backup's digest can be compared against what the server recorded when it wrote the file.

The single thing to change: take backups with a passphrase. They are signed, verified automatically, and never need this confirmation.

After a Restore#

No server restart is needed. Most settings are read from the database each time they are used, so they are live the moment the restore commits. The few that the server also holds in memory are re-read as part of the restore itself:

If the restore is refused part-way through, nothing above happens either - the transaction and the in-memory state are rolled back together.

Restoring onto a New Server#

This is the case the two files exist for, and it is also on the first-run /setup page ("Restoring from a previous installation?"), which asks for the same two files.

Recipes reference a Windows image, and relay groups reference driver packages. Neither is in the settings file itself, so those references are matched to what the target server has:

• Images are matched by SHA-256 first, then by name. If a recipe's image is not on the target server, the restore is refused before anything is written, naming the recipes and images involved. When the settings file was taken together with an assets backup, the message tells you to restore that folder as well. Otherwise import the missing images under Images, then restore again.
• Driver packages are matched by name. A manually uploaded driver that is missing is not fatal: that assignment is dropped, the rest of the restore proceeds, and the result message names what was skipped.
• Catalog drivers are pending, not missing: see the next section.

Catalog drivers come back by themselves#

Every catalog driver recorded in the settings file is queued for download as soon as the restore finishes, through the same download queue the Drivers page uses. They download in the background; progress shows on the Backup & Restore tab and under Activity > Jobs.

Recipes and relay groups that used a catalog driver keep that assignment: it is applied the moment the download registers the driver.

The default relay group is kept across a restore, never deleted and re-created. A backup taken by a version that has the default group records which group is the default one and exactly what it held, and that is what it holds after the restore - a recipe or driver you had taken out of it stays out. A backup from before the default group existed gets what an upgrade gives it: every restored recipe and every Windows driver. A relay site whose relay group is not in the backup moves to the default group.

Each download is checked against the SHA-256 recorded in the backup. Nothing is ever substituted silently. A driver that cannot be brought back exactly is listed under Needs your attention (on the Backup & Restore tab, on the Get started page and as one line on the Dashboard) with the reason, and stays there until you dismiss it:

Existing installs and older backups. A driver that was added before FluxDeploy recorded where drivers come from has no source recorded and is treated as manually uploaded, so it goes into the assets backup until you download it again from the catalog. Backups made by an older FluxDeploy (format v1 to v3) and older Files Backup folders still restore exactly as before; they simply carry no catalog list and no backup id, so nothing is downloaded and the pair check does not apply.

Backup File Versions#

The file records the backup format it was written in, separately from the product version.

• A backup from an older FluxDeploy restores normally, once you have confirmed you accept a file whose contents cannot be verified (see Integrity). Any collection the older format did not carry is left untouched rather than being wiped.
• A backup that does not say which collections it carries - an older file, or one that has been edited - is applied to what it visibly contains and nothing else. Recipes, answer file templates, relay groups and notification channels are only replaced when the file actually holds them, so no deletion can ever follow from a missing line.
• A backup from a newer FluxDeploy is refused: this server cannot see everything the file contains, so applying it would look like a clean restore while silently dropping the parts it does not recognize. Upgrade the server to at least the version named in the message, then restore. The same applies to a settings file in format v4 (this release) restored on an older server, and to an assets folder written by a newer FluxDeploy.
• Format v4 adds the backup id, the image list (each Windows image with whether it was built here or uploaded, its size and SHA-256) and the catalog driver list. The integrity value of a v1 to v3 file covers exactly what it covered when it was written, so older backups still verify; a file that declares an older format but carries v4 content is refused as edited.

Assets Backup (file 2)#

WIM and ISO files are too large to round-trip through a browser, so the Assets Backup card copies them to a server-side folder instead:

1. Choose what to include: Windows images, ISOs, manually uploaded drivers. Everything is on by default; anything you untick is recorded as left out in the backup, and a restore says so instead of failing later. If you untick Windows images while some were built here, the card warns you, because they cannot be rebuilt exactly.
2. Enter a destination folder (local disk or a UNC share reachable by the server) and click Start Backup. Files are copied into wim/, iso/ and drivers/ (each driver as one zip) beside a manifest.json that records every file's name, size and SHA-256, the backup id and what was left out. The folder is written with the manifest last, so an interrupted backup has no manifest and can never be mistaken for a complete one.
3. Download the settings backup after this: it records the assets backup's id.

A file that is already missing on the server when you back up is named in the result (and in the manifest) rather than dropped quietly.

To restore, use Restore above with the folder. The restore:

• checks the manifest, then every file's size and SHA-256 while copying it, and refuses all of it if any one fails;
• decides where each file goes by itself (your Images folder, your ISO folder, your driver store). It never reads a destination out of the manifest, because the manifest is a file on a share and /setup runs before any account exists;
• opens driver zips only after their hash matches, with the same zip-slip and zip-bomb protections as any driver upload;
• is safe to run twice: items already on the server are left alone, and a registered image whose file went missing is brought back to the same path.

Older Files Backup folders#

A folder made by an earlier FluxDeploy (WIM and ISO files with a manifest.json but no backup id) is a Files Backup. It still works the way it always did, under Restore Missing Files (older files backups): scan, then copy back only what is missing from its original location. It copies files and does not register them. A two-file assets folder pointed at that panel is refused with a message telling you to use Restore instead.

Tip: For the database itself, SQLite installations can download a copy of the database file from Settings > General > Database. SQL Server installations should use their normal SQL backup tooling.