debian-ubuntu

Debian-Ubuntu: Debian and Debian-Based Distro Administration

Administer Debian, Ubuntu, Linux Mint, Pop!_OS, Devuan, and other Debian-derived systems, with partial coverage for Kali when the question is about base OS administration rather than security-distro workflow.

Focus on Debian stable and Ubuntu LTS first, then layer in derivative-specific behavior, PPA workflows, snap confinement, Ubuntu HWE, and explicit checks for derivatives that diverge on init, packaging defaults, or intended use.

Versions worth pinning (verified October 2026):

Only pin versions here when they materially affect compatibility or troubleshooting shape. For ordinary Debian and Ubuntu package work, prefer the live distro lane and package policy over a stale package-version table.

Security recheck (2026-09-10): CVE-2026-53362 is a high-priority Linux IPv6 flaw that Canonical lists as CISA KEV. Ubuntu 26.04's linux package is fixed in 7.0.0-31.31; Ubuntu 24.04's linux-hwe-7.0 is fixed in 7.0.0-31.31~24.04.1. The 24.04 linux lane remains marked vulnerable in that record. Check the exact release and kernel package; these are not universal kernel version floors.

Security recheck (2026-10-02): CVE-2026-53266 (netfilter ebtables SNAT, high, CISA KEV 2026-09-18) has the same fixed versions: linux 7.0.0-31.31 on 26.04 and linux-hwe-7.0 7.0.0-31.31~24.04.1 on 24.04, while the 24.04 linux lane is still listed as vulnerable.

When to use

• Package management with apt, apt-get, dpkg, apt-cache, pinning, or holds
• PPA management on Ubuntu, Mint, or Pop!_OS (add-apt-repository, key handling)
• Snap and Flatpak workflow, confinement issues, and alternatives
• systemd service, timer, boot, and journal troubleshooting on Debian-style systems
• GRUB, initramfs, EFI, kernel, and recovery work on Debian or Ubuntu
• Release maintenance: dist-upgrades, HWE transitions, release upgrades (do-release-upgrade)
• Desktop stack: Wayland vs X11, GNOME, KDE, Cinnamon, COSMIC, portals, PipeWire, Bluetooth
• Session startup and laptop work: GDM, SDDM, LightDM, suspend/resume, power profiles, hybrid graphics
• GPU and gaming: NVIDIA proprietary vs nouveau, AMD Mesa, Intel, Vulkan, Steam, Proton, Gamescope
• Capture and communication: OBS, WebRTC screen sharing, Discord/Teams, portals, virtual cameras
• Storage: ext4, Btrfs, LUKS, LVM, TRIM, hibernation
• Firmware and hardware enablement: fwupd, ubuntu-drivers, HWE stacks, backports
• Security: AppArmor profiles, unattended-upgrades, needrestart, debian-security updates
• Remote gaming and input: Moonlight, Sunshine, Steam Remote Play, controllers
• Base Linux ops on Debian-style systems: journalctl, dmesg, lsblk, update-alternatives

When NOT to use

• Shell syntax, quoting, or script portability - use shell-scripting
• Network architecture, DNS, VPNs, reverse proxies, or firewall design - use networking
• Docker, Podman, image builds, or container runtime - use docker
• Kubernetes cluster or manifest work - use kubernetes
• Fleet-wide Linux configuration via playbooks - use ansible
• Security review, vulnerability triage, or offensive testing - use security-audit or privilege-escalation
• RPM-family distros and tooling - use rhel-fedora. That includes RHEL, Fedora, Rocky, AlmaLinux, Oracle Linux, and Amazon Linux.
• Ubuntu Core and snap-only transactional workflows - outside this skill; do not treat them like ordinary apt-managed Ubuntu hosts
• NixOS or declarative system management - use nixos
• Kali offensive tooling, pentest workflow, or training-image specifics - use kali-linux
• OPNsense or pfSense appliance work - use opnsense-pfsense

AI Self-Check

Before returning Debian or Ubuntu commands, verify:

• Distro and release identified: Debian stable/testing/unstable, Ubuntu LTS/interim, Mint, Pop!_OS, Devuan, Kali, or another derivative, and its current support lifecycle and enabled repositories. Advice diverges quickly.
• Init system identified: do not assume systemd on Devuan or other Debian derivatives without checking PID 1, service manager, and boot tooling first.
• Release model respected: do not suggest apt upgrade when apt full-upgrade or apt dist-upgrade is required for package transitions. Do not suggest apt dist-upgrade casually on Ubuntu without context.
• Ubuntu 24.04 -> 26.04 delta accounted for: Ubuntu 24.04 LTS upgraders inherit 24.10, 25.04, 25.10, and 26.04 changes. Do not treat 26.04 as a small point refresh of 24.04.
• Repository state clean: no broken apt lists, missing GPG keys, or mixed releases without pinning.
• Boot stack identified: GRUB vs other loader, EFI vs BIOS, initramfs generator, and kernel metapackage before changing boot files.
• Fallback path exists: do not remove the only known-good kernel or break the only boot entry, especially on a remote or encrypted system.
• Third-party repo trust boundary respected: review PPA source, key, and maintenance status before adding; make snaps, vendor repos, and pin priorities explicit.
• systemd scope is correct: distinguish system units from user units and use systemctl --user only when appropriate.
• Wayland stack is coherent: compositor, portal backend, Xwayland compatibility, and user-session services line up.
• Session startup path identified: display manager, greeter, or TTY launch path known before debugging env propagation.
• Audio stack is coherent: PipeWire, pipewire-pulse, and WirePlumber are not fighting a leftover PulseAudio setup.
• Bluetooth path is complete: bluetooth.service alone is not enough if audio routing, trust, pairing, or profile selection is broken.
• GPU stack matches hardware: proprietary NVIDIA vs nouveau vs Mesa. Verify actual driver in use before debugging graphics issues.
• Gaming stack includes 32-bit userspace when needed: Steam and Proton failures often come from missing i386 graphics libraries.
• Capture stack is coherent: portal backend, PipeWire, WebRTC or Electron client path, and any virtual camera module choice line up.
• Suspend and hibernation claims are real: hibernation advice matches actual swap layout, initramfs resume hook, and Secure Boot state.
• AppArmor state is considered: on Ubuntu, AppArmor denials can silently break services, snaps, or custom binaries.
• Snap confinement is not ignored: when a snap misbehaves, check interfaces and confinement level before reinstalling.
• Ubuntu desktop session assumptions are current: on Ubuntu 26.04 Desktop, do not assume a stock Xorg session or the old Software & Updates GUI are present by default.
• HWE kernel path is understood: Ubuntu HWE stacks transition kernel metapackages. Know whether the system tracks generic or hwe.
• Diagnostic errors are not silenced: do not mask failures with 2>/dev/null on commands whose error reason matters. Use 2>&1 || true to surface errors without aborting.
• Firmware updates are not conflated with package updates: fwupd and vendor tools (e.g., system76-firmware) are separate from apt upgrade.
• Debian alternatives are checked: when a command behaves oddly, verify update-alternatives for that binary.
• Cross-cutting agent hygiene applied - see references/agent-hygiene.md

Workflow

The steps are ordered. Copy this checklist and track progress:

• Step 1: Distro lane identified
• Step 2: Current state gathered
• Step 3: Matching reference loaded
• Step 4: One layer changed; consequential changes confirmed first
• Step 5: Validated (on failure, fix and return to Step 4)

Step 1: Identify the distro lane first

Step 2: Gather current system state

cat /etc/os-release

Step 3: Load only the relevant reference

If the host is Ubuntu 24.04 LTS or the user is planning a 24.04 -> 26.04 move, load references/derivatives-and-hwe.md early. That path bundles interim-release churn, desktop-session changes, app swaps, and GUI-tool changes that do not show up if you treat 26.04 like a routine point upgrade.

Do not load every reference by default. Pick the one that matches the failure mode, then widen only if the first layer is clean.

Step 4: Change one layer at a time

