✓ Stable v0.3.2

garlock

Secure screen locker with PAM authentication and visual ring indicator

garlock is the screen locker component of the gardesk ecosystem. Inspired by swaylock, it features a circular ring indicator that provides visual feedback during password entry, blurred screenshot background, and secure PAM-based authentication. Supports daemon mode for integration with idle managers and gar keybindings, with protection against brute force attacks via configurable cooldown periods.

View on GitHub Download RPM

🎯 RPM Available

Features

✓
PAM Authentication
Secure password verification via Linux PAM subsystem
✓
Visual Ring Indicator
Circular ring with color states for input feedback
✓
Blurred Background
Screenshot capture with Gaussian blur and brightness adjustment
✓
Brute Force Protection
Configurable cooldown after failed authentication attempts
✓
Daemon Mode
Background service with IPC for idle manager integration
✓
Multi-Monitor Support
RandR detection with ring centered on primary monitor
✓
XKB Keyboard Handling
Proper keyboard layout support with Caps Lock detection
✓
Secure Input Handling
Password zeroization and memory protection

Installation

RPM (Fedora/RHEL)

terminal

$sudo dnf config-manager --add-repo https://repos.musicsian.com/musicsian.repo

$sudo dnf install garlock

From Source

terminal

$git clone https://github.com/espadon/gardesk

$cd gardesk/garlock

$cargo build --release

$sudo cp target/release/garlock /usr/local/bin/

PAM Configuration

garlock requires a PAM configuration file at /etc/pam.d/garlock. The RPM package installs this automatically. For manual installation:

# /etc/pam.d/garlock
auth       include      system-auth
account    include      system-auth
password   include      system-auth
session    include      system-auth

Quick Start

Lock your screen immediately:

terminal

$garlock

INFO garlock 0.3.2 starting INFO Capturing screenshot... INFO Creating locker window... INFO Entering event loop

Using with gar Keybindings

Add a lock keybinding to your gar configuration:

-- ~/.config/gar/init.lua
gar.keybinds = (
  -- Lock screen with Super+L
  ( mods = ( "Mod4" ), key = "l", action = "spawn", args = "garlock" ),

  -- Lock screen with Super+Escape (alternative)
  ( mods = ( "Mod4" ), key = "Escape", action = "spawn", args = "garlock" ),
)

Daemon Mode

Run garlock as a daemon for integration with idle managers (like swayidle):

terminal

$garlock daemon

INFO garlock 0.3.2 starting INFO Running in daemon mode INFO Daemon ready, waiting for commands

Lock via Daemon

terminal

$garlock lock

INFO Sending lock command to daemon INFO Daemon response: "Locking screen"

systemd Service

# ~/.config/systemd/user/garlock.service
[Unit]
Description=garlock screen locker daemon
PartOf=gar-session.target
After=gar.service

[Service]
ExecStart=/usr/bin/garlock daemon
Restart=on-failure

[Install]
WantedBy=gar-session.target

CLI Commands

terminal

$garlock # Lock immediately (direct or via daemon)

$garlock lock # Lock via daemon, fallback to direct

$garlock daemon # Start daemon mode

$garlock status # Query lock state (daemon required)

$garlock shutdown # Stop daemon gracefully

Options

terminal

$garlock --help

garlock - Screen locker for the gar desktop suite Usage: garlock [OPTIONS] [COMMAND] Commands: daemon Run in daemon mode lock Lock the screen status Query lock state shutdown Stop daemon Options: -c, --config <PATH> Config file path -d, --debug Enable debug logging -h, --help Print help -V, --version Print version

File Locations

Config: ~/.config/garlock/config.toml
PAM config: /etc/pam.d/garlock
Socket: $XDG_RUNTIME_DIR/garlock.sock
Logs: journalctl --user -u garlock.service

Configuration Reference

garlock uses TOML configuration at ~/.config/garlock/config.toml. If the file doesn't exist, garlock creates one with documented defaults on first run.

