Backup and restore

tools/backup.py makes a full backup of a running server into one dated folder. The restore procedures are in tools/RESTORE.md.

Making a backup

The OAR and IAR steps run OpenSim's save oar / save iar, and the terrain step runs terrain save, all through WorldBridge's console op, which runs only when the server was started with WORLDBRIDGE_ALLOW_CONSOLE=true (then python tools/make_config.py <bin> --force and a restart). When WorldBridge refuses the op (403: the console is off, or the token is below gaia), the script prints a warning naming WORLDBRIDGE_ALLOW_CONSOLE, skips everything the console writes (region.oar, the IARs, terrain.r32), still copies the databases and the state files, and records the skipped files in MANIFEST.json ("partial": true, "skipped": {...}). The databases and state alone restore the whole server (RESTORE.md part A); the OAR and IARs are what moves a region or an inventory into another server (parts B and C). Any other WorldBridge error (not running, a wrong token) stops the backup.

python tools/backup.py [out_parent] [--no-oar] [--no-iar] [--no-db]

out_parent defaults to PARACOSM_BACKUP_DIR, else <source root>/backups (git-ignored). The folder is paracosm-backup-<yyyymmdd-hhmmss>/:

file	what	how
`region.oar`	the region: terrain, objects, their scripts, sounds and textures, parcels	`save oar` (console op)
`<First>_<Last>.iar`	the estate owner's and the resident's inventories (one file if they are the same account)	`save iar` (console op), with the passwords from `.env`
`db/*.db`	every SQLite store in `bin/`	SQLite's online-backup API, consistent while OpenSim runs
`state/`	WorldBridge's `worldbridge-*.json` state files, `WorldBridge.token`, `OpenSim.ini`, `Regions_Regions.ini`, `config-include_StandaloneCommon.ini`	copied
`terrain.r32`	the live heightmap	`terrain save` (console op)
`MANIFEST.json`	the size and SHA-256 of every file; `partial` and `skipped` (what the console could not write, and why)	written last

A backup holds secrets: state/OpenSim.ini has the estate owner's and the console's passwords, and state/WorldBridge.token is the gaia token. Keep backups as private as .env.

The reference island's full backup was 1.25 GB (the OAR 164 MB, 2,644 objects and 4,082 assets).

Restoring

tools/RESTORE.md covers:

A. The whole server, exactly as it was (the same machine or a new one): stop OpenSim, copy db/*.db and state/worldbridge-*.json back into bin/, keep or regenerate the config, start.
B. The region into another server: load oar <path> (replaces the region's objects and terrain) or load oar --merge <path> (adds to what is there), at the OpenSim console or through WorldBridge's console op.
C. An inventory: load iar <First> <Last> / <password> <path>.

It also gives a one-line check of a backup against its manifest. The procedure was verified on 2026-09-27 by loading the island's backup into a server built from source by build/build_server.py: all 2,644 objects arrived and the terrain matched to 0.000 m.