debian-upgrade.md

Upgrade Debian 12 (Bookworm) to Debian 13 (Trixie)

1. Preparation & Safety First

• Backup crucial data and configs — especially /etc, /var/lib/dpkg, /var/lib/apt/extended_states, and results from:

  dpkg --get-selections '*'

  Also consider backing up user home dotfiles (~/.config, etc.).

• Update Debian 12 fully:

  sudo apt update
  sudo apt upgrade
  sudo apt full-upgrade
  sudo apt autoremove --purge
  sudo apt autoclean

• Ensure enough free disk space — at least 5 GB free on /.

---

2. Update APT Repositories to Trixie

• Backup your sources config:

  sudo cp /etc/apt/sources.list /etc/apt/sources.list.bookworm-backup
  sudo cp -r /etc/apt/sources.list.d /etc/apt/sources.list.d.bookworm-backup

• Replace all bookworm mentions with trixie:

  sudo sed -i 's/bookworm/trixie/g' /etc/apt/sources.list
  sudo find /etc/apt/sources.list.d -name "*.list" \
       -exec sudo sed -i 's/bookworm/trixie/g' {} \;

• If you use third‑party repos (e.g. NodeSource, Docker), ensure they support Trixie or temporarily disable them.

---

3. Upgrade to Debian 13

• Refresh package lists:

  sudo apt update

• Start with a minimal upgrade:

  sudo apt upgrade --without-new-pkgs

• Then do a full upgrade:

  sudo apt full-upgrade

---

Handling Secure Boot During Upgrade

If your system has UEFI Secure Boot enabled, Debian may prompt you to disable it during the upgrade. This usually happens when installing or updating third-party drivers or DKMS modules (e.g., NVIDIA, VirtualBox, or firmware packages).

You have two choices:

1. Disable Secure Boot – recommended for home or Proxmox servers. This allows all modules to install and load without extra steps.
2. Keep Secure Boot enabled – you must verify that all modules and services load correctly after the upgrade.

---

1. Inspect kernel messages for blocked modules

Check for Secure Boot restrictions in the kernel log:

dmesg | grep -Ei "secure|lockdown|denied|nvidia|firmware|rejected"

• Look for messages like:

Lockdown: Loading of unsigned module is restricted
nvidia: module verification failed: signature and/or required key missing
firmware: failed to load iwlwifi-8265-36.ucode (-2)

• These indicate which modules were blocked.

---

2. Check system journal for module or driver issues

journalctl -k -b

• -k → kernel messages only
• -b → messages from the current boot
• Search inside less using / for keywords: Lockdown, denied, verification failed, firmware, rejected

---

3. Verify Secure Boot status

Confirm whether Secure Boot is still active:

mokutil --sb-state

---

4. Check for failed services

Blocked firmware or modules may prevent services from starting:

systemctl --failed

• This helps identify any dependent services that failed because drivers or modules were not loaded.

---

4. Finalization

• Clean up:

  sudo apt autoremove --purge
  sudo apt clean

• Reboot:

  sudo reboot

• Verify:

  cat /etc/os-release

---

5. Troubleshooting & Extras

• Use tmux or screen so the session stays alive even if your SSH drops. Refer
• Check /var/log/apt/term.log for errors.
• Read the official release notes before upgrading.
• For automation, use an Ansible playbook or shell script.

---

TL;DR Summary

Step	Action
1	Update Debian 12, backup configs, ensure free space
2	Change apt sources from bookworm → trixie
3	apt update → upgrade --without-new-pkgs → full-upgrade
4	Clean, reboot, verify
5	Consult logs and release notes if issues arise