Configuration

Configuration Guide

Linux Hello is highly configurable via ~/.config/face-auth/config.yaml.

Global Settings

Setting	Type	Description	Default
logging.level	String	Log verbosity (DEBUG, INFO, WARNING, ERROR)	INFO
logging.file	Path	Log file location	~/.local/share/face-auth/face_auth.log

Camera Settings (camera)

camera:
  device_id: 0              # /dev/video0 (or path like /dev/v4l/by-path/...)
  width: 640                # Capture width
  height: 480               # Capture height
  fps: 30                   # Capture FPS

Recognition Settings (recognition)

recognition:
  model: "hog"              # "hog" (CPU, faster) or "cnn" (GPU, slower but accurate)
  tolerance: 0.6            # Match strictly (lower = stricter). 0.6 is balanced.
  num_jitters: 1            # Re-sampling for higher accuracy (slows down process)
  security_mode: "balanced" # See below

Security Modes

• fast: Tolerance 0.7, requires 1 sample match.
• balanced: Tolerance 0.6, requires 2 sample matches.
• secure: Tolerance 0.5, requires 3 sample matches.

Performance Tuning

recognition:
  scale_factor: 0.5       # Downscale for faster detection
                          # 0.25 = fastest (lower accuracy)
                          # 0.5 = balanced (recommended)
                          # 1.0 = full resolution (slowest)
  
  try_rotations: false    # Try 90°/180°/270° rotations during auth
                          # true = handles rotated camera/device (slower)
                          # false = faster, upright faces only

Monitoring Settings (monitoring)

These settings control the "walk-away lock" daemon.

monitoring:
  enabled: true
  check_interval: 2.0     # Check presence every 2 seconds
  absence_timeout: 30.0   # Lock screen after 30s of no face
  presence_timeout: 5.0   # How long to confirm presence (avoids flickering)

Actions (actions)

Define what happens on specific events.

actions:
  on_absence:
    - lock_screen          # Built-in action
    # - custom_script: /path/to/script.sh
  on_presence:
    - log
  on_auth_success:
    - log