Irlume

irlume is a Windows Hello–style face login daemon for Linux, written in Rust. It authenticates through PAM and adapts to the available hardware: an infrared (Windows Hello) camera enables the secure tier (greeter login, sudo, and TPM-sealed keyring unlock, with an anti-spoof liveness gate), a regular RGB webcam enables the convenience tier (lock-screen unlock only), and a fingerprint reader can be used as a companion factor. The password always remains as fallback.

Face data is stored as 512-dimensional embeddings, never images. On a system with a TPM the embeddings are encrypted with AES-256-GCM under a TPM-sealed key; without a TPM they are stored in root-only files and keyring unlock is unavailable.

Installation

Install the irlume^AUR package.

The package builds from the signed upstream Git tag. The ONNX model weights are fetched via Git LFS during the build, so git-lfs is a build dependency. It depends on a provider of onnxruntime (onnxruntime-cpu, onnxruntime-cuda or onnxruntime-rocm), tpm2-tss and pam; the onnxruntime provider is chosen at install time.

The package enables and starts irlumed.service automatically.

Configuration

Installation wires nothing into PAM; face authentication is opt-in.

Enroll your face and review the guided setup (a self-diagnosing TUI):

$ irlume tui

On an infrared camera, enrollment probes the sensor and automatically enables the infrared emitter if its frames come back dark, so no separate step is normally needed. Only if infrared frames stay dark after enrolling, enable the emitter manually (infrared cameras only, and it requires root):

# irlume ir-setup

Wire the greeter and lock screen (without --apply this is a dry run that prints the per-file wiring plan without writing anything):

# irlume login enable --apply

To also use face authentication for sudo, pass --with-sudo.

Keyring unlock

On the secure tier, a face match can release your login password from the TPM so that GNOME/Keyring or KDE Wallet unlocks at login, as with a password login:

$ irlume keyring arm

Re-run this after changing your login password.

Reverting

All PAM changes are removed with:

# irlume login disable --apply

The password prompt is never removed; a failed or unavailable face scan always falls through to the password.

Troubleshooting

The TUI (irlume tui) has a Repair screen that detects and one-key-fixes common faults (daemon down, stale socket, missing models, PAM wiring inconsistencies, stuck fingerprint reader claims, camera/emitter issues). Check it first.

Logs go to the journal: journalctl -u irlumed.

For per-stage tracing (capture timings and match scores, numbers only, never frames or embeddings), set IRLUME_LOG=debug in the environment, or persist it as root with irlume logs debug on. irlume logs shows a filtered journal view for diagnosing authentication problems.

Dark or dim login stops working after upgrading

Infrared templates enrolled before a major recognition change (for example the 0.2.0 removal of the shipped IR adapter) are stored in a different embedding space and no longer match; the daemon logs a notice to that effect. Bright-light (RGB) login and the password are unaffected. On irlume 0.2.1 or later, capture fresh scans to restore infrared login; they are added to the existing profile in one step:

$ irlume enroll

On irlume 0.2.0 exactly, irlume enroll refuses with "this face is already enrolled": run irlume tui, open Profiles, select the profile and choose improve (or run irlume enroll --reset for a clean start), or upgrade to 0.2.1 first.

Security

Upstream documents its threat model, an ISO/IEC 30107-3 presentation-attack self-test (including honest limitations of the opt-in passive blink liveness against determined glossy prints and for glasses wearers), and an at-rest audit including a cross-machine disk-theft test. See the Honest limitations section and SECURITY_AT_REST.

RGB-only (no IR) face matching is deliberately restricted to unlocking the screen and never releases credentials.