Repositories, apt pinning and kernel pinning · Proxmox VE

Two questions decide what runs on a Proxmox node: which repository it draws from, and what you have pinned so that it does not move. Both are usually configured once during installation and never revisited, and both have consequences that surface months later.

The kernel half of this has become concrete: PVE 9.2 moved the default kernel from the 6.x series to 7.0. A fleet that upgrades into that transition and finds one hardware class unhappy needs a way to stay on the kernel that worked, without also standing still on everything else.

The three repositories

They carry the same code at different points in its life.

Repository	Component	Timing	Requires
Enterprise	`pve-enterprise`	Latest, after the widest testing	A subscription
No-subscription	`pve-no-subscription`	Earlier, less soak	Nothing
Test	`pve-test`	First. Not for production	Nothing

The documentation is direct about which is recommended: the enterprise repository “contains the most stable packages and is suitable for production use.”

The distinction people get wrong is thinking no-subscription is a lesser edition. It is not — it is the same packages, published sooner, with less time between release and your node. That is a genuine trade rather than a quality difference, and it points different ways in different environments: for production you want the soak; during a critical advisory you may want the fix.

Writing the sources files for PVE 9

PVE 9 runs on Debian 13 Trixie and uses the deb822 .sources format. Four files, and all four suites must say trixie.

# /etc/apt/sources.list.d/pve-enterprise.sources
Types: deb
URIs: https://enterprise.proxmox.com/debian/pve
Suites: trixie
Components: pve-enterprise
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg

# /etc/apt/sources.list.d/proxmox.sources   (no-subscription alternative)
Types: deb
URIs: http://download.proxmox.com/debian/pve
Suites: trixie
Components: pve-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg

# /etc/apt/sources.list.d/debian.sources
Types: deb deb-src
URIs: http://deb.debian.org/debian/
Suites: trixie trixie-updates
Components: main non-free-firmware
Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg

Types: deb deb-src
URIs: http://security.debian.org/debian-security/
Suites: trixie-security
Components: main non-free-firmware
Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg

Two details are load-bearing.

trixie-security is where base-OS security fixes come from, and it is not subject to the enterprise-versus-no-subscription timing question at all. When a CVE is in openssl or the kernel rather than in a pve-* package, this is the file that matters.

non-free-firmware is required for CPU microcode. intel-microcode and amd64-microcode live there. A node whose debian.sources lists only main cannot install microcode updates, which is a silent gap covered in the firmware lesson.

Read-only / Safewhat is this node actually configured to pull from?— Read-only. Lists the configured sources and shows which repository each candidate version comes from. Run this before assuming a node is on the repository you think.

ls -1 /etc/apt/sources.list.d/
grep -rE '^(Types|URIs|Suites|Components):' /etc/apt/sources.list.d/

apt-cache policy
apt-cache policy pve-manager

apt modernize-sources converts legacy sources.list entries to the deb822 format and is the right cleanup after an 8-to-9 upgrade.

Holding a package that must not move

apt-mark hold prevents a package from being upgraded or removed.

Configuration changehold, list, release— A hold is stored in the dpkg selections database and survives reboots and upgrades. The listing command is the one that matters most, because a hold has no other visible symptom.

apt-mark hold pve-qemu-kvm

apt-mark showhold

apt-mark unhold pve-qemu-kvm

Holds are the right tool for a narrow, temporary situation: a package whose newer version is known to break something in your environment, or a component you need to keep still while an in-flight upgrade completes.

For finer control than “never upgrade this”, apt_preferences pins by version, origin or release. Its most common legitimate use on a Proxmox node is preferring a specific package from one repository while taking everything else from another:

# /etc/apt/preferences.d/pve-no-subscription-pin
Package: *
Pin: release n=trixie, c=pve-no-subscription
Pin-Priority: 100

A priority below 500 means “available, but not preferred”, so packages come from that repository only when explicitly requested with apt install package=version. That is a defensible way to keep a faster repository configured for emergencies without drawing everything from it.

Pinning is easy to get subtly wrong and hard to notice — apt-cache policy is the verification, and it should be run after every change to preferences.d.

Downgrading

Service impact possiblego back to a specific version— Installs an older version explicitly. Only works while that version is still in a configured repository or in the local apt cache, and downgrades can fail where a package's dependencies have also moved.

apt-cache policy pve-qemu-kvm
apt list -a pve-qemu-kvm

apt install pve-qemu-kvm=9.2.0-1
apt-mark hold pve-qemu-kvm

The hold immediately afterwards is not optional. Without it the next apt upgrade puts the package straight back, and the incident recurs at the worst possible moment — during a routine patch window, when nobody is watching for it.

/var/cache/apt/archives is frequently the only copy of the version you are rolling back to, because Proxmox repositories carry a limited set of older versions. That is the argument against apt clean as a reflex during a change window; apt autoclean, which removes only packages no longer downloadable, is the safer habit.

Kernel pinning

