How to Back Up and Restore a Haiku System

A useful Haiku backup must preserve more than file contents. BFS attributes can hold MIME, mail, media, icon, and application metadata; packagefs separates immutable package content from writable settings/cache/var/non-packaged data. Design the restore first, then choose file-level and image-level backups that can actually reproduce it.

Inventory data and package state

Back up personal documents and the writable home hierarchy, including relevant ~/config/settings, mail, application data, scripts, keys, and user-installed non-packaged files. Review secrets before copying them to unencrypted media.

Record installed system and home packages and repositories:

pkgman search -a -i -D
pkgman list-repos

Save Haiku revision/architecture and custom package files/recipes not available from repositories. The virtual /boot/system package content can normally be reconstructed, but its package inventory, non-packaged additions, settings, cache/var data, and repository snapshot may not be.

Package rollback states are recovery aids on the same disk, not backups. A failed drive loses current and historical states together.

Choose an attribute-preserving destination

A BFS destination naturally supports Haiku attributes and links. Another file system, network protocol, or archive may preserve bytes while dropping attributes. Do not assume cp -a means identical semantics on every host/destination.

Use a Haiku-aware copy/archive tool whose documentation explicitly covers attributes, symlinks, permissions, sparse files, and hard links. On Haiku, compare source and destination attributes with listattr/catattr for representative files. Test files with custom attributes, symlinks, executable bits, Unicode names, and large data.

If the chosen offsite format cannot preserve BFS metadata, create a BFS disk image/container or a verified attribute-aware archive inside it. State the limitation rather than silently accepting metadata loss.

Make a consistent file-level backup

Close applications that continuously write databases, mail, browser profiles, or settings. Pause services where their documented procedure allows it. Copy personal data first and mutable configuration second. A live copy can capture different files from different moments; applications needing transaction consistency may require export or shutdown.

Keep backup logs and fail on unreadable files instead of reporting success. Check free space before starting and avoid placing the only backup on another partition of the same physical disk.

After copying, compare file counts/sizes as a coarse check, then hashes for important ordinary files and attributes for Haiku-specific metadata. Open several restored documents from the backup without using originals.

Use versioned destinations rather than mirroring deletions immediately. A synchronization that propagates accidental deletion or ransomware is not historical backup.

Create a block image only when appropriate

A raw image preserves the complete partition/file-system layout and attributes, but it copies free space, requires a target at least as large, and can capture an inconsistent mounted source. Prefer booting from separate trusted media and unmounting the source volume before imaging.

Identify source and destination in DriveSetup by model, capacity, and partition—not changing device numbers alone. Reverse if/of in dd and the destination is overwritten. Use read-only imaging/recovery tooling appropriate to the hardware, store the image on another device, and compute a checksum afterward.

Do not image a failing disk repeatedly. Make one controlled clone with suitable recovery tooling and work from the copy. Encryption and physical protection matter because the image contains deleted-space remnants and every secret.

Restore to a clean test target

Test restore before disaster. For file-level recovery, install a compatible Haiku system, update it to the intended repository state, reinstall packages from the saved inventory, then restore user documents and settings selectively.

Restore data while applications are closed. Do not overwrite every current setting blindly across incompatible application versions. Start with documents, then application data, then individual settings; launch and verify after each group. Restore non-packaged software only when its architecture/dependencies are still valid.

For a full image, restore only to an identified empty/test device of adequate size while booted elsewhere. The operation replaces the target partition table/data. Afterward, verify BFS, mount it, and repair bootability only through Haiku’s documented Installer/boot tools if needed.

Verify the recovered system

Check attributes on representative mail/media/custom files, open documents, run applications, verify package/repository inventory, and test keys/credentials without exposing them. Confirm BFS queries find restored attribute values and that symlinks/permissions behave correctly.

Perform a cold boot, update check, network test, and backup-again cycle. Record restore duration and missing manual steps. A backup is accepted only after a separate target can recover useful data.

Keep multiple generations, one offline/offsite copy, checksums, and a written recovery procedure. Re-test after major Haiku/package changes. packagefs simplifies reconstructing immutable system content, but it does not recreate your data, settings, package sources, or verification evidence.

Related:

Sources: