Linux Fingerprint Reader Management Tool

A user-friendly Bash utility to easily manage fingerprint authentication on Ubuntu and Debian-based Linux systems.

This tool is designed to simplify checking hardware status, enrolling fingerprints, testing scanner verification, and safely managing PAM (Pluggable Authentication Modules) configurations. It is particularly optimized for EgisTec and LighTuning devices (such as USB ID 1c7a:0570 commonly found in Acer Swift series laptops) which require specific troubleshooting steps under Linux.

---

Compatibility & Caveats

• 💻 Supported Operating Systems:
  • Debian / Ubuntu and derivatives (Linux Mint, Pop!_OS, Zorin OS, etc.): Fully supported out-of-the-box, including automated PAM enablement/disablement.
  • Other Distributions (Arch Linux, Fedora, RHEL, openSUSE, etc.): Commands like status, enroll, test, and clear will work. However, enable and disable commands will not work because these distributions do not use Debian's pam-auth-update manager. PAM must be configured manually or via authselect on those systems.
• 🔌 Supported Hardware:
  • Works with any fingerprint scanner supported by the upstream libfprint project (including models from Elan, Synaptics, Goodix, Broadcom, and EgisTec).

---

Features

• 🔍 Status Diagnostics: Check if your fingerprint hardware is recognized, if the fprintd system service is running, which fingers are enrolled, and if PAM integration is enabled.
• ✋ Interactive Enrollment: Choose which finger to enroll with guided terminal prompts.
• 🧪 Verification Test: Test the reader to see if it successfully matches your print without triggering lockouts.
• 🔐 PAM Configuration Integration: Safe, automated enablement/disablement of fingerprint login for sudo commands and lock screens.
• ⚡ Attempts Optimization: Configures the system to give you 3 attempts before falling back to your password prompt (overriding Ubuntu's default of 1).

---

Installation & Setup

1. Clone the repository:

   git clone https://github.com/<your-username>/<repo-name>.git
   cd <repo-name>

2. Make the script executable:

   chmod +x fingerprint-tool.sh

3. Check device status:

   ./fingerprint-tool.sh status

---

Usage Guide

Run the script with one of the following commands:

./fingerprint-tool.sh [command]

Commands:

Command	Description
status	Displays device detection, enrolled fingerprints, and PAM status.
enroll	Initiates fingerprint enrollment for a selected finger.
test	Tests the scanner to verify if your swipe matches the enrolled fingerprint.
enable	Enables fingerprint unlock system-wide (requires sudo).
disable	Disables fingerprint unlock system-wide (requires sudo).
clear	Deletes all enrolled fingerprints for the current user.
help	Shows the help menu.

---

Troubleshooting & Tips

1. Device disabled to prevent overheating

Fingerprint sensors generate significant heat when scanning repeatedly. If the sensor disconnects during enrollment:

• Wait 2–3 minutes for the physical reader to cool down.
• Wipe the scanner with a clean, dry microfiber cloth.
• Pace your swipes: When enrolling, pause 2 to 3 seconds between each touch/swipe.

2. Failed to detect minutiae: No minutiae found

• Some fingerprint readers (like the 1c7a:0570) are registered as swipe devices in Linux even if they look like touch sensors. Ensure you are doing a slow, firm downward swipe (from joint to tip) rather than a simple tap.

3. Device was already claimed

If the lock screen does not unlock but the terminal test works, it means another process is holding a claim on the scanner:

• Ensure the GNOME Settings (Users/Fingerprint panel) app is closed.
• Close any terminal running a test/enrollment script.
• If needed, reboot the system to force-release all USB claims.

---

License

This project is open-source and available under the MIT License.