A tested fix for uunicorn/python-validity
0.15, where the Synaptics Metallica MIS fingerprint reader (06cb:009a)
can stop answering and send the daemon into an unbounded restart loop while
flooding the system journal.
| Upstream PR | uunicorn/python-validity#290 (ready for review) |
| Companion PR | uunicorn/open-fprintd#30 |
| Root-cause issue + patch | uunicorn/python-validity#272 |
| Related open PRs credited | #245, #273, #284, #249, #285, #217, #255, open-fprintd #24 |
This repository is the standalone overlay: the patch, the Arch packaging to apply it, the local remediation scripts, and the raw validation evidence.
On an Arch-based system (Omarchy) with Python 3.14 / pyusb 1.3.1 / libusb 1.0.30:
- Fingerprint login works, then stops after a reboot/suspend, and
python3-validity.servicekeeps restarting. journalctl -u python3-validityis full ofusb.core.USBTimeoutError: [Errno 110] Operation timed out.- The system journal balloons;
journalctl --disk-usagesat at the default 4 GiB ceiling.
init.open() -> open_common() -> init_flash() -> get_flash_info()
-> tls.cmd('3e') -> usb.cmd() -> dev.write(1, out)
usb.core.USBTimeoutError: [Errno 110] Operation timed out
atexit.register(close)runs only after a successfulopen_common(), andclose()is the only code that resets the USB device. A failed init therefore never resets the stuck sensor, so the next start hits the same state.- Arch's AUR PKGBUILD patches upstream
Restart=notoRestart=on-failurewith the defaultRestartSec=100msandStartLimitBurst=5 / 10s. Because each attempt takes ~15 s (the USBdefault_timeout), that start limit never trips: the loop is unbounded. - On
06cb:009athe sensor can transiently report busy (0x0104/0x0401), reply to3ewith only the status word (no flash header), and requiressend_init()to run before the protected-flash commands ininit_flash(). - Both
python3-validity.serviceandopen-fprintd.serviceshipped with--debug, dumping hex traffic (including key material) into the journal.
Measured on the affected machine:
| metric | value |
|---|---|
Scheduled restart job events |
12,701 |
| max systemd restart counter | 5,075 |
| starts on the worst day | 5,267 |
USBTimeoutError [Errno 110] that day |
10,530 |
| journal | pinned at 4.1 GiB |
--debug only, no crash loop (one day) |
113,639 lines / ~106 MiB |
Full diff: patch/fix.patch.
flash: tolerate a short/empty flash-info reply — a0000-only3ereply no longer crashesunpack(); an unknown flash IC is never formatted with guessed parameters.usb: retry transient0x0104/0x0401busy — boundedcmd_retry_busy()also retries USB timeouts; theinit_hardcodedreply is no longer asserted so the clean-slate fallback is reachable.init: runsend_init()beforeinit_flash()— the ordering06cb:009aneeds.init: reset and re-open the sensor instead of crash-looping —usb.reset()/usb.reopen()plus_open_with_recovery(): a bounded number of attempts with a hard reset/re-open in between.dbus: re-acquire the USB device onResume()—init.resume()opens a fresh handle instead of reusing the stale pre-suspend one.service: drop--debugand throttle restarts —Restart=on-failure,RestartSec=5,StartLimitIntervalSec=300,StartLimitBurst=5.init: never print a traceback from the atexit reboot handler.dbus: log expected verify/enroll cancel and timeout without a traceback.
17 unit tests (pytest, no hardware): upstream PR #290.
- 2 full reboots:
NRestarts=0, services active, 0 init errors, 0 debug dumps, all fingerprints listed. Seedocs/post-reboot.txt. - 14 real suspend/resume cycles: same PIDs throughout (no restart),
NRestarts=0, in-process re-init after each wake, 0 init errors, fingerprints available immediately. Seedocs/resume-matrix.txt. - Journal:
4.1 GiB -> 452 MiB(capped at 500 MiB). - Log volume: projected ~2,731 lines/day, i.e. -97.6% vs the
debug-only day and -98.9% vs the worst crash-loop day.
See
docs/final-metrics.txt.
The local setup also disables the old
python3-validity-suspend-hotfix.service restart unit and relies on
open-fprintd's Suspend()/Resume() path, which removes a ~2 s window where
the lock screen raced the restart.
git clone https://github.com/alhasapi/python-validity-fix
cd python-validity-fix/aur
makepkg -f # builds python-validity 0.15-2 with the patch
sudo ../local/install.sh # installs it + drop-ins + journal cap, restarts serviceslocal/install.sh:
- installs the patched package,
- installs
/etc/systemd/system/open-fprintd.service.d/10-no-debug.confand/etc/systemd/journald.conf.d/00-size.conf(SystemMaxUse=500M), - restarts journald and vacuums the journal,
- disables the now-redundant
python3-validity-suspend-hotfix.service, - restarts
open-fprintd/python3-validityand prints validation output.
Validate with local/validate.sh,
local/resume-matrix.sh and
local/post-reboot-check.sh.
See docs/LOCAL_FIX.md for the rollback procedure.
patch/ combined diff + commit list
aur/ PKGBUILD overlay that applies the patch to 0.15
local/ install/validate scripts and systemd/journald drop-ins
docs/ evidence, upstream links, PR texts and raw validation output
Built on the analysis and patches of the upstream contributors, in particular
#272 (root cause + patch), #245, #273, #284, #249,
#285, #217, #255, and open-fprintd #24 (PrepareForSleep).
See docs/UPSTREAM.md for the full list of notifications.
MIT for the scripts and documentation in this repository, matching
python-validity (MIT). The patch modifies upstream MIT-licensed code.
See LICENSE.