Facelock reads its configuration from /etc/facelock/config.toml. Override the path with the FACELOCK_CONFIG environment variable. Note: FACELOCK_CONFIG is ignored by privileged PAM and root auth flows, which always use either an explicit --config path or /etc/facelock/config.toml.
All settings are optional. Facelock auto-detects the camera and uses sensible defaults. The annotated config file at config/facelock.toml in the repository serves as the canonical example.
Run facelock setup to select a model tier interactively and download the required models.
If you point detector_model or embedder_model at a custom file, you must also set the matching SHA256 so the daemon can verify it at load time.
Controls how the PAM module reaches the face engine.
Key
Type
Default
Description
mode
string
"daemon"
"daemon" connects to a persistent daemon via D-Bus system bus (~200ms warm, ~600ms cold). "oneshot" spawns facelock auth per PAM call (slower, ~600ms+, no background process).
model_dir
string
"/var/lib/facelock/models"
Directory containing ONNX model files.
idle_timeout_secs
u64
0
Shut down the daemon after this many idle seconds. 0 means never. Useful with D-Bus activation.
Disable face authentication entirely. PAM returns IGNORE, falling through to the next auth method.
abort_if_ssh
bool
true
Refuse face auth when connected via SSH (no camera available).
abort_if_lid_closed
bool
true
Refuse face auth when the laptop lid is closed (camera blocked).
require_ir
bool
true
Require an IR camera for authentication. RGB cameras are trivially spoofed with a printed photo. Only set to false for development/testing.
require_frame_variance
bool
true
Require multiple frames with different embeddings before accepting. Defends against static photo attacks.
require_landmark_liveness
bool
false
Require landmark movement between frames to pass liveness check. Detects static images by tracking facial landmark positions across frames. Experimental; off by default.
landmark_displacement_px
f32
1.5
Minimum pixel displacement for a landmark to count as "moving" between frames. Only used when require_landmark_liveness is true.
landmark_min_moving
u32
3
Number of facial landmarks (out of 5) that must show movement to pass the liveness check. Only used when require_landmark_liveness is true.
suppress_unknown
bool
false
Suppress warnings for unknown users (users with no enrolled face).
min_auth_frames
u32
3
Minimum number of matching frames required before accepting. Only applies when require_frame_variance is true.
Controls how face embeddings are encrypted at rest.
Key
Type
Default
Description
method
string
"none"
"none" -- no encryption. "keyfile" -- AES-256-GCM with a plaintext key file. "tpm" -- AES-256-GCM with a TPM-sealed key (recommended if TPM available).
key_path
string
"/etc/facelock/encryption.key"
Path to AES-256-GCM key file for keyfile method.
sealed_key_path
string
"/etc/facelock/encryption.key.sealed"
Path to TPM-sealed AES key for tpm method.
With method = "tpm", the 32-byte AES key is sealed by the TPM at rest. At daemon startup, the key is unsealed and held in memory. Embeddings use the same AES-256-GCM format as keyfile — no re-encryption needed when migrating between methods. Migration commands: facelock tpm seal-key (keyfile → tpm) and facelock tpm unseal-key (tpm → keyfile).