General Options

Option	Type	Default	Description
`grace_period`	-	0	Seconds before password required (0 to disable)
`pam_service`	-	"garlock"	PAM service name (must match /etc/pam.d/)
`max_attempts`	-	3	Failed attempts before cooldown
`cooldown_seconds`	-	5	Cooldown duration in seconds

Background Options

Option	Type	Default	Description
`blur_radius`	-	25.0	Gaussian blur radius (0 to disable)
`brightness`	-	0.6	Brightness adjustment (0.0-1.0)
`fallback_color`	-	"#1a1a2e"	Solid color if screenshot fails (hex)

Ring Geometry

Option	Type	Default	Description
`radius_outer`	-	90.0	Outer ring radius in pixels
`radius_inner`	-	75.0	Inner ring radius in pixels
`line_width`	-	6.0	Ring stroke width in pixels

Ring Colors

Colors use hex format with optional alpha: #RRGGBB or #RRGGBBAA

Option	Type	Default	Description
`color_idle`	-	"#1e90ffcc"	Ring color when waiting for input
`color_typing`	-	"#00ff00cc"	Ring color when receiving input
`color_verifying`	-	"#ffa500cc"	Ring color during PAM auth
`color_wrong`	-	"#ff0000cc"	Ring color after failed auth
`color_clear`	-	"#ffff00cc"	Ring color on backspace/clear
`color_inside`	-	"#00000088"	Inner circle fill color
`color_ring_bg`	-	"#00000055"	Ring track background color

Indicator Options

Option	Type	Default	Description
`show_caps_lock`	-	true	Show Caps Lock warning
`caps_lock_text`	-	"Caps Lock"	Text for Caps Lock indicator
`show_failed_attempts`	-	true	Show failed attempt count
`show_time`	-	false	Display current time on lock screen
`time_format`	-	"%H:%M"	strftime format for time display

Font Options

Option	Type	Default	Description
`family`	-	"Sans"	Font family for text elements
`size`	-	14	Font size in points

Minimal Configuration

# ~/.config/garlock/config.toml

[general]
max_attempts = 5
cooldown_seconds = 10

[background]
blur_radius = 30.0
brightness = 0.5

[ring]
color_idle = "#89b4facc"
color_typing = "#a6e3a1cc"

Time Display Formats

The time_format option uses strftime patterns:

# Common formats:
"%H:%M"       # 24-hour (14:30)
"%H:%M:%S"    # 24-hour with seconds (14:30:45)
"%I:%M %p"    # 12-hour with AM/PM (02:30 PM)
"%l:%M %p"    # 12-hour no leading zero (2:30 PM)
"%a %H:%M"    # Day + time (Mon 14:30)
"%A, %B %d"   # Full date (Monday, January 16)

Complete Configuration Example

# ~/.config/garlock/config.toml

[general]
# Grace period (0 = always require password)
grace_period = 0

# PAM service name
pam_service = "garlock"

# Brute force protection
max_attempts = 3
cooldown_seconds = 5

[background]
# Blur effect (higher = more blur)
blur_radius = 25.0

# Darken the background (0.0 = black, 1.0 = original)
brightness = 0.6

# Fallback if screenshot fails
fallback_color = "#1a1a2e"

[ring]
# Ring dimensions
radius_outer = 90.0
radius_inner = 75.0
line_width = 6.0

# State colors (Catppuccin Mocha palette)
color_idle = "#89b4facc"       # Blue - waiting
color_typing = "#a6e3a1cc"     # Green - typing
color_verifying = "#f9e2afcc"  # Yellow - verifying
color_wrong = "#f38ba8cc"      # Red - failed
color_clear = "#cba6f7cc"      # Purple - clearing

# Background colors
color_inside = "#1e1e2e88"     # Dark center
color_ring_bg = "#31324455"    # Ring track

[indicator]
# Caps Lock warning
show_caps_lock = true
caps_lock_text = "Caps Lock"

# Failed attempts counter
show_failed_attempts = true

# Time display
show_time = true
time_format = "%H:%M"

[font]
family = "JetBrainsMono Nerd Font"
size = 14

PAM Service Configuration

The pam_service option must match a file in /etc/pam.d/. The default "garlock" service includes system-auth for standard password verification:

# /etc/pam.d/garlock
# Standard system authentication
auth       include      system-auth
account    include      system-auth
password   include      system-auth
session    include      system-auth

# Alternative: Use login service
# auth       include      login

Overview

garlock is a screen locker for the gardesk desktop environment, inspired by swaylock. It captures a screenshot of the current desktop, applies blur and darkening effects, then displays a fullscreen window with a circular ring indicator. Users enter their password, which is verified against Linux PAM, and successful authentication unlocks the screen.

The ring indicator provides visual feedback for the current state: idle (waiting), typing (receiving input), verifying (checking PAM), wrong (failed auth), and clear (backspace pressed). This feedback helps users understand what's happening without revealing password information.

Architecture

Lock Flow

When garlock is invoked, it follows this sequence:

Screenshot Capture: Captures the current screen via X11 MIT-SHM
Background Processing: Applies Gaussian blur and brightness adjustment
Window Creation: Creates fullscreen X11 window with override_redirect
Input Grabs: Grabs keyboard and pointer to capture all input
Ring Initialization: Sets up Cairo-based ring renderer
Event Loop: Processes keyboard input and renders frames
Authentication: On Enter, spawns async PAM authentication thread
Unlock: On success, releases grabs and destroys window

Daemon Mode

In daemon mode, garlock listens on a Unix socket for lock commands:

// Daemon event loop
while running (
    if let Some((cmd, client)) = server.poll() (
        match cmd (
            Command::Lock => (
                // Send response before blocking
                client.respond(Response::ok_with_message("Locking"));
                // Run lock screen (blocks until unlocked)
                run_lock(config);
            ),
            Command::QueryState => (
                client.respond(Response::state(is_locked, attempts, cooldown));
            ),
            Command::Shutdown => (
                running = false;
                client.respond(Response::ok());
            ),
        )
    )
    sleep(10ms);
)

State Machine

garlock uses dual state machines following swaylock patterns:

AuthState: Tracks authentication progress (Idle, Validating, Invalid)
InputState: Tracks visual feedback (Idle, Letter, Backspace, Clear, Neutral)

These combine to determine the ring color. AuthState takes priority for Verifying and Wrong states, while InputState controls Typing and Clear feedback.

Event Loop

The main event loop processes X11 events and manages rendering:

loop (
    match locker.poll_for_event()? (
        Some(Event::KeyPress(key)) => (
            match keyboard.process_key(key.detail, true) (
                KeyResult::Char(c) => (
                    password.push(c);
                    state.on_input(InputState::Letter);
                    ring.advance_highlight();
                ),
                KeyResult::Backspace => (
                    password.pop();
                    ring.retreat_highlight();
                ),
                KeyResult::Enter => (
                    if !state.is_in_cooldown() (
                        pending_auth = authenticate_async(user, password);
                    )
                ),
                // ... other key handling
            )
        ),
        None => (
            // Check pending auth result
            if let Some(result) = pending_auth.try_recv() (
                match result (
                    AuthResult::Success => break,  // Unlock!
                    AuthResult::Failure => state.on_auth_failure(),
                )
            )
            // Update timers and redraw if needed
            if needs_redraw ( render_frame() )
        ),
    )
)

Security

PAM Authentication

garlock uses Linux PAM (Pluggable Authentication Modules) for password verification:

Authentication runs in a background thread to keep UI responsive
Uses the pam-sys crate for low-level PAM bindings
Only authenticates - does not open a new session (one already exists)
PAM service name is configurable (default: "garlock")

// Background thread authentication
fn authenticate_async(username: String, password: String) -> PendingAuth (
    let (tx, rx) = mpsc::channel();
    thread::spawn(move || (
        let result = pam_authenticate(&username, &password);
        tx.send(result);
    ));
    PendingAuth ( receiver: rx )
)

Secure Input

Password handling includes several security measures:

Zeroization: Password buffer is zeroed on drop (zeroize crate)
No echo: Characters are never displayed, only ring segments light up
Length hiding: Ring has 12 segments that cycle, hiding true password length
Immediate clear: Password cleared after authentication attempt

Cooldown Protection

After max_attempts failed authentications, garlock enters a cooldown period:

During cooldown, Enter key is ignored (no authentication attempts)
Cooldown timer is displayed on screen
After cooldown expires, attempt counter resets to zero
Configurable via max_attempts and cooldown_seconds

Input Grabs

garlock grabs both keyboard and pointer input:

Keyboard grab prevents other applications from receiving input
Pointer grab prevents clicking through to other windows
override_redirect window bypasses window manager decoration
Input grabs are released only on successful authentication

gar Integration

Keybindings

Bind garlock to keys in gar's init.lua for quick locking:

gar.keybinds = (
  -- Lock with Super+L (common convention)
  ( mods = ( "Mod4" ), key = "l", action = "spawn", args = "garlock" ),

  -- Lock with Super+Escape
  ( mods = ( "Mod4" ), key = "Escape", action = "spawn", args = "garlock lock" ),
)

Session Management

garlock integrates with gar's systemd session:

garlock.service is part of gar-session.target
Daemon starts when gar session starts
Clean shutdown when session ends

Idle Locking

Integrate with swayidle or similar for automatic screen locking:

# Lock after 5 minutes of inactivity
swayidle -w \
    timeout 300 'garlock lock' \
    timeout 600 'systemctl suspend' \
    before-sleep 'garlock lock'

Multi-Monitor

RandR Detection

garlock queries monitor configuration via X11 RandR:

Detects all connected monitors and their positions
Identifies primary monitor for ring placement
Single fullscreen window spans all monitors
Background screenshot covers entire desktop

Ring Placement

The ring indicator is centered on the primary monitor:

let (ring_cx, ring_cy) = match locker.get_monitors() (
    Ok(monitors) => (
        if let Some(primary) = monitors.primary() (
            primary.center()  // Center of primary monitor
        ) else (
            (screen_width / 2, screen_height / 2)  // Fallback to screen center
        )
    ),
    Err(_) => (screen_width / 2, screen_height / 2),
)

Ring Indicator

The circular ring indicator provides visual feedback without revealing password information. The ring changes color based on the current state and lights up segments as keys are pressed.

Ring States

Option	Type	Default	Description
`Idle`	-	color_idle	Waiting for input - default blue color
`Typing`	-	color_typing	Receiving password characters - green color
`Verifying`	-	color_verifying	Checking password with PAM - orange color
`Wrong`	-	color_wrong	Authentication failed - red color (1.5s timeout)
`Clear`	-	color_clear	Backspace or Ctrl+U pressed - yellow color

Segment Highlighting

The ring is divided into 12 segments. Each keystroke advances to the next segment, providing visual feedback without revealing password length:

Character typed: Advances to next segment (wraps at 12)
Backspace: Retreats to previous segment (clears at 0)
Ctrl+U: Clears all segments
Enter: Segments clear, ring transitions to Verifying

Since the ring wraps at 12 segments, an attacker cannot determine whether the password is 5, 17, or 29 characters long.

Background Processing

The lock screen background is created from a screenshot:

Capture: Screenshot via X11 MIT-SHM extension (fast shared memory)
Blur: Gaussian blur with configurable radius (default 25px)
Darken: Brightness adjustment (default 60% of original)
Fallback: Solid color if screenshot fails

Blur Examples

# No blur (clear but distracting)
blur_radius = 0

# Light blur (some privacy)
blur_radius = 15.0

# Medium blur (default - good balance)
blur_radius = 25.0

