What it is
pakfire-manual is a pakfire add-on for IPFire 2.29 x86_64. It applies core updates one step at a time, with explicit checks before each step.
The add-on installs a WUI page under IPFire → Extras → Pakfire-Manual for managing data files, and a CLI tool (pakfire-planner.sh) that you run as root from an SSH session when you are ready to apply a step.
How it integrates with pakfire
The package installs as a standard .ipfire add-on - the same way as any other pakfire package:
cd /opt/pakfire/tmp
tar -xvf pakfire-manual-vX.Y.Z.ipfire
NAME=pakfire-manual bash install.sh
It does not replace or patch pakfire. It calls IPFire’s own update.sh for each core step, exactly as pakfire would, after running its own pre-flight checks. Data files (mirrors.allow, known_breakage.tsv, core_addon_matrix.tsv) survive package upgrades through IPFire’s standard addon backup mechanism.
Why it exists
pakfire upgrade applies all pending core updates in one shot. When several core updates are pending - each with its own add-on changes, open bugs, and breaking changes - a single-shot upgrade gives no way to check intermediate state or stop at a known-good point if one step fails.
pakfire-manual works through a six-phase pipeline:
- Local state - reads the current core level, installed add-ons, and pending updates
- Upgrade plan - builds a per-step plan with add-on version changes and known-breakage information
- Mirror survey - probes all configured mirrors and records which ones serve the full pakfire2 2.29 x86_64 tree
- Fetch and verify - downloads intermediate core packages from a confirmed mirror and GPG-verifies each one against the IPFire project signing key (hard stop on failure)
- Deploy - applies exactly one core step; refuses if a
crash-severity bug is open for the target version - Handoff - writes a post-upgrade summary to syslog
The deploy hold is the key gate. If known_breakage.tsv contains a crash-severity entry for the target core update, Phase 5 refuses and shows the blocking bug IDs. You resolve the entry when the bug is fixed upstream, then run again.
The WUI manages the data files - mirror list, known-breakage table, add-on version matrix - without requiring SSH access for day-to-day maintenance.
Geo-aware mirror selection
On systems with a strict outgoing geo-block policy, pakfire upgrade picks mirrors with no knowledge of your firewall rules. The connection may fail silently, with no useful error shown.
pakfire-manual reads your live Location Group from /var/ipfire/fwhosts/customlocationgrp on every run, resolves all IP addresses a mirror hostname returns (including round-robin entries), and checks each one against the same libloc database your packet filter uses. Any mirror with a BLOCKED verdict is skipped and logged.
No static config. No manual overrides. If you add a country to your outgoing block group today, the tool skips mirrors in that country on its next run - no config file to update.
Requirements
- IPFire 2.29 x86_64
location(libloc) - standard on IPFirecurl- GPG keyring with the IPFire project signing key - imported automatically on first use; no manual setup needed
The add-on is aware of firewall-local and reads its Outgoing Location Block group if present. It is not a dependency - the geo-check falls back gracefully if customlocationgrp does not exist.
Links
- Repository: GitHub - horace-michael/pakfire-manual: IPFire 2.29 x86_64 controlled sequential upgrade planner — step-by-step pakfire upgrade with geo-aware mirror selection and guarded deploy · GitHub
- Install: download the latest
.ipfirepackage from the Releases page - Usage guide (WUI walkthrough with screenshots): USAGE.md
Credits
This tool was inspired by @pscar13.
The original idea - applying core updates one step at a time, with explicit review at each gate - came from this post:
Pakfire upgrade to specific version
Without that post this package would not exist.
Feedback, missed edge cases, and breakage reports are welcome.
