howto/upgrades.md

@@ -109,6 +109,34 @@ the timer `prometheus-node-exporter-apt.timer` triggers. It currently runs every
 15 minutes, so it's probably not necessary to trigger it by hand to speed things
 up.
 
+## Blocked upgrades
+
+<!-- note that this section is cross-referenced from the -->
+<!-- OutdatedPackages alert in prometheus-alerts.git change the -->
+<!-- link target there if you change the heading here. -->
+
+Outdated packages are packages that don't currently relate to one of the
+configured package archives. Some causes for the presence of outdated packages
+might be:
+
+* leftovers from an OS upgrade
+* apt source got removed but not packages installed from it
+* patched package was installed locally
+
+If you want to know which packages are marked as obsolete, you can use the
+following two commands:
+
+    apt list "?obsolete"
+    # The following will mainly print the same list as above, but there might be
+    # some more in its list.
+    DEBUG=1 /usr/share/prometheus-node-exporter-collectors/apt_info.py
+
+Check the state of each package with `apt policy $package` to determine what
+needs to be done with it. If most cases, the packages can just be purged, but
+maybe not if they are obsolete because an apt source was lost. In that latter
+case, you may want to check out why the source was removed and make sure to
+bring it back.
+
 ## Out of date package lists
 
 The `AptUpdateLagging` looks like this: