Snapshots

A snapshot is a compressed file describing a machine’s apt and dpkg state. Debark uses it to work out which packages that machine needs.

You can also build with a baseline OS without capturing a snapshot. Choose that option for a stock installation; use a captured snapshot for the actual state of a particular machine.

Take the snapshot on the offline machine. Creating it needs no internet or root access and doesn’t change installed packages.

Create and inspect a snapshot

debark snapshot create --out target.tar.zst
debark snapshot inspect target.tar.zst

Without --out, the filename is snapshot.tar.zst. Inspection shows the target release, architecture, installed package count, and how the snapshot was created. Use --json for structured output.

Copy the snapshot to the online computer and pass it to debark build --snapshot.

What a snapshot holds

Information	Why the build needs it
Installed packages and versions	Avoid downloading dependencies already present on the target
apt sources	Download from the repositories configured for the target
Version preferences and holds	Respect the target’s package selection rules
apt settings	Preserve choices such as whether to install recommended packages
Archive public keys	Check packages against the target’s configured archive keys
Release, architecture, and apt/dpkg versions	Choose compatible packages and a build backend
Machine ID	Apply Ubuntu’s phased-update policy for the target

It does not contain the installed .deb files, application data, or a backup of the machine. Software managed outside apt and dpkg isn’t described.

Redacting and labelling

Add labels to help identify snapshots:

debark snapshot create --out lab-server.tar.zst \
  --label machine=lab-server --label purpose=monthly-update

Use --redact when you need to remove the machine ID, proxy settings, and labels:

debark snapshot create --out target.tar.zst --redact

A redacted snapshot still contains package and repository information. Review it before sharing it outside your usual working environment. Redaction also affects phased updates, described below.

Captured or synthesized

Captured snapshots come from snapshot create on a real machine. Use this option whenever you can access the target.

Synthesized snapshots describe an assumed stock Debian or Ubuntu installation. build --base creates this description as part of a build; you do not need to supply a snapshot file. snapshot from-base saves the same kind of description as a reusable file.

The origin.kind field records captured or synthesized; snapshot inspect shows it.

A base can assume packages are installed when the actual machine doesn’t have them, leaving dependencies out of the bundle. Builds from bases have less testing than captured snapshots. See building without a snapshot.

Phased updates

Ubuntu may make an update available to only some machines during a gradual rollout. Debark uses the target’s captured machine ID so apt can apply that policy to the target.

If the machine ID is absent, including after --redact, Debark excludes phased updates from the automatic upgrade pass. Explicit package requests are handled separately. This matters when using --upgrades.

Skipping the keyrings

--no-keyrings omits archive public keys and removes their Signed-By references from the captured sources. Leave this flag off for normal use.

A snapshot without the key material cannot satisfy an --approved-keys check. These archive keys are also separate from the operator key used to sign and verify the bundle.

When to take a new snapshot

Capture again after installing or removing packages, changing apt sources or settings, or changing the target’s architecture configuration. A build checks dependencies against the snapshot, so an old snapshot may no longer describe what the machine needs.