KMX - Linux Mint Package Verifier

Linux Mint Package Verifier (mint_verifier) is a C++23 command-line tool that:

• Resolves the Ubuntu base codename for a Linux Mint codename dynamically at runtime.
• Discovers Linux Mint and Ubuntu mirrors.
• Downloads and parses Packages.gz indexes for amd64 packages.
• Compares SHA-256 checksums of packages across mirrors.
• Generates CSV inventories and mismatch reports.
• Prints runtime telemetry (phase timings + peak RSS).

---

Features

• Dynamic Mint → Ubuntu resolution

  • Fetches mintsources.conf from the Linux Mint mintsources repository.
  • Reads base_codename= to determine the Ubuntu base release.

• Mirror discovery

  • Mint mirrors from:
    • http://packages.linuxmint.com/ (always first)
    • https://linuxmint.com/mirrors.php (scraped + deduplicated)
  • Ubuntu mirrors from:
    • http://archive.ubuntu.com/ubuntu/ (always first)
    • http://mirrors.ubuntu.com/ country files (XX.txt) (fetched + deduplicated)

• Bounded concurrency

  • Fixed-size worker pool for downloads (max_concurrent = 16 by default).
  • Avoids unbounded async fan-out and large memory spikes.

• Efficient parsing and reporting

  • Parses gzip package indexes with zlib.
  • Stores SHA-256 in fixed-size arrays (std::array<char, 64>).

• Configurable HTTP timeout

  • Default request timeout: 5 seconds.
  • Override per run via CLI argument.

---

Project Structure

include/kmx/lm/package_verifier/
  application.hpp
  checksum_comparator.hpp
  http_client.hpp
  mirror_finder.hpp
  package_downloader.hpp
  package_parser.hpp
  types.hpp

src/
  main.cpp
  kmx/lm/package_verifier/
    application.cpp
    checksum_comparator.cpp
    http_client.cpp
    mirror_finder.cpp
    package_downloader.cpp
    package_parser.cpp

---

Requirements

• Linux (uses /proc/self/status telemetry and /tmp cache path)
• CMake 3.25+
• C++ compiler with C++23 support (GCC 13+ or Clang 17+ recommended)
• zlib development package
• pthread support
• curl CLI available in PATH (used by the HTTP client wrapper)

Ubuntu/Debian example dependencies

sudo apt update
sudo apt install -y build-essential cmake zlib1g-dev curl

---

Build

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

Binary output:

• build/mint_verifier

---

Usage

./build/mint_verifier <linux_mint_codename> [timeout_sec]

Examples:

./build/mint_verifier zena
./build/mint_verifier zena 10

Arguments:

• linux_mint_codename
  • Required.
  • Lowercase letters only.
  • Example: zena.
• timeout_sec
  • Optional.
  • Positive integer; overrides default HTTP timeout for this run.

On startup, the app prints the effective timeout and selected target pair:

• Linux Mint codename
• Resolved Ubuntu base codename

---

What the Tool Downloads

For each discovered mirror, the downloader builds this path:

<mirror>/dists/<codename>/<component>/binary-amd64/Packages.gz

Components checked:

• Linux Mint: main, upstream, import, backport
• Ubuntu: main, restricted, universe, multiverse

Downloaded files are cached in:

• /tmp/mint_verifier_cache/

using deterministic filenames derived from URL hash.

---

Output Files

For each ecosystem, two reports are produced in the current working directory:

• linux_mint_packages.csv
• linux_mint_mismatches.txt
• ubuntu_packages.csv
• ubuntu_mismatches.txt

CSV format

Header:

Package,Version,SHA256,Mirror

Each row is one package entry from one mirror.

Mismatch report format

• Lists only packages whose SHA-256 differs across at least two mirrors.
• If no mismatches are found, file contains:

No mismatches detected. All packages match across all mirrors.

---

Runtime Telemetry

The app prints phase durations:

• Resolve base codename
• Mirror discovery
• Downloads
• Report generation
• Total

It also prints peak memory usage (RSS, GiB):

• after mirror discovery
• after downloads
• final

---

Networking Behavior and Exit Codes

The internal HTTP layer uses curl and treats non-zero exits as failures.

Common cases:

• curl exit 22

  • HTTP error with --fail enabled (typically HTTP 4xx/5xx).
  • Often means the mirror does not contain that exact distro/component/arch path.

• curl exit 28

  • Operation timeout.
  • The app logs timeout lines as:
    • [http_client] Timeout after <N>s: <url>

The application continues processing remaining mirrors/components; failed URLs contribute empty results.

---

Performance Notes

• Concurrency is intentionally bounded to keep memory stable on large mirror sets.
• Progress output is rate-limited to reduce console flush overhead.
• Cache + conditional download (curl -z) reduce repeated transfer cost.

If you want faster runs on high-bandwidth systems, increase downloader concurrency in code (package_downloader constructor default).

---

Troubleshooting

• No Ubuntu codename resolved

  • Verify Mint codename spelling.
  • Check internet access to GitHub raw content.

• Frequent Download failed (curl exit 22)

  • Some mirrors may be incomplete for the target codename/component.
  • Inspect a failing URL directly:

    curl -I -L "<failing_url>"

• Frequent timeouts (curl exit 28)

  • Increase timeout argument:

    ./build/mint_verifier zena 15

• Binary built but command not found

  • Run with explicit path: ./build/mint_verifier ...

---

Notes and Limitations

• Current implementation targets amd64 indexes.
• Mirror discovery depends on external sites and their current HTML/listing format.
• Network failures are tolerated per mirror; reports are based on successful fetches only.

---

License / Copyright

Copyright (c) 2026 - present KMX Systems. All rights reserved.