Check a bundle before transfer

Check a bundle while you are still on the online computer, where missing downloads and package choices are easier to fix.

debark verify ./bundle --key operator.pub
debark doctor ./bundle

Verification checks that the bundle is intact and signed by a trusted key. Doctor checks for common problems with its packages.

What doctor checks

Check name	What to look into
network-postinst	A setup script may try to access the network
snap-shim	The .deb may install a Snap app that the bundle does not contain
dkms-headers	A kernel module may need headers missing from the bundle
redistribution	A package comes from a restricted archive component
unverified-url	A vendor input lacks publisher verification
held-package	The target has a package on hold
essential-change	A change affects a package marked essential

Findings use note or warn. Read the package name, message, and evidence attached to a warning before transferring the bundle.

These checks look for known patterns. A clean report does not guarantee that every package will work offline. Warnings do not make the doctor command fail; it returns exit 0 when the scan completes, even with findings. Read or parse the findings themselves.

You can also check a snapshot:

debark doctor --snapshot target.tar.zst

Supply a bundle or a snapshot, not both. --no-scan-scripts skips reading package setup scripts; use it only when you do not need that part of the check.

Add build rules with a policy file

A policy file can restrict package names, archive components, and other recorded attributes. Save this example as policy.yaml:

schema_version: debark.policy/v1
default_severity: deny
require_signed_publisher: true
deny_packages:
  - '*-dbgsym'

Then use it during the build:

debark build --snapshot target.tar.zst --out ./bundle \
  --sign operator.key --policy policy.yaml jq

The example uses default_severity: deny, so a matching rule stops the build with exit 6. Use warn to record findings without blocking the build, or info for informational findings. If you omit the severity, it defaults to warn.

A rule applies to the resolved plan, so it can also match dependencies you did not request by name.

Policy settings

YAML and JSON are accepted. Unknown settings cause an error.

Setting	Default	Purpose
schema_version	Required	Use debark.policy/v1
allow_components	Unset	Allow only the listed apt components
deny_components	Unset	Reject the listed apt components
allow_packages	Unset	Allow only package names matching these glob patterns
deny_packages	Unset	Reject package names matching these glob patterns
require_signed_publisher	false	Reject url-unverified inputs; supplied checksums are accepted
allow_url_inputs	true	Allow download URLs in the request
approved_keys	Unset	Restrict archive signing-key fingerprints
deny_flags	Unset	Reject packages with the listed flags in the plan
default_severity	warn	Use deny to block, warn to warn, or info to report information

Globs match package names, for example linux-image-*. A policy only evaluates the information available in the plan. It does not turn every possible doctor warning into a build-time check.

Requiring approved archive keys

--approved-keys takes a plain-text file of archive public-key fingerprints, one per line. Blank lines and comments starting with # are allowed. Obtain the fingerprints from sources you trust and include the archives this target needs.

debark build --snapshot target.tar.zst --out ./bundle \
  --sign operator.key --approved-keys approved-keys.txt jq

This controls archive keys used for downloads. It is separate from the operator key that signs the finished bundle.

Capture the snapshot with keyrings included. A snapshot made with --no-keyrings cannot satisfy this check.

If a rule blocks the build

Read which package, component, input, or key matched the rule. Correct the package request, supply the required checksum, or revise the policy if its requirements need to change.

For archive-key failures, inspect the snapshot’s key information and compare it with your approved list. Take a fresh snapshot if required keys were omitted or the target’s sources changed.