Debian Knowledge Patch

Debian knowledge patch

Use this skill when planning Debian upgrades, reconciling package or service changes, or checking platform behavior that differs from older installations. Resolve upgrade hazards before recommending an in-place upgrade, especially for remote or stateful systems.

Navigate the references

Read every reference relevant to the host before changing an upgrade plan, package set, boot configuration, network configuration, or stateful service.

Triage breaking upgrade risks first

Before approving an in-place upgrade, determine whether the host is:

• reached only through SSH;
• using a separate /boot;
• mounting encrypted filesystems, especially plain-mode dm-crypt;
• running RabbitMQ, MariaDB, Dovecot, or Bacula;
• dependent on stable network-interface names or /etc/sysctl.conf;
• using a retired architecture or third-party armel or armhf binaries;
• relying on custom WirePlumber, strongSwan, OpenLDAP, Samba, or libvirt setup;
• carrying packages or commands that no longer exist.

Treat every matching condition as a required migration, verification, or rollback-planning step. Do not defer it to post-upgrade cleanup.

Protect remote access and bootability

Prepare SSH before a remote upgrade

• Install openssh-server version 1:9.2p1-2+deb12u7 or later from stable-updates before starting an SSH-supervised upgrade.
• Do not expect a new SSH session to read ~/.pam_environment; relocate needed variables to shell startup files or another appropriate mechanism.
• Replace DSA keys. OpenSSH 9.8p1 and later cannot re-enable them.
• Reserve the ssh1 command from openssh-client-ssh1 for devices that offer no other key type.

Check /boot

• Require a separate /boot to be at least 768 MB with about 300 MB free.
• Pay particular attention to systems originally installed with Debian 10 or earlier.
• Enlarge an LVM-backed /boot with lvextend when necessary.

Read security-networking.md and upgrade-foundations.md before finalizing a remote-upgrade procedure.

Preserve encrypted storage

• Verify that systemd-cryptsetup is installed before rebooting an upgraded encrypted system; automatic discovery and mounting moved into that package.
• Never let new plain-mode dm-crypt defaults silently replace the parameters that created existing data.
• For a device made with the previous defaults, pin cipher=aes-cbc-essiv:sha256,size=256,hash=ripemd160 in /etc/crypttab.
• Recognize the new plain-mode defaults as cipher=aes-xts-plain64 and hash=sha256.

Plain mode stores no parameters. A mismatch can make valid old data appear random, so verify configuration before attempting repair or reinitialization.

Stage stateful-service migrations

RabbitMQ

• Convert classic HA queues to quorum queues before upgrading.
• Do not plan a direct broker upgrade from the preceding stable release.
• Preserve or recreate required state before applying Debian's reset procedure, which removes /var/lib/rabbitmq/mnesia after the OS upgrade and restarts the service.

MariaDB

• Stop MariaDB cleanly before its major upgrade and confirm Shutdown complete in the logs.
• If the stop was unclean, recover with 10.11, then stop cleanly again before moving to 11.8. MariaDB 11.8 cannot crash-recover a crashed 10.11 data directory.

Dovecot and Bacula

• Port and test the incompatible Dovecot 2.4 configuration before the OS upgrade; the replicator feature is gone.
• Budget hours or days and roughly twice the current database space for a Bacula schema migration, plus dump space under /var/cache/dbconfig-common/backups.
• Prevent Bacula from exhausting disk space because that can corrupt its database.

Read services-data.md for the complete service-specific requirements.

Reconcile system and network behavior

• Move local sysctl settings from /etc/sysctl.conf to /etc/sysctl.d/*.conf; systemd-sysctl no longer reads the former file.
• Review /usr/lib/sysctl.d/50-default.conf from linux-sysctl-defaults.
• Account for iputils-ping using ICMP datagram sockets instead of CAP_NET_RAW. Unprivileged ping now depends on net.ipv4.ping_group_range.
• After apt full-upgrade and before reboot, test interface naming with:

udevadm test-builtin net_setup_link /sys/class/net/<interface>

• Pin an old interface name with a systemd.link file if i40e behavior or newly honored ACPI _SUN data would rename it.
• Rework custom strongSwan deployment toward charon-systemd, swanctl, and /etc/swanctl/conf.d.
• Review OpenLDAP TLS settings because libldap2 and slapd now use OpenSSL and may load the system trust store when no CA certificates are configured.

Reconcile package and configuration splits

• Review libvirt drivers and storage backends after upgrade; each is now a separate binary package.
• Install samba-ad-dc for Active Directory domain-controller support.
• Install samba-vfs-ceph or samba-vfs-glusterfs for those backends; most other VFS modules are included in samba.
• Keep tzdata-legacy where a database or service still uses names such as US/*.
• Port custom WirePlumber setup to its new configuration system; defaults need no action.

Consult packages-toolchains-desktops.md before substituting a removed package or command. Some removals have targeted replacements, while others do not.

Account for architecture and ABI boundaries

• Do not plan an upgrade of an existing i386 installation. Use i386 only for legacy roles such as chroots and multiarch on amd64.
• Treat mipsel and mips64el as removed.
• Treat armel as installer-less and limited to Raspberry Pi 1, Zero, and Zero W with Debian kernels, while allowing supported existing systems to upgrade.
• Rebuild and audit third-party software for armel and armhf: the 64-bit time_t transition changes many library ABIs without changing sonames and can cause silent data loss.
• Keep the legacy time ABI expectation only for i386.
• Match ppc64el guest page-size needs to the host kernel and QEMU machine setting.

Read release-platform.md for exact platform and virtual-machine constraints.

Use new platform capabilities deliberately

• Expect systemd to mount /tmp as tmpfs by default.
• Distinguish fresh installations, which enable cleanup of /tmp and /var/tmp, from upgraded systems, which must opt in.
• Use firmware HTTP Boot to start installer or live media directly from a full ISO URL on supported UEFI and U-Boot systems.
• Expect automatic Pointer Authentication and Branch Target Identification hardening on supported arm64 hardware.
• Expect Hunspell language packages to provide compiled .bdic dictionaries for supporting Qt WebEngine browsers.
• Allow Plasma 6 applications to coexist with retained Qt 5 and KDE Frameworks 5 compatibility libraries, while treating Frameworks 5 as deprecated.

Prepare migrations that become urgent next

• Move sudo-ldap rules to libsss-sudo so privilege policy survives its removal.
• Install the transitional OpenSSH GSS-API client or server package now when relying on GSSAPI* options.
• Replace fcitx 4 with fcitx5 and move Debian LXD deployments to Incus with tools from incus-extra.
• Replace sbuild-debian-developer-setup with sbuild --chroot-mode=unshare.
• Remove dependency on libnss-docker, whose required Docker API disappears after Engine 26.
• Select DHCP software by network stack: NetworkManager and systemd-networkd need no ISC client, ifupdown can use dhcpcd-base, and servers should move to Kea.

Use upgrade-foundations.md as the final migration checklist rather than assuming a successful reboot completes the work.