• Fix package state before debugging services that may be broken by stale libraries.
• Fix service configuration before declaring systemd broken.
• Fix mountpoints and loader state before rebuilding initramfs.
• On Ubuntu, separate "vanilla Debian behavior" from "Ubuntu snap/HWE/PPA behavior."
• On Pop!_OS, separate "Ubuntu behavior" from "System76 firmware and power behavior."
• Prefer reversible steps: package holds, backup kernels, apt-mark, saved configs.
• Snapshot or back up before release upgrades, kernel changes, filesystem work, or bootloader repair.

Consequential changes (release upgrades, full-upgrade with removals, kernel removal, GRUB reinstall, PPA purge, LUKS or LVM changes): show the exact command and what it will do (simulated transaction with apt-get -s, removal list, or target device), get explicit confirmation, run it, then go to Step 5. In unattended runs, stop at the plan. Exact commands live in references/derivatives-and-hwe.md (release upgrades), references/boot-kernel-and-recovery.md (kernels, GRUB, live-media chroot), and references/storage-and-rollback.md (LUKS, LVM).

Step 5: Validate before closing

If kernel or boot files changed, first confirm every kernel above has an initrd and run sudo update-initramfs -u -k <version> for any that are missing. Then run sudo update-grub only when GRUB is the confirmed loader (command -v update-grub), and confirm the entries with grep -E "menuentry|initrd" /boot/grub/grub.cfg. If a check fails, fix the layer it points to and return to Step 4. Reboot only when the boot path is understood and at least one known-good entry remains.

Troubleshooting Pattern

Keep triage cross-layer and boring:

1. Confirm active distro, release, session type, kernel, and package lane.
2. Identify failing layer: package state, system service, user service, boot path, desktop session, graphics, or app.
3. Pull logs before changing config.
4. Change one layer at a time and retest.
5. Prefer known-good baseline over tweak stacking.

Core log sweep:

Broad pattern sweeps when you need correlation, not first-pass precision:

When a bug looks desktop-only, compare one clean baseline:

• GNOME vs KDE vs Cinnamon vs COSMIC
• browser WebRTC vs packaged client
• plain game launch vs Gamescope or MangoHud
• stock kernel vs HWE kernel

Default Decisions

• Debian stable means conservative updates. Pin when mixing repos. Use backports selectively. Avoid testing or sid packages on stable without a transition plan.
• Ubuntu LTS means predictable cadence. Ubuntu 26.04 is the current baseline, but 24.04 -> 26.04 upgrades bundle three interim releases plus the final LTS delta. Expect bigger desktop, app, and workflow changes than the version jump alone suggests.
• Ubuntu Desktop assumptions changed in 26.04. Stock Ubuntu Desktop is Wayland-only, and the old Software & Updates GUI is no longer installed by default on new installs. GUI-first troubleshooting advice from 24.04-era blog posts may be wrong on fresh 26.04 systems.
• Use systemd-native tools first. Reach for systemctl, journalctl, timedatectl, and localectl before distro wrappers.
• Treat PPAs as exceptions, not defaults. Review maintainer, signing key, freshness, and package origin before adding one. Remove dead PPAs promptly.
• Prefer distro packages before third-party repos. Use Debian backports, Ubuntu official repos, or vendor packages first; escalate to PPAs only when the distro lane is genuinely insufficient. Isolate vendor repos to the packages they own.
• Narrow before broad. Use apt-cache policy, apt list --upgradable, and targeted installs before broad reinstall attempts. For slow upgrades, identify held packages and phased updates before forcing resolver choices. Keep package index updates scoped; repeated apt update in scripts wastes time and load.
• Treat snaps as sandboxed first. Interface and confinement issues explain more snap failures than package bugs.
• GRUB and initramfs are one subsystem. Kernel metapackage, update-initramfs, update-grub, and EFI fallback all have to agree.
• Desktop failures are often session failures. On Wayland, user units, portals, and session env matter as much as the package list.
• Gaming failures are often stack mismatches. Wrong driver branch, missing i386 userspace, absent firmware, or broken Proton path is more common than "Linux gaming is bad."
• Capture failures are portal/PipeWire failures. OBS, browser WebRTC, Discord, and Teams often fail at the screencast path.
• AppArmor is invisible until it is not. On Ubuntu, check aa-status and journal denials when a service or binary mysteriously fails.
• Firmware is separate from packages. fwupd and vendor tools update hardware firmware. Do not expect apt upgrade to fix BIOS or SSD firmware.

