Howdy Facial Recognition — Setup & Usage Manual

For Fedora Workstation with GNOME & Windows Hello IR Camera

What This Does

This installer sets up facial authentication on Fedora using your laptop's Windows Hello IR camera. Once configured, you can unlock your screen, authorize sudo commands, and authenticate anywhere a password prompt appears — just by looking at your laptop. If the camera can't see you or recognition fails, it automatically falls back to your regular password.

Supported authentication points:

  • GNOME lock screen (GDM)
  • sudo commands in the terminal
  • su user switching
  • Polkit GUI password dialogs (e.g., Software Center installs)

First-Time Setup

Prerequisites

  • Fedora Workstation with GNOME (tested on Fedora 43 / GNOME 49)
  • A laptop with a Windows Hello compatible IR camera (e.g., ASUS Zenbook)
  • Internet connection (to download source code and face recognition models)
  • Approximately 10–15 minutes for the full build

Step 1: Run the Installer

chmod +x install-howdy.sh
sudo ./install-howdy.sh

You'll see an interactive menu:

══════════════════════════════════════════════════
  Howdy Facial Recognition — Fedora Installer
══════════════════════════════════════════════════

  1)  Full install        Build & configure howdy from source
  2)  Diagnose            Check installation health (7-point check)
  3)  Auto-fix            Fix common issues (dlib, SELinux, PAM, GDM)
  4)  Check PAM           Inspect PAM configuration files
  5)  Detect IR camera    Scan for Windows Hello IR sensor
  6)  Add face model      Register your face
  7)  Test                Test face recognition
  8)  Uninstall           Remove howdy completely
  9)  Help                Show command-line usage
  0)  Exit

Choose option 1 for a fresh installation. The installer will automatically:

  1. Install all build dependencies (compilers, libraries, Python packages)
  2. Detect your IR camera by scanning pixel formats
  3. Build howdy from source (produces the native pam_howdy.so PAM module)
  4. Download dlib face recognition neural network models (~27 MB)
  5. Configure the IR camera device and format
  6. Set up dlib so it's accessible system-wide
  7. Configure PAM files for GDM, sudo, su, and polkit
  8. Add the gdm user to the video group (required for lock screen access)
  9. Install an SELinux policy so GDM can access the camera
  10. Create an uninstaller

Step 2: Register Your Face

At the end of the installation, the script will ask if you want to add your face model. Say yes — this step is critical. Without a registered face model, howdy has nothing to compare against and facial authentication will not work.

Add your face model now? (Y/n): Y

When prompted:

  1. Position your face centered in front of the IR camera
  2. The IR LEDs near the camera should light up (a faint red/purple glow)
  3. Keep your face still for a moment while it captures
  4. Give the model a descriptive label (e.g., "glasses-on", "normal", "dark-room")

Step 3: Test

The installer will then offer to test recognition:

Test face recognition? (Y/n): Y

This opens a live camera view. You should see your face detected with a bounding box. Press q to exit the test.

Step 4: Test Lock Screen

  1. Open a safety TTY first: press Ctrl+Alt+F3, log in with your password
  2. Switch back to GNOME: Ctrl+Alt+F2
  3. Lock the screen: Super+L
  4. Look at the IR camera — it should unlock automatically
  5. If it doesn't, type your password (it always works as a fallback)

If the lock screen shows "Attempting facial authentication" but the IR LEDs don't light up, run:

sudo ./install-howdy.sh    # Choose option 3 (Auto-fix)
sudo systemctl restart gdm

⚠️ Always keep a TTY session open (Ctrl+Alt+F3) before restarting GDM — this kills your GNOME session.

Step 5: Test sudo

Open a new terminal and run:

sudo ls

You should see "Attempting facial authentication" followed by immediate authorization if your face is recognized. If it fails after the timeout (4 seconds), you'll get the normal password prompt.

Face Model Management

Why Face Models Matter

Face models are the core of howdy's recognition. Without at least one registered model, howdy cannot authenticate you and will always fall through to password entry. The quality and variety of your models directly affects recognition reliability.

Adding Multiple Models

For best results, register several face models under different conditions:

sudo howdy add          # Add with default label
sudo howdy add -U jane  # Add for a specific user

Recommended models to add:

Label Condition
normal Neutral face, good ambient light
glasses Wearing glasses
no-glasses Without glasses
dark Low ambient light (relies on IR LEDs)
angle-left Slight left head tilt
angle-right Slight right head tilt

The IR camera works best in its native infrared mode, so ambient lighting matters less than with a regular webcam. However, different head angles and accessories (glasses, hats) can affect recognition.

Listing Models

sudo howdy list

Shows all registered models with their ID numbers and labels.

Removing a Model

sudo howdy remove <id>

Remove a specific model by its ID (shown in howdy list).

Clearing All Models

sudo howdy clear

Removes all face models. You'll need to re-register before facial auth works again.

Day-to-Day Usage

Once configured, howdy works transparently. You don't need to do anything different — just look at your laptop when a password prompt appears.

What Happens During Authentication

  1. A password prompt appears (lock screen, sudo, GUI dialog)
  2. Howdy activates the IR camera (LEDs glow)
  3. It captures frames and compares against your registered models
  4. If matched within the timeout (4 seconds), you're authenticated
  5. If not matched, the normal password prompt appears

Temporarily Disabling

sudo howdy disable    # Turn off facial auth
sudo howdy enable     # Turn it back on

This is useful during screen sharing, presentations, or if you temporarily don't want the camera activating.

