Debian Preseeding: Why Unknown Keys Fail Silently and How to Catch Them

You built a Debian automation pipeline around a preseed.cfg file. It worked on the release you tested. Then a point update ships, you rebuild your image, and the installed systems come up with the wrong hostname, the wrong APT mirror, or an unexpected partition layout. The installer never threw an error. It just quietly ignored the keys it no longer recognized.

The takeaway: a Debian preseed file is not a declarative config that fails loudly. It is a release-specific answer script fed into the installer's debconf database. The only reliable way to know it worked is to audit the installed system against your expectations.

Why preseeding fails silently

During installation, the Debian installer maps d-i keys from your preseed file into debconf templates. If a key does not exist in that release's template set—because it was renamed, relocated, or removed—the value is discarded. There is no validation pass that rejects unknown keys. From the installer's perspective, an unrecognized key is indistinguishable from a key that was never set.

This matters most across point releases. Upstream may relocate a key from one package to another, or change a variable name to match a new default. Your file still parses. The installer still runs. But the answer you intended to supply never reaches the component that needed it.

A worked example: audit the result, not the input

Assume you want to set a hostname, a DNS server, and a custom APT source during install. A minimal preseed.cfg might look like this:

d-i netcfg/hostname string web-prod-01
d-i netcfg/get_nameservers string 9.9.9.9
d-i partman-auto/method string regular
d-i partman-auto/disk string /dev/sda
d-i apt-setup/services-select multiselect security, updates

Rather than trusting that every key was accepted, run a short audit on the installed system. Execute the following as root (or via sudo) on the target machine after first boot:

#!/bin/bash
# Run as root on the installed Debian system
expected_host="web-prod-01"
actual_host=$(hostname)

if [ "$actual_host" != "$expected_host" ]; then
  echo "FAIL: hostname is '$actual_host', expected '$expected_host'"
else
  echo "PASS: hostname matches"
fi

if grep -q "9.9.9.9" /etc/resolv.conf; then
  echo "PASS: nameserver 9.9.9.9 present"
else
  echo "FAIL: nameserver 9.9.9.9 missing from /etc/resolv.conf"
fi

# APT source format varies by release and configuration.
# Check both traditional and deb822 paths.
if grep -rq "deb.debian.org" /etc/apt/sources.list /etc/apt/sources.list.d/ 2>/dev/null; then
  echo "PASS: Debian repository reference found"
else
  echo "FAIL: no Debian repository reference found under /etc/apt"
fi

Expected checks: the script prints PASS or FAIL for each item. A FAIL on hostname or nameserver usually means the corresponding preseed key was ignored or overwritten by DHCP. A FAIL on the APT source may mean the key moved, or the installer wrote the source to a different file format.

Risk: this script reads system files but does not modify state. It is safe to run repeatedly. If you embed it in a first-boot unit, keep it read-only and log to a separate file.

Trade-offs and limitations

An audit catches symptoms, not root causes. If a key was renamed, your script tells you the hostname is wrong, but not which preseed line failed. You still need to consult the version-specific installer documentation for the target release to find the correct key name.

Audits are also release-specific. A check that greps /etc/apt/sources.list may need to change if a future release defaults to deb822 .sources files. And some preseeded values—such as partition UUIDs or device mapper names—are dynamic by design, so they resist simple string comparison.

Finally, preseeding does not solve secret management. A preseed.cfg is typically plain text. Storing root passwords, API tokens, or disk encryption passphrases directly in the file exposes them to anyone who can read the file or the boot media. Pre-hashed passwords reduce exposure compared to plaintext, but the file itself remains sensitive.

What to do next

• Pin your preseed file to a specific Debian release codename in your build pipeline, and review it when you upgrade.
• Run the audit script as a provisioning gate: if it exits non-zero, do not promote the image.
• Keep secrets out of preseed.cfg. Use a separate mechanism to inject them after the base system is installed.

Preseeding is powerful because it removes interactive prompts. It is fragile because it removes feedback. Closing that gap with a concrete post-install check turns a silent failure into a visible one.