Quick Triage Checklist

Reference Files

• references/packages-and-repos.md - apt workflow, dpkg, pinning, PPAs, snaps, flatpaks, .deb handling
• references/systemd-and-journal.md - systemd service debugging, unit overrides, user units, journal triage
• references/boot-kernel-and-recovery.md - GRUB, kernel metapackages, initramfs, EFI, recovery, and live-ISO chroot
• references/derivatives-and-hwe.md - Ubuntu HWE, release upgrades, Debian lane differences, Mint, Pop!_OS, Devuan, and Kali scope notes
• references/desktop-audio-and-bluetooth.md - X11 vs Wayland, GNOME, KDE, Cinnamon, COSMIC, portals, PipeWire, Bluetooth
• references/session-display-and-mobile.md - GDM, SDDM, LightDM, session env, suspend/resume, power profiles, hybrid graphics
• references/graphics-and-gaming.md - NVIDIA, AMD, Intel, Vulkan, Steam, Proton, Gamescope, MangoHud
• references/capture-and-sharing.md - OBS, WebRTC screen sharing, Discord/Teams, hardware encoding, virtual cameras
• references/storage-and-rollback.md - ext4, Btrfs, LUKS, LVM, TRIM, hibernation, resume
• references/security-and-updates.md - AppArmor, unattended-upgrades, debian-security, needrestart
• references/remote-gaming-input-and-tooling.md - Moonlight, Sunshine, controllers, Steam Remote Play
• references/base-linux-and-cli.md - core Linux inspection commands and Debian tools such as update-alternatives
• references/gotchas-and-special-situations.md - recurring Debian/Ubuntu failure patterns and edge cases

Output Contract

See references/output-contract.md for the full contract.

• Skill name: DEBIAN-UBUNTU
• Deliverable bucket: audits
• Mode: conditional. When invoked to analyze, review, audit, or improve existing repo content, apply the reporting size and evidence rules in references/output-contract.md and write the deliverable to docs/local/audits/debian-ubuntu/<YYYY-MM-DD>-<slug>.md. When invoked to answer a question, teach a concept, build a new artifact, or generate content, respond freely without the contract.
• Severity scale: P0 | P1 | P2 | P3 | info (see shared contract; only used in audit/review mode).

Related Skills

• shell-scripting - shell syntax, zsh or bash behavior, script portability
• networking - network services, DNS, VPNs, firewall design
• docker - container runtime and image concerns instead of host distro administration
• kubernetes - cluster and manifest work that sits above host OS administration
• ansible - codifying Linux changes across many machines
• security-audit - hardening and security review rather than normal package/service administration
• rhel-fedora - RPM-family distro administration rather than Debian-family behavior
• nixos - NixOS and declarative Nix system management rather than apt-based administration
• kali-linux - Kali-specific branch, image, and offensive-workflow concerns
• opnsense-pfsense - OPNsense and pfSense appliance work rather than Linux host administration
• arch-linux - Arch Linux and CachyOS administration (the upstream inspiration for this skill)
• update-docs - after substantial system administration changes that introduce new operational gotchas

Rules

1. Confirm consequential changes before running them. Show the exact command and its plan, wait for an explicit yes, then verify. Unattended runs stop at the plan.
2. Identify the installed Ubuntu kernel lane. HWE can be a Desktop install default or an explicit choice. Check the release-qualified metapackage and validate driver compatibility before changing lanes.
3. Never skip a release. Debian and Ubuntu upgrades go one supported step at a time (Ubuntu LTS-to-LTS is one supported step); finish the current release with full-upgrade first.