Image files

An image file is an on-disk snapshot of a volume. Because by default volume contents are volatile, an image is a way to make them persist across dismount and shutdown.

Image file features

• Crash-safe. Writes use an A/B generation scheme; an interrupted save never corrupts the image, and the previous generation always remains loadable.
• Checksummed. A per-region hash detects on-disk corruption at load.
• Sparse. Only used regions occupy the disk; freed regions are punched.
• Compressed verbatim. Compressed regions are stored in compressed form, so images stay as small as possible.

Constraints

The image must reside on a local disk. It cannot be placed on a RAM FS volume (recursive) or on a network path. Images are also platform-specific: an image saved on Windows cannot be loaded on macOS or vice versa.

Load and save

Creating a volume with an existing image path loads its contents at mount. Saving a volume writes its contents to the image and binds the volume to it. Once bound, subsequent saves are differential: only regions changed since the last save are written, at 2 MB granularity. This keeps saving operations fast and minimises SSD writes.

Save triggers

• Manual. Save on demand.
• Periodic. Every N minutes, set in a volume's Advanced options.
• Shutdown and dismount. Optional auto-save when the system shuts down and when the volume is dismounted.

Auto-mount

A configured image-backed volume can mount at boot with its contents loaded, independently of the application. Combined with auto-save, a persistent volume reloads at boot and saves itself as you work.

Typical setup

For a persistent work volume: create it bound to an image on a local disk, enable auto-save at shutdown, and enable mount at startup. It will load at boot, run at memory speed, and persist automatically.