Universal, production-ready facial recognition authentication system and multi-camera biometric engine for Linux.
Works seamlessly on Ubuntu Desktop, Ubuntu Server, Debian, Linux Mint, Pop!_OS, Fedora, and Arch Linux.
Standard upstream Howdy faces severe performance degradation in dynamic real-world environments (backlight silhouettes, thermal sensor grain, specular reflections, off-axis multi-monitor postures, and presentation attacks). This distribution incorporates the complete enterprise blueprint for Linux facial biometrics:
-
Adaptive Photometric Dynamics (Multi-Scale Retinex with Color Restoration - MSRCR):
- Decomposes observed frames into reflectance and illumination components:
$$I(x, y) = R(x, y) \cdot L(x, y)$$ - Strips high-frequency sensor noise via bilateral edge-preserving filtering without blurring facial boundaries.
- Dynamically adapts gamma (
$\gamma \in [0.40, 0.75]$ ) and multi-scale Gaussian surrounds ($\sigma \in {15, 80}$ ) under harsh backlight ($L < 95$ ), pulling internal eye and nose contours directly out of dark silhouettes. - Compresses specular highlights and desk lamp glare under high luminance (
$L > 160$ ).
- Decomposes observed frames into reflectance and illumination components:
-
Deep Learning Vision Backbone (OpenCV YuNet CNN):
- Replaces legacy dlib HOG detectors with an ultra-lightweight depthwise separable CNN (76,000 parameters, 0.08 GFLOPs).
- Achieves sub-6ms single-core inference latency and extends off-axis yaw angle tolerance to
$\pm 85^\circ$ (enabling natural unlock even when looking toward secondary displays). - Auto-extracts 5 facial landmark anchors (right eye, left eye, nose tip, mouth corners) with SVD Procrustes canonical geometric alignment.
-
Passive Anti-Spoofing & Liveness Verification (MiniFASNet):
- Evaluates micro-texture surface reflectance and auxiliary 2D Fast Fourier Transform (FFT) frequency spectrums in 3.4ms.
- Identifies pixel grid frequency anomalies and planar light profiles to block 2D paper printouts, tablet screen replays, and 3D silicone mask presentation attacks without requiring friction-inducing active challenges (blinking/head turns).
-
Universal Hardware Compute Engine & Dynamic GPU Auto-Detection:
- Automatically probes and arms available hardware acceleration providers at runtime:
-
NVIDIA CUDA (
CUDAExecutionProvider/ TensorRT) on workstations with dedicated GPUs. -
Intel OpenVINO (
OpenVINOExecutionProvider) on Intel Core CPUs and Iris Xe / ARC integrated graphics. - AMD ROCm on supported AMD Radeon systems.
-
NVIDIA CUDA (
- Zero-Dependency Fallback: If no GPU drivers are present, the engine automatically operates on CPU SIMD vector extensions (AVX2/FMA/NEON), ensuring 100% plug-and-play operation across any Linux distribution or machine.
- Automatically probes and arms available hardware acceleration providers at runtime:
-
Universal Multi-Camera Concurrent Acquisition & ACPI Clamshell Lid Gating:
- Automatically discovers, arms, and queries all attached video sensors concurrently in parallel via multithreading.
- Checks ACPI clamshell lid state (
/proc/acpi/button/lid/*/state): if a laptop lid is closed while docked to external displays, it automatically deactivates the obscured internal laptop camera and routes capture to external webcams (e.g. Logitech Brio). If no external camera is connected, it bypasses camera polling instantly, falling back to fingerprint in 0ms.
-
POSIX Volatile Memory Hardening & glibc RSS Leak Elimination:
- Pins process address space into physical RAM via
mlockall(MCL_CURRENT | MCL_FUTURE)to prevent secret biometric vectors from ever paging out to Linux swap partitions or disk. - Enforces glibc memory thresholds (
MALLOC_MMAP_THRESHOLD_=65536) and triggers explicit C heap trimming (malloc_trim(0)) after every authentication cycle, eliminating RSS memory accumulation in long-running PAM sessions.
- Pins process address space into physical RAM via
-
Hardware-Bound AES-256-GCM AEAD Vault with XZ (LZMA2) Compression:
- Face model files (
models/<user>.dat) are compressed with XZ (LZMA2 Preset 6) and encrypted on disk with authenticated AES-256-GCM (HOWDY_ENC_XZ_V3). - 1,000 face models compress from 2.62 MB down to 454 KB on disk (83% reduction) while decrypting and decompressing in volatile RAM in 17ms.
- Master key is cryptographically bound to the platform identity (
/etc/machine-id) using HKDF-SHA256. Plaintext biometric vectors exist strictly in volatile RAM.
- Face model files (
-
Interactive Sci-Fi Biometric HUD (
howdy test):- High-tech biometric HUD with landmark constellation mesh, target reticle crosshairs, confidence meters, lighting badges, and detector status overlays.
- Dynamic split-view camera matrix with live hotplug detection.
- Integrated top-right
[X CLOSE / EXIT]button with instant mouse-click event handling, window manager close detection, and signal handling.
-
High-Performance 30+ FPS Interactive HUD Enrollment (
howdy-hud-enroll):- Seamless live enrollment HUD capable of capturing 1,000+ high-precision face scans across multiple cameras, angles, distances, and expressions.
- Decoupled architecture: background
ThreadedCameraframe capture eliminates USB I/O blocking, while an asynchronous vector embedding worker thread processes neural descriptors without causing GUI lag or frame drops. - Periodic atomic checkpoints to disk every 50 scans with real-time visual progress bar.
-
Dynamic Hardware Sensor Calibration & USB Monitor Webcam Prioritization:
- Intelligently probes sensor sharpness control scales (
1..7on integrated laptop cameras vs0..255on USB webcams like Logitech Brio 100), ensuring optimal edge sharpness on every device. - Disables dynamic framerate throttling on supported webcams, halving frame latency from 67ms to 33ms (solid 30 FPS).
- Automatically prioritizes external USB webcams over integrated laptop cameras so the primary monitor camera captures on Frame 1 when docked at a desk.
- Intelligently probes sensor sharpness control scales (
Install, build, and configure the complete face recognition engine in a single command across Ubuntu, Debian, Fedora, Arch Linux, and openSUSE:
curl -fsSL https://raw.githubusercontent.com/ImNotMrReaper/howdy-face-id-linux/main/install.sh | sudo bashgit clone https://github.com/ImNotMrReaper/howdy-face-id-linux.git
cd howdy-face-id-linux
sudo ./install.shsudo dpkg -i howdy-face-id-auth_1.2.0_amd64.deb
sudo apt-get install -fEnroll your face profile across all connected cameras in a single take:
sudo howdy addCalibrate your face profile across 5 distinct poses (neutral, left, right, up, down):
sudo howdy scanVerify your camera alignment, certainty scores, and real-time biometric matching:
sudo howdy testPress q or ESC to exit the HUD.
# List encrypted biometric models:
sudo howdy list
# Remove a specific model ID:
sudo howdy remove <ID>
# Clear all models for a user:
sudo howdy clearThe installer automatically configures your PAM pipeline across:
- Terminal Sudo:
/etc/pam.d/sudo - Desktop Privilege Elevation:
/etc/pam.d/polkit-1 - Central Common Auth:
/etc/pam.d/common-auth - Lockscreen & Login:
/etc/pam.d/gdm-password(or lightdm/sddm)
# Recommended Authentication Hierarchy:
auth sufficient pam_python.so /lib/security/howdy/pam.py
auth sufficient pam_python.so /lib/security/reaper_fprint_pam.py
auth sufficient pam_unix.so try_first_pass nullok
auth required pam_deny.so
To compile and build a fresh .deb binary on any Debian/Ubuntu machine:
./build_deb.shThe resulting package will be generated at ./howdy-face-id-auth_1.0.0_amd64.deb.
To completely remove the package and restore stock PAM configurations:
# Via script:
sudo ./uninstall.sh
# Or via apt:
sudo apt remove howdy-face-id-auth| Distribution | Status | Installation Method |
|---|---|---|
| Ubuntu 24.04 LTS (Desktop & Server) | ✅ Fully Verified | .deb or install.sh |
| Ubuntu 22.04 LTS (Desktop & Server) | ✅ Fully Verified | .deb or install.sh |
| Debian 12 (Bookworm) | ✅ Supported | .deb or install.sh |
| Linux Mint 21 / 22 | ✅ Supported | .deb or install.sh |
| Pop!_OS 22.04 / 24.04 | ✅ Supported | .deb or install.sh |
| Fedora 38 / 39 / 40 | ✅ Supported | install.sh |
| Arch Linux | ✅ Supported | install.sh |
This distribution builds upon and integrates extraordinary contributions from the open-source computer vision and Linux biometrics communities. Full details and license notices are documented in CREDITS.md.
- Howdy (Original Framework) by Slavik "boltgolt" (MIT License): Foundational Linux PAM facial authentication architecture, CLI toolchain, and daemon infrastructure.
-
OpenCV Zoo & YuNet Deep CNN by Shiqi Yu, Feng Ne, and the OpenCV Team (Apache 2.0): Lightweight depthwise separable CNN face detection model (
face_detection_yunet_2023mar.onnx) providing sub-6ms inference,$\pm 85^\circ$ yaw tolerance, and 5-point facial landmark localization. - Silent-Face-Anti-Spoofing & MiniFASNet by Minivision AI (ONNX Conversion by Fido Garcia, Apache 2.0): Passive anti-spoofing and liveness verification analyzing surface reflection micro-textures and Fourier 2D FFT spectrums.
-
dlib Toolkit by Davis E. King (Boost Software License 1.0): High-precision 29-layer ResNet face recognition model (
dlib_face_recognition_resnet_model_v1.dat) and 5-point landmark shape predictor. - OpenCV by OpenCV.org Foundation (Apache 2.0): VideoCapture V4L2 camera streaming backend, colorspace conversions, CLAHE contrast equalization, and DNN inference modules.
- Microsoft ONNX Runtime by Microsoft Corporation (MIT License): High-performance neural network runtime with automated dynamic hardware execution provider probing (CPU SIMD, OpenVINO, CUDA/TensorRT, ROCm).
- pam-python by Russell Stuart (GNU LGPL 2.1): C PAM bridge enabling native Python PAM conversation handlers.
- PyCA Cryptography by Python Cryptographic Authority (Apache 2.0 / BSD 3-Clause): Authenticated Encryption with Associated Data (AES-256-GCM AEAD) and HKDF-SHA256 hardware key derivation.
- XZ Utils & LZMA SDK by Igor Pavlov and Lasse Collin / Tukaani Project (Public Domain / LGPL): Ultra-compact LZMA2 compression powering the 454 KB biometric template vault.
- Multi-Scale Retinex with Color Restoration (MSRCR): Jobson, D. J., Rahman, Z., & Woodell, G. A. (1997). "A multiscale retinex for bridging the gap between color images and the human observation of scenes". IEEE Transactions on Image Processing, NASA Langley Research Center.
- Deep Residual Learning for Image Recognition (ResNet): He, K., Zhang, X., Ren, S., & Sun, J. (2016). "Deep Residual Learning for Image Recognition". IEEE Conference on Computer Vision and Pattern Recognition (CVPR).
- Face Anti-Spoofing via Fourier Micro-Textures: Zhang, Z., Yan, J., Liu, S., Lei, Z., Yi, D., & Li, S. Z. (2012). "A face antispoofing database with diverse attacks". IAPR International Conference on Biometrics (ICB).
- Enterprise Linux Biometrics Blueprint: Gemini Deep Research Architectural Blueprint.
Licensed under the MIT License. See LICENSE for full legal text.
Individual upstream models, libraries, and dependencies retain their respective original licenses (MIT, Apache 2.0, Boost Software License 1.0, LGPL 2.1, and Public Domain).