# Heavy blur (maximum privacy)
blur_radius = 50.0

Overlay Elements

Additional UI elements displayed around the ring:

Time Display

When show_time is enabled, the current time appears above the ring:

[indicator]
show_time = true
time_format = "%H:%M"  # 24-hour format

Caps Lock Warning

When Caps Lock is active during typing, a warning appears below the ring:

[indicator]
show_caps_lock = true
caps_lock_text = "Caps Lock"

Failed Attempts Counter

After failed authentication attempts, a counter appears:

[indicator]
show_failed_attempts = true
# Displays: "2 failed attempts" after 2 failures

Cooldown Timer

During cooldown after max_attempts failures:

# Displays: "Try again in 5s"
# Countdown updates every second

Color Schemes

Default Theme

[ring]
color_idle = "#1e90ffcc"       # DodgerBlue
color_typing = "#00ff00cc"     # Lime
color_verifying = "#ffa500cc"  # Orange
color_wrong = "#ff0000cc"      # Red
color_clear = "#ffff00cc"      # Yellow
color_inside = "#00000088"     # Black (translucent)
color_ring_bg = "#00000055"    # Black (more translucent)

Catppuccin Mocha Theme

[ring]
color_idle = "#89b4facc"       # Blue
color_typing = "#a6e3a1cc"     # Green
color_verifying = "#f9e2afcc"  # Yellow
color_wrong = "#f38ba8cc"      # Red
color_clear = "#cba6f7cc"      # Mauve
color_inside = "#1e1e2e88"     # Base
color_ring_bg = "#31324455"    # Surface0

Nord Theme

[ring]
color_idle = "#88c0d0cc"       # Frost
color_typing = "#a3be8ccc"     # Aurora Green
color_verifying = "#ebcb8bcc"  # Aurora Yellow
color_wrong = "#bf616acc"      # Aurora Red
color_clear = "#b48eadcc"      # Aurora Purple
color_inside = "#2e344088"     # Polar Night
color_ring_bg = "#3b425255"    # Polar Night

Daemon IPC

In daemon mode, garlock listens on a Unix socket for commands. This enables integration with idle managers and external scripts.

Socket Location

$XDG_RUNTIME_DIR/garlock.sock
# Typically: /run/user/1000/garlock.sock

Commands

Option	Type	Default	Description
`lock`	-	-	Lock the screen immediately
`query-state`	-	-	Get current lock state as JSON
`shutdown`	-	-	Gracefully stop the daemon

Responses

Option	Type	Default	Description
`ok`	-	-	Command executed successfully (optional message field)
`state`	-	-	Current state with locked, failed_attempts, in_cooldown fields
`error`	-	-	Error occurred (message field contains details)

Events

The daemon broadcasts events to subscribed clients:

Option	Type	Default	Description
`locked`	-	-	Screen was locked
`unlocked`	-	-	Screen was unlocked (successful auth)
`auth-failed`	-	-	Authentication attempt failed (includes attempt count)
`cooldown-started`	-	-	Cooldown activated (includes duration in seconds)
`shutdown`	-	-	Daemon is shutting down

Protocol Format

Messages are JSON objects with kebab-case tag fields. Each message is newline-terminated.

Command Examples

// Lock command
("command": "lock")

// Query state command
("command": "query-state")

// Shutdown command
("command": "shutdown")

Response Examples

// Success response
("status": "ok", "message": "Locking screen")

// State response
(
  "status": "state",
  "locked": true,
  "failed_attempts": 2,
  "in_cooldown": false
)

// Error response
("status": "error", "message": "Screen is already locked")

Event Examples

// Locked event
("event": "locked")

// Unlocked event
("event": "unlocked")

// Auth failed event
("event": "auth-failed", "attempt": 2)

// Cooldown started event
("event": "cooldown-started", "seconds": 5)

// Shutdown event
("event": "shutdown")

CLI Usage

terminal

$garlock status

( "status": "state", "locked": false, "failed_attempts": null, "in_cooldown": null )

