# Check a bundle before transfer

Use doctor to find common offline installation problems and policy files to enforce build rules.

Source: https://debark.dev/docs/guides/policy-and-doctor

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

```bash
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:

```bash
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`:

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

Then use it during the build:

```bash
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.

```bash
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.

<NextSteps
  items={[
    {
      title: 'Vendor packages',
      href: '/docs/guides/vendor-debs',
      description: 'Supply expected checksums for URL inputs.',
    },
    {
      title: 'Run from a script',
      href: '/docs/guides/automation',
      description: 'Capture findings and handle policy failures.',
    },
  ]}
/>