Back up and restore the configuration#
The appliance keeps the last 49 committed configurations for rollback — on its own disk. This
guide is about the copy that survives the disk: taking a backup off the box, and putting one back,
on the same appliance or on its replacement.
You need: a super-user (admin) account for anything that restores, or that exports secrets. Any signed-in user can take a redacted export through the web UI or the API; at the CLI it needs the operator class.
The two kinds of backup#
| Redacted | Encrypted | |
|---|---|---|
| Contains | The whole configuration, with every secret replaced by ##SECRET-DATA## and every URL cut down to where it points (https://hooks.example.net/##SECRET-DATA##) |
The whole configuration including every secret, encrypted under a passphrase you choose |
| Use it for | Sending to support, attaching to a ticket, comparing two appliances | Restoring this appliance, or building its replacement |
| Restores onto | Only an appliance that already holds the secrets | Any appliance of the same product |
| Who can export it | Any signed-in role (operator at the CLI) | Super-user |
There is no export with secrets in clear text.
A URL counts as a secret wherever it could carry one: a user name and password before the host, a
token in the path, a key in the query. A redacted backup — like show configuration and the
configuration API for any role below admin — keeps the scheme, host and port and replaces the
rest. A URL with nothing after the host is shown as it is.
The passphrase is not recoverable
The passphrase is never stored on the appliance and is not in the backup. An encrypted backup whose passphrase is lost cannot be opened by anyone, including Netavo support. It must be at least 12 characters; use printable ASCII if you may ever restore at the CLI.
What a backup does not contain#
A backup is the configuration and nothing else. A replacement appliance needs these separately:
| Not in the backup | On a replacement |
|---|---|
| The web UI's TLS certificate and key | A self-signed certificate is generated at first start. Upload a custom certificate again. Other appliances that list this one as a fleet peer pin its certificate — re-pin it on each of them |
| The licence | Activate the replacement (request licensing activate); the licence is bound to the hardware and is not transferable by copying files |
| Subscriber address bindings | Rebuilt as subscribers reconnect or renew |
| SSH host keys | Generated on the replacement; clients will see a new host key |
| The rollback history | Starts again from the restore |
| Files the configuration refers to by path (CA files, key files) | Copy them to the same paths |
Take a backup#
Configuration → Backup & restore. Download redacted saves the file straight away. Download encrypted asks for a passphrase twice, then saves it.
You are asked for the passphrase twice; then the backup — a JSON document beginning
"format": "netavo-config-backup" — is printed without paging.
The backup is printed for your SSH client to capture. The passphrase is asked for, never typed on the command line, so it is not echoed and does not appear in the command history or in TACACS+ accounting.
To write it to a file on the appliance instead, add file <name>:
Files are written to /etc/netavo-bng/backups/ and are readable only by root and the
appliance's group. Copy them off with scp. Use redacted in place of encrypted for a
redacted backup; it asks for no passphrase.
# Redacted: any role
curl -sS -H "Authorization: Bearer $TOKEN" https://lns1:8443/api/v1/config/export \
| jq -r .backup > lns1-redacted.json
# Encrypted: admin. The passphrase goes in the body, never the URL.
curl -sS -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d "{\"passphrase\": \"$PASSPHRASE\"}" https://lns1:8443/api/v1/config/export \
| jq -r .backup > lns1-encrypted.json
The response also carries a suggested fileName. See the
Configuration API reference.
Every export is recorded in the appliance's log (CONFIG_EXPORTED) with who took it and which
kind.
Restore a backup#
A restore never writes the running configuration directly. The backup is loaded into the candidate configuration, checked, and shown to you; it takes effect only when it is committed, exactly like a change you typed.
Read the report before you commit#
Whichever way you restore, you are shown the same report first:
- Where the backup came from — appliance, software release, when and by whom it was exported.
- Whether it validates on this appliance.
- The changes against the running configuration, as
compareshows them. Secret values are never shown. - Secrets that differ — listed by path, because the diff cannot show them.
- Box-specific values that differ — hostname, router IDs, the IS-IS NET, the management network, interface addresses, data-plane ports, listener addresses, the RADIUS NAS identity. On a replacement for the same appliance these are what you want. On any other appliance they are how two routers end up with the same router ID: check each one.
- For a redacted backup, the secrets kept from this appliance and the secrets missing.
Steps#
- Configuration → Backup & restore, choose the backup file, and enter its passphrase if it is encrypted.
- Preview shows the report. Nothing has changed yet.
- Restore commits it. Tick Roll back automatically unless I confirm when the restore could cut off your own access — the management network, the web UI listeners, operator accounts. If you cannot reach the appliance to press Confirm within the window, the previous configuration comes back by itself.
load override terminal waits for you to paste the backup and end it with Ctrl-D, then asks
for the passphrase if the backup is encrypted. It prints the report described above and stops:
nothing is committed. compare shows the changes; commit confirm 10 commits them with a
ten-minute window, and the plain commit that follows confirms it.
load override file <name> reads the backup from /etc/netavo-bng/backups/<name> instead of a
paste. load override replaces the whole candidate; there is no merge. Until you commit, you
can edit the candidate with set and delete — for example to change the hostname for a
different appliance — or abandon it with rollback 0.
jq -n --rawfile backup lns1-encrypted.json --arg passphrase "$PASSPHRASE" \
'{backup: $backup, passphrase: $passphrase, action: "preview"}' \
| curl -sS -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d @- https://replacement:8443/api/v1/config/import
action is preview (the default; changes nothing), commit, or commitConfirm with
confirmMinutes. After commitConfirm, POST /api/v1/config/confirm makes it permanent.
Restoring a redacted backup#
A redacted backup has no secrets in it, so the appliance supplies its own: for each placeholder it keeps the secret it currently holds at the same place — a RADIUS server is matched by its address, a local subscriber by its username, and a URL is kept only if the appliance's own URL points at the same host. That makes a redacted backup a faithful restore on the appliance it came from, even after its secrets have been rotated.
Matching is exact and one-to-one. A name must be spelled as it is on the appliance, including its
case — Alice and alice are different accounts — and if the backup or the appliance holds the
same name twice, or two entries that cannot be told apart, none of them is given a secret.
A placeholder with nothing to match, or with more than one possible match, is reported as
missing and left empty; it is never filled with a guess. The web UI and the API will not commit a restore with missing secrets. At the CLI the
load succeeds, lists them, and you can set each one before committing. To build a replacement
appliance, use an encrypted backup.
Verify#
- In configuration mode,
comparereports no differences once the restore is committed. - A new backup taken straight afterwards carries the restore as its
commit: your user name and the comment restore from backup of …. (Configuration → History lists the versions you can roll back to, so the restore itself appears there after the next commit; the version it replaced is at the top.) - The log has a
CONFIG_IMPORTEDrecord: who, which kind, from which appliance, the outcome, and how many lines and secrets changed. - Sections marked as needing a restart in the configuration editor take full effect only after
request system restart.
When a restore is refused#
| Message | Meaning |
|---|---|
| the passphrase is wrong, or the file has been altered or damaged | The backup did not decrypt. An encrypted backup is authenticated as a whole: a file changed anywhere, including its header, gives the same answer as a wrong passphrase. Nothing was loaded |
| the backup holds a setting this release does not know | It was written by a newer release than this appliance runs. The message names the setting and the release. Upgrade the appliance first; nothing was loaded |
| the backup is of a … configuration; this is … | A backup from a different product (BNG and VPE backups are not interchangeable) |
| the configuration in the backup has a null at … | The file was edited by hand: an export never writes null. Remove the entry (or give it a value) at the place named. Nothing was loaded |
| this is a bare configuration file, not a backup | The file is a raw config.json, not something the export produced |
| Validation failed: … | The configuration was read but this appliance will not accept it — typically because it refers to something this hardware does not have. At the CLI, fix it in the candidate and commit; elsewhere, nothing was committed |
| N secret(s) are neither in the backup nor on this box | A redacted backup, on an appliance that does not hold its secrets. Use an encrypted backup, or load it at the CLI and set them |
| configuration is being edited by another session | Someone has uncommitted changes open. Their candidate was not touched |
A backup written by an older release is accepted: it is read the way that release's configuration is read after an upgrade.