$garlock lock

( "status": "ok", "message": "Locking screen" )

$garlock shutdown

( "status": "ok", "message": "Shutting down" )

Raw Socket Example

terminal

$echo '{"command": "query-state"}' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/garlock.sock

{"status":"state","locked":false}

Python Example

#!/usr/bin/env python3
import socket
import json
import os

sock_path = os.path.join(os.environ.get('XDG_RUNTIME_DIR', '/tmp'), 'garlock.sock')

def send_command(cmd):
    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock:
        sock.connect(sock_path)
        sock.sendall((json.dumps(cmd) + '\n').encode())
        response = sock.recv(4096).decode()
        return json.loads(response)

# Query state
status = send_command(("command": "query-state"))
print("Locked:", status.get("locked", False))

# Lock screen
result = send_command(("command": "lock"))
print("Response:", result.get("message", result.get("status")))

Troubleshooting

PAM Authentication Fails

Check that the PAM configuration exists and is correct:

terminal

$cat /etc/pam.d/garlock

auth include system-auth account include system-auth ...

$# If missing, create it:

$sudo tee /etc/pam.d/garlock << EOF auth include system-auth account include system-auth password include system-auth session include system-auth EOF

Check PAM configuration is valid

terminal

$pamtester garlock $USER authenticate

Password: ******** pamtester: successfully authenticated

Screenshot Capture Fails

If screenshot capture fails, garlock uses a solid fallback color:

terminal

$garlock --debug

DEBUG Capturing screenshot... ERROR Failed to capture screenshot: MIT-SHM not available INFO Using fallback color #1a1a2e

$# Check MIT-SHM extension:

$xdpyinfo | grep MIT-SHM

Input Grab Fails

If another application has grabbed input, garlock cannot lock:

terminal

$garlock --debug

ERROR Failed to grab keyboard: AlreadyGrabbed

$# Release stuck grabs:

$xdotool keyup --clearmodifiers

Daemon Connection Failed

If the daemon is not running, garlock falls back to direct lock:

terminal

$garlock lock

INFO No daemon running, locking directly

$# Start daemon first:

$garlock daemon &

$garlock lock

INFO Sending lock command to daemon

Check Daemon Status

terminal

$garlock status

( "status": "state", "locked": false )

$# If daemon not running:

$garlock status

Error: Failed to connect to socket

Caps Lock Not Detected

Caps Lock detection uses XKB. Verify XKB is working:

terminal

$xset q | grep Caps

00: Caps Lock: off 01: Num Lock: on

$# If XKB indicator doesn't update, check keyboard layout:

$setxkbmap -query

Multi-Monitor Ring Position

Ring should be centered on primary monitor. Check monitor detection:

terminal

$garlock --debug

INFO Ring centered on primary monitor DP-1 at (960, 540)

$# If no primary monitor:

$xrandr --output DP-1 --primary

Debug Logging

terminal

$garlock --debug

DEBUG garlock 0.3.2 starting DEBUG Configuration loaded DEBUG Capturing screenshot... DEBUG Screenshot captured: 1920x1080 DEBUG Background processed: blur=25.0, brightness=0.6 DEBUG Creating locker window... DEBUG Initializing keyboard handler... DEBUG Initializing ring indicator... DEBUG Initial render completed

$# For even more detail:

$RUST_LOG=trace garlock

Development Mode

For testing, build with dev feature to allow Escape key to exit:

terminal

$cargo build --release --features dev

$./target/release/garlock

INFO Entering event loop (dev mode: press Escape to exit)

Known Limitations

X11 only - Wayland is not supported
Single PAM service - no per-user or per-session service switching
No fingerprint/biometric authentication (PAM password only)
Grace period not yet implemented (always requires password)

Getting Help

GitHub Issues: github.com/espadon/gardesk/issues
Check PAM logs: journalctl -e | grep pam
Debug logging: garlock --debug
Trace logging: RUST_LOG=trace garlock