Backup and restore
Aperture has a built-in configuration backup: one JSON file with your cameras, users, rules, settings, storage destinations, camera groups, automations and webhooks. It does not contain footage, events, API tokens or extensions. This page explains what the file holds, how to restore it, how to back up the complete state instead, and how to move Aperture to a new machine.
Three kinds of backup
Section titled “Three kinds of backup”| Backup | Contains | Use it for |
|---|---|---|
| Configuration backup (in the app) | Cameras, users, settings, schedules, notification channels and rules, preferences, camera access lists, passkeys, storage destinations and mirrors, camera groups, automations, webhooks | Undoing a configuration mistake; rebuilding on a fresh install |
| State backup (files) | The whole database and secrets.json |
Recovering everything except footage; a safe point before an update |
| Footage backup | The recordings | Keeping footage when a disk fails |
The configuration backup is the quickest. The state backup is the complete one.
Configuration backup
Section titled “Configuration backup”Open Settings › System and, under Maintenance, click Download backup. You get aperture-backup-<date>-<time>.json. Only admins can download or restore it.
What is in it
Section titled “What is in it”The file holds every row of these database tables:
| Table | What it holds |
|---|---|
users |
Accounts, roles, password hashes, two-factor secrets and recovery codes (hashed) |
storage_locations |
Storage destinations: name, type, folder or share settings, allocation, and the encrypted share password or SSH key |
cameras |
Every camera with its stream addresses, recording mode, retention, motion zones and options |
camera_destinations |
Which destinations each camera records and mirrors to, with each mirror’s retention |
settings |
App-wide settings: site, storage allocation of Primary storage, detection, Home Assistant and single sign-on settings, push keys and more |
schedules |
Recording schedules |
notify_channels, notify_rules |
Notification channels and rules |
user_preferences |
Each user’s preferences |
user_camera_acl |
Which cameras each viewer may see |
webauthn_credentials |
Registered passkeys |
camera_groups |
Camera groups |
automations |
Automations |
webhooks |
Webhooks with their signing secrets |
Three kinds of secret in it are encrypted with the key in data/secrets.json: storage-destination passwords and SSH keys, camera ONVIF passwords, and the Eufy password. A server with a different key cannot decrypt them. A restore there clears them and lists them, so you know which to enter again; see Restore it and Moving to new hardware.
What is not in it
Section titled “What is not in it”- Footage and its index (
segments, mirror copies), events, detections and object tracks, event thumbnails. - API tokens and signed-in sessions. Integrations such as Home Assistant need a new token after a restore onto a new install.
- Extensions, with their files and settings. A JSON file cannot carry an extension’s files, so a restore leaves the extensions installed on the server exactly as they are: it neither adds nor removes any. After a restore onto a new install, install them again.
- Push subscriptions: every phone has to switch push on again after a restore onto a new install.
- The activity log, notification log, webhook delivery log, shares, exports and weather history.
- The object-recognition runtime and models in
/var/lib/aperture/ai, and HomeKit pairing data.
Restore it
Section titled “Restore it”- Open Settings › System and, under Maintenance, click Restore….
- Choose the backup file and confirm. The app warns that this replaces all configuration and may sign you out.
- If everything came back as it was, the page reloads after a moment. Otherwise it lists what needs your attention (passwords to enter again, allocations it did not restore, destinations it kept) and waits. Note the list, then click Reload.
- Restart Aperture so every part picks up the restored settings at once:
sudo systemctl restart apertureWhat a restore does:
- It replaces the rows of each table listed above that the file contains, in one transaction: either everything is restored or nothing changes. A table the file does not contain is left as it is. A backup from an older version, without storage destinations, camera groups, automations or webhooks, leaves those alone.
- It runs with foreign keys off, so replacing the cameras does not delete the footage index of those cameras. Footage of cameras that are not in the backup stays on disk and in the database.
- Passwords this server cannot decrypt are cleared. Storage-destination passwords and keys, ONVIF passwords and the Eufy password open only with the key of the server that made the backup. Any that do not open here are removed and listed: enter them again. A restore onto the same server keeps them all.
- Allocations of local destinations are not restored. A local folder’s allocation reserves real disk space, so a local destination keeps the allocation it has on this server, and one that is new here gets none. The restore lists those whose allocation differs from the backup; set it again under Settings › Recording & Storage. Network shares’ allocations are only caps and are restored as they are. The allocation of Primary storage is a setting and comes from the backup.
- Destinations that still hold footage are kept. A destination on this server that is not in the backup stays if footage or mirror copies are stored on it, or if it is a local folder with an allocation. Its footage stays playable and retention can still delete it. The restore lists these; remove them under Settings › Recording & Storage if you no longer need them.
- Extensions, API tokens and signed-in sessions are not touched.
- It refuses a backup made by a newer version of Aperture (a higher database schema) with “backup is from a newer version (schema vN > vM); upgrade this server first”. A backup from an older version is accepted.
- It refuses a file that is not valid JSON or has no tables. The upload may be up to 256 MB.
- Your own account is replaced too. If the backup does not contain it, you are signed out and sign in with an account from the backup.
Automate it
Section titled “Automate it”The backup is an API call. On the server, the local CLI token is enough:
sudo sh -c 'curl -sf -H "Authorization: Bearer $(cat /var/lib/aperture/data/cli.token)" \ -o /root/aperture-backup-$(date +%F).json http://127.0.0.1:8971/api/v1/system/backup'Scoped API tokens cannot download or restore backups; only a signed-in admin or the CLI token can. Each download is recorded in the activity log.
State backup
Section titled “State backup”The database data/aperture.db holds everything the configuration backup leaves out (events, the footage index, API tokens, extension settings), and data/secrets.json holds the key that decrypts stored passwords. Back up both, together.
Safest: with the service stopped
Section titled “Safest: with the service stopped”sudo systemctl stop aperturesudo cp -a /var/lib/aperture/data/aperture.db* /var/lib/aperture/data/secrets.json /root/aperture-state/sudo systemctl start apertureCreate /root/aperture-state/ first. Copy all aperture.db* files: the database runs in WAL mode and may have -wal and -shm files next to it. Recording stops for the few seconds the service is down.
While it runs
Section titled “While it runs”SQLite’s online backup makes a consistent copy without stopping anything. It needs the sqlite3 package:
sudo apt install -y sqlite3sudo sqlite3 /var/lib/aperture/data/aperture.db ".backup '/root/aperture-state/aperture.db'"sudo cp /var/lib/aperture/data/secrets.json /root/aperture-state/Do not copy a live database with plain cp: the copy can catch it halfway through a write.
Restore a state backup
Section titled “Restore a state backup”- Stop Aperture:
sudo systemctl stop aperture. - Put
aperture.dbandsecrets.jsonback into/var/lib/aperture/data/. Delete anyaperture.db-walandaperture.db-shmleft from the newer database first. - Start it:
sudo systemctl start aperture. - Footage recorded after the backup is on disk but not in the restored index. Open Settings › Recording & Storage and click Re-scan: Aperture indexes every segment file it finds for its cameras.
Diagnostics bundle
Section titled “Diagnostics bundle”When you ask for help, a diagnostics bundle shows what the server sees. In Settings › System, under Maintenance, click Download diagnostics. You get aperture-diagnostics-<time>.tar.gz with:
| File | Contents |
|---|---|
status.json |
The system health snapshot: go2rtc, each camera’s live and recording state, watchdog restarts, today’s coverage, storage, integrations |
config.json |
Listen address, data and recordings folders, public URL, go2rtc addresses. No secrets. |
logs.txt |
The last 500 lines of nvrd’s log since it started |
version.txt |
Version and commit |
It holds no passwords or tokens, but it does hold camera names, and log lines can hold addresses on your network. Read it before you post it publicly. An admin API token with the system:read scope can fetch it from /api/v1/system/diagnostics.
Footage
Section titled “Footage”Footage is not in any of the backups above. Two ways to keep a second copy:
- Mirror to another destination. In the app, a camera can record to several destinations at once, for example a local disk and a NAS, each with its own retention. See Storage. This keeps the copy current without scripts.
- Copy the files. Footage is plain MPEG-TS files under
/var/lib/aperture/recordings/<camera id>/, named by their start time in Unix seconds. Copy them withrsyncor your backup tool. Skip.aperture-reservationin the recordings folder: it is the hard storage reservation, a large preallocated file with no footage in it.
Copied footage is only playable in Aperture if the database still knows those cameras. To bring files back, put them in the camera’s folder and click Re-scan under Settings › Recording & Storage.
Moving to new hardware
Section titled “Moving to new hardware”The complete way moves the whole state folder, so everything comes along: footage, events, settings, extensions, HomeKit pairing and the encryption key.
-
Install on the new machine. Prepare it and run
make installas described in Install. The installer enables the services but does not start them, so nothing touches the cameras yet. Do not start them. -
Prepare the disks. If the old machine had a footage disk mounted at
/var/lib/aperture/recordings, mount the new one at the same place now. Paths must stay the same: the database stores the absolute path of every segment. -
Stop the old machine’s services:
Terminal window sudo systemctl stop aperture-discovery aperture aperture-go2rtc -
Copy the state and the configuration to the new machine, keeping owners and permissions. Extensions’ files belong to numeric user ids that must survive the copy. As root on both ends, for example:
Terminal window sudo rsync -aHAX --numeric-ids --exclude .aperture-reservation \/var/lib/aperture/ root@192.168.1.11:/var/lib/aperture/sudo rsync -a /etc/aperture/aperture.env root@192.168.1.11:/etc/aperture/aperture.env -
Update the addresses in the new machine’s
/etc/aperture/aperture.envif its address changed:APERTURE_STREAM_HOSTandAPERTURE_PUBLIC_URL. -
Check the retention plan before the first start.
deploy/check-retention.shcomputes what the retention janitor will delete on its first pass, so a wrong layout is caught while it is still a prediction. It needssqlite3:Terminal window cd ~/aperturesudo deploy/check-retention.sh /var/lib/aperture/data/aperture.dbPASSmeans routine pruning at most.FAILmeans the first pass would delete a large part of the archive: do not start until you know why. -
Start the new machine:
Terminal window sudo systemctl start mosquitto aperture-go2rtc aperture aperture-discovery -
Point everything at it: your reverse proxy or DNS name, Home Assistant’s MQTT broker address if it used the old machine’s broker, and any bookmarks. Leave the old machine’s services stopped: two servers recording the same cameras and publishing to the same Home Assistant conflict.
The hard storage reservation, if you use one, is rebuilt on the new disk by the first retention pass, which runs right after the start.
The configuration-only way
Section titled “The configuration-only way”If you cannot copy the state folder (for example, the old disk is failing), you can rebuild from a configuration backup:
- Install Aperture on the new machine and do not start it. If local destinations recorded to other disks, mount those disks at the same paths: the backup keeps each destination’s folder.
- If you still have the old
secrets.json, put it in/var/lib/aperture/data/before the first start, so encrypted passwords in the backup stay readable. Do this only on a fresh install that has no database yet. - Start Aperture, create a temporary admin account, and restore the backup under Settings › System. Your old accounts replace the temporary one; sign in with your old password. Note the list the restore shows.
- Restart Aperture.
- Enter again each password the restore listed. Without the old
secrets.json, that is every storage-destination password or key, every ONVIF password and the Eufy password. - Re-add what the backup does not carry: API tokens and extensions. Switch push on again on each phone.
- In Settings › Recording & Storage, check the allocation of Primary storage (the backup brings the old machine’s value, which may not fit the new disk) and set the allocation of each local destination, which the restore leaves unset on a new install.
- If you have the old footage, copy each camera’s folder into
/var/lib/aperture/recordings/and click Re-scan under Settings › Recording & Storage. Events and their thumbnails from before the move are not recovered.
Related
Section titled “Related”Updates · Storage · Install · Troubleshooting