The kernel is not an ordinary package. It is selected by the bootloader, Proxmox keeps several installed at once, and the tool that decides which one boots is proxmox-boot-tool rather than apt.

apt-mark hold on a kernel metapackage stops new kernels installing. proxmox-boot-tool kernel pin decides which installed kernel boots. The second is almost always the one you want, because it keeps new kernels arriving and reviewable while the node continues to run the one you trust.

Read-only / Safewhat is available, and what is running?— Read-only. The list is what proxmox-boot-tool will copy to the ESPs; uname -r is what actually booted. Disagreement after a reboot means the node did not boot what you expected.

proxmox-boot-tool kernel list
uname -r
proxmox-boot-tool status

Configuration changepin a known-good kernel after a regression— Sets the default boot entry to a specific version and refreshes every synced ESP. Takes effect at the next reboot and persists across package upgrades until unpinned.

proxmox-boot-tool kernel pin 6.17.2-4-pve

proxmox-boot-tool kernel list

Configuration changetest a candidate for exactly one boot— Applies the selection to the next boot only. If the node does not come back, a power cycle returns it to the current default with no state left behind.

proxmox-boot-tool kernel pin 7.0.2-6-pve --next-boot
reboot

Use --next-boot to test a kernel and a plain pin to stay on one. A one-shot boot used as a rollback reverts silently at the next reboot, weeks later, during something unrelated — which is the worst time to rediscover the regression.

Configuration changerelease the pin— Returns to booting the newest available kernel. Do this deliberately once the regression is resolved, and verify the list afterwards.

proxmox-boot-tool kernel unpin
proxmox-boot-tool kernel list

Unattended upgrades on a hypervisor

Debian’s unattended-upgrades can apply security updates automatically. On a general-purpose server that is straightforwardly good. On a hypervisor it needs a policy, because the blast radius of an automatic change is every guest on the node.

A defensible middle position for most estates:

Enable automatic download, disable automatic install. Packages are staged locally so a patch window is fast and does not depend on the network, and nothing changes without a human.

If you do enable automatic install, restrict it to the security origins and exclude the packages whose upgrade restarts something that matters — pve-manager, qemu-server, pve-qemu-kvm, pve-cluster and the kernel metapackages.

Never enable automatic reboot. Unattended-Upgrade::Automatic-Reboot on a hypervisor takes every guest down at whatever hour the timer fires, with no HA drain, no ordering and no notice.

# /etc/apt/apt.conf.d/52unattended-upgrades-proxmox
Unattended-Upgrade::Package-Blacklist {
    "pve-manager";
    "pve-qemu-kvm";
    "qemu-server";
    "pve-container";
    "pve-cluster";
    "proxmox-kernel-.*";
    "proxmox-default-kernel";
};
Unattended-Upgrade::Automatic-Reboot "false";

Read-only / Safewhat would it do?— Read-only. The dry run reports which packages the current configuration would act on, without installing anything. Run it after every configuration change.

unattended-upgrade --dry-run --debug

The honest position is that a hypervisor wants scheduled patching with a human, HA drain and a soak — the rolling procedure from the patching lesson — rather than automatic patching. Unattended upgrades on a Proxmox node are best used to make that window fast, not to replace it.

Under the hood

Why the kernel is managed by two systems, and what each one owns.

apt installs kernel packages into /boot and maintains the dependencies. proxmox-boot-tool decides which of the installed kernels is copied onto the EFI System Partitions and which is the default boot entry. On a ZFS-root system the second is the one that determines what runs, because the bootloader reads the ESP and never touches the pool.

That split is why apt-mark hold on a kernel is usually the wrong tool. It prevents new kernels being installed at all, so the node stops receiving them, stops having them available to test, and stops accruing the security fixes they carry — while proxmox-boot-tool kernel pin achieves the operational goal of “keep booting the one that works” without any of that. Pin to control what boots; hold only when you have a specific reason to prevent the package arriving.

Three related mechanics worth having.

Proxmox uses kernel metapackages. proxmox-default-kernel depends on the current default series and pulls in a new versioned kernel package when the default moves — which is what made the 9.2 transition from the 6.x series to 7.0 happen on ordinary upgrades rather than as an opt-in. Holding the metapackage freezes the series; pinning a version freezes what boots.

The ESP bounds how many kernels you can keep. At 512 MB, each kernel plus its initramfs is a few hundred megabytes, so the set is small. proxmox-boot-tool kernel remove frees space on every synced ESP, and an ESP that fills produces an update-initramfs failure during an ordinary apt upgrade — an out-of-space error that names the ESP rather than the root filesystem.

A pin is written onto each ESP during refresh. So a pin applied while one disk was absent does not reach that disk until it is refreshed again, and a node whose ESPs disagree can boot different kernels depending on which disk the firmware chose.

On the apt side, the priority model is what makes preferences subtle. A package version gets a priority from the repository it came from — 500 by default for a normal configured repository, 100 for installed packages not available anywhere. Below 500 means “not preferred”, so a repository pinned to 100 supplies packages only when a version is requested explicitly. Above 1000 means “install even if that is a downgrade”, which is powerful and is the setting that produces surprising results when copied without understanding. apt-cache policy prints the resolved priorities, and it is the only reliable way to know what a preferences file actually did.

What happens if the new default kernel breaks one hardware class in a mixed fleet?

This is the realistic shape of the PVE 9.2 kernel transition, and it is worth walking through because the instinctive responses are mostly wrong.

Symptoms are hardware-specific and load-dependent: a NIC that stops passing traffic under sustained load, an HBA that resets, a passthrough device that no longer binds, storage latency that climbs on one model of server and nowhere else. The nodes that are fine are genuinely fine, which makes the first hypothesis “something is wrong with that node” rather than “something is wrong with that kernel”.

Stop the rollout first. The remaining nodes on the old kernel are two things at once: capacity that still works, and the control group. Losing them costs you the fastest diagnostic available, which is differential — comparing a working host against a broken one.

Pin, do not remove. proxmox-boot-tool kernel pin on the last known-good version returns the affected nodes to service. Removing the new kernel throws away the evidence needed to reproduce the fault and report it, and you will need to test the fix eventually.

Characterise before you generalise. Record what the affected nodes have in common — server model, NIC model and firmware revision, HBA, BIOS version. “7.0 panics on the R650s with the older BIOS” is a finding someone can act on; “7.0 broke some nodes” is not. Fleets that look homogeneous in inventory are routinely not homogeneous in firmware.

Check firmware before blaming the kernel. A new kernel frequently exposes a firmware bug that the old one worked around, and the fix is often a NIC or HBA firmware update rather than a kernel change. The firmware lesson covers the mechanics; the point here is that “pin the kernel” and “update the firmware” are complementary, and only the second is a resolution.

Give the pin an expiry. A pinned node is a node not taking kernel security updates. That is an acceptable trade for a week while you investigate and a poor one for a year. Ticket it with a date, and put proxmox-boot-tool kernel list in your inventory so the pinned nodes are visible without asking.

The one thing not to do is upgrade the rest of the fleet in the hope that the affected nodes are unusual. They are unusual — that is the finding — and adding more of them turns a bounded problem into an estate-wide one with no control group left.

Common mistakes

Mixed repositories across one cluster. Version skew nobody chose, surfacing at migration time.
A suite still saying bookworm on a PVE 9 node. That is PVE 8 packages on Debian 13.
debian.sources without non-free-firmware. CPU microcode cannot be installed, silently.
A hold with no review date. The package stops receiving security updates while apt reports success.
Downgrading without a hold. The next apt upgrade undoes it, during a routine window.
apt clean during a change window. The cache is often the only copy of the version you would roll back to.
apt-mark hold on a kernel instead of proxmox-boot-tool kernel pin. Stops new kernels arriving rather than controlling which one boots.
--next-boot used as a permanent rollback. It reverts at the following reboot.
Unattended-Upgrade::Automatic-Reboot "true" on a hypervisor. Every guest, at whatever hour the timer fires, with no drain.

Key takeaways

Enterprise, no-subscription and test are the same code at different ages. Enterprise is recommended for production; pick one per cluster.
PVE 9 means trixie in every suite, and non-free-firmware in debian.sources for microcode.
trixie-security carries base-OS fixes and is unaffected by the repository timing question.
A hold silently stops security updates. apt-mark showhold is the only way to find one.
Downgrade, then hold, or the next upgrade undoes it. Prefer apt autoclean to apt clean.
Pin what boots with proxmox-boot-tool kernel pin; hold what installs with apt-mark hold. The first is usually the right tool.
--next-boot tests a kernel; a plain pin keeps one.
Every pin and hold needs a ticket with a date, and a fleet-wide check.
Unattended upgrades on a hypervisor: download automatically, install deliberately, never reboot automatically.

Knowledge check

Why this matters

Repositories and pins are configuration nobody looks at, which is exactly what makes them worth a lesson.

A repository choice made during installation determines how quickly every future fix reaches the node, and it is invisible afterwards — no alert fires because a cluster is split across two repositories, and the consequence shows up as a migration failure attributed to something else. A hold applied during an incident three years ago is invisible in the same way, and worse, because apt actively reports success while the package stands still.

That shared property — silent, permanent unless someone revisits it — is why the operational answer is not better judgement at the moment of change. It is inventory. apt-mark showhold, proxmox-boot-tool kernel list, and the resolved output of apt-cache policy, collected as facts across the fleet and reviewed on a cadence, turn three invisible states into three lists somebody reads.

The kernel half is the live one. PVE 9.2’s move to the 7.0 series is the sort of change that is uneventful on most hardware and unpleasant on some, and the difference between those two outcomes being a bounded incident or an estate-wide one comes down to two habits: upgrade one node first and let it soak, and know that pinning is available before you need it.

And then, because a pin trades an availability risk for a security one, the last habit: give it a date. The failure mode of good crisis management is a mitigation that becomes permanent because it worked.