Editing Configuration

sudo howdy config

Opens the config file in your default editor. Key settings:

Setting Default Description
device_path /dev/video2 Path to your IR camera
device_format YUYV Pixel format (auto-detected)
certainty 3.5 Match threshold (1–10, lower = stricter)
timeout 4 Seconds to try before giving up
dark_threshold 60 Minimum brightness to attempt recognition
detection_notice true Show "Attempting facial authentication"

Tuning certainty: If howdy rejects you too often, increase this value. If it accepts strangers or photos, decrease it. The default of 3.5 is a good balance.

Troubleshooting

Quick Diagnostic

Run the built-in 8-point health check:

sudo ./install-howdy.sh    # Choose option 2 (Diagnose)

Or from the command line:

sudo ./install-howdy.sh --diagnose

This checks: howdy installation, dlib module, IR camera, GDM permissions, SELinux policy, PAM configuration, dlib face models data, and registered face models.

Auto-Fix

For most problems, the auto-fixer handles everything:

sudo ./install-howdy.sh    # Choose option 3 (Auto-fix)

This repairs: dlib symlinks, GDM video group membership, SELinux policies, PAM configuration, and missing dlib model data.

Common Problems

"Camera path is not configured correctly"

The configured video device doesn't work. Re-detect:

sudo ./install-howdy.sh    # Choose option 5 (Detect IR camera)

Then edit the config: sudo howdy config and update device_path.

sudo works but lock screen doesn't

Usually a GDM permissions or SELinux issue:

sudo ./install-howdy.sh    # Choose option 3 (Auto-fix)
sudo systemctl restart gdm

Remember: Open a safety TTY (Ctrl+Alt+F3) before restarting GDM.

"ModuleNotFoundError: No module named 'dlib'"

The dlib Python symlinks are broken. Fix:

sudo ./install-howdy.sh    # Choose option 3 (Auto-fix)

If that doesn't work, reinstall dlib:

sudo pip3 install --force-reinstall dlib --break-system-packages
sudo ./install-howdy.sh    # Choose option 3 (Auto-fix)

"Data files have not been downloaded"

The dlib face recognition neural network models are missing:

cd /usr/share/dlib-data
sudo ./install.sh

Or run option 3 (Auto-fix) which handles this automatically.

IR LEDs don't light up at all

  • Check the camera device exists: ls -la /dev/video*
  • Test with: ffplay /dev/video2 (replace with your device)
  • On ASUS Zenbooks, the IR device is often /dev/video2 not /dev/video0
  • Camera device numbers can change after a reboot — if this happens, re-run detection

Face recognized in test but not in sudo/lock screen

  • sudo: Check PAM with option 4 (Check PAM). Ensure pam_howdy.so is the first auth line.
  • Lock screen: Check that gdm is in the video group: groups gdm
  • Both: Check SELinux: sudo ausearch -m avc -ts recent | grep howdy

Recognition is too strict / too lenient

Edit certainty: sudo howdy config

  • Too strict (rejects you): increase certainty (e.g., 4.0 or 4.5)
  • Too lenient (accepts wrong faces): decrease certainty (e.g., 2.5 or 3.0)

Command-Line Reference

The installer supports both interactive menu and command-line flags:

sudo ./install-howdy.sh              # Interactive menu
sudo ./install-howdy.sh --install    # Full installation (skip menu)
sudo ./install-howdy.sh --diagnose   # 8-point health check
sudo ./install-howdy.sh --fix        # Auto-fix common issues
sudo ./install-howdy.sh --check-pam  # Inspect PAM files
sudo ./install-howdy.sh --detect-ir  # Scan for IR camera
sudo ./install-howdy.sh --add-face   # Register a face model
sudo ./install-howdy.sh --uninstall  # Remove howdy completely
sudo ./install-howdy.sh --help       # Show usage

Howdy Commands

sudo howdy add              # Register your face
sudo howdy add -U <user>    # Register for a specific user
sudo howdy list             # List face models
sudo howdy remove <id>      # Remove a face model
sudo howdy clear            # Remove all face models
sudo howdy test             # Live camera test
sudo howdy config           # Edit configuration
sudo howdy disable          # Temporarily disable
sudo howdy enable           # Re-enable
sudo howdy snapshot         # Capture a snapshot

Uninstalling

sudo ./install-howdy.sh    # Choose option 8 (Uninstall)

Or:

sudo howdy-uninstall

This removes: PAM configuration, SELinux policies, howdy binaries, config files, and dlib symlinks (but not the pip-installed dlib itself).

Security Notes

  • Howdy uses IR camera data, which is more resistant to photo-based spoofing than regular webcams, but it is not as secure as a strong password. It's a convenience feature, not a high-security replacement.
  • The sufficient PAM keyword means howdy can grant access on its own. If face recognition succeeds, no password is needed. Your password remains as a fallback.
  • Face model data is stored locally at /usr/lib64/security/howdy/models/. It is not transmitted anywhere.
  • The SELinux policy grants GDM access to video devices only — no broader permissions are added.

Files & Paths

Path Purpose
/etc/howdy/config.ini Howdy configuration
/usr/lib64/security/pam_howdy.so Native PAM module
/usr/lib64/security/howdy/ Howdy Python code & models
/usr/share/dlib-data/ Face recognition neural network models
/etc/pam.d/gdm-password GDM PAM config
/etc/pam.d/sudo sudo PAM config
/usr/local/bin/howdy-uninstall Uninstaller script
-- ms
-- ms
Measuring the internet...