✓ Stable v0.1.0

gardm

X11/Wayland display manager with graphical greeter

gardm is a display manager for the gardesk ecosystem that manages X11 server startup, user authentication via PAM, and session launching for both X11 and Wayland compositors. It features a customizable graphical greeter with garbg wallpaper integration, user avatar support, session selection, power management buttons, and accessibility options including high contrast mode and large text.

View on GitHub Download RPM

🎯 RPM Available

Installation

gardm is available as an RPM package for Fedora and RHEL-compatible distributions.

Using DNF (Recommended)

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

$sudo dnf install gardm

Building from Source

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

$cd gardesk/gardm

$cargo build --release

$sudo cp target/release/gardmd /usr/bin/

$sudo cp target/release/gardm-greeter /usr/bin/

Components

gardmd - Display manager daemon (runs as root)
gardm-greeter - Graphical login UI

Enable and Start

gardm runs as a systemd service. First disable any existing display manager, then enable gardm.

$sudo systemctl disable gdm sddm lightdm# disable other DMs

$sudo systemctl enable gardm

$sudo systemctl start gardm# or reboot

On next boot (or after starting), gardm will launch the X server and display the greeter.

PAM Configuration

gardm uses PAM for authentication. Create the PAM configuration file:

# /etc/pam.d/gardm
auth       include      system-auth
account    include      system-auth
password   include      system-auth
session    required     pam_loginuid.so
session    include      system-auth
-session   optional     pam_systemd.so

The pam_systemd.so module registers sessions with systemd-logind, enabling device access for Wayland compositors and proper session tracking.

systemd Service

The RPM package includes a systemd service file. For manual installation:

# /etc/systemd/system/gardm.service
[Unit]
Description=gar Display Manager
After=systemd-user-sessions.service getty@tty1.service plymouth-quit.service
Conflicts=getty@tty1.service

[Service]
Type=notify
ExecStart=/usr/bin/gardmd
Restart=always
RestartSec=5

[Install]
Alias=display-manager.service

CLI Options

Option	Type	Default	Description
`--no-x`	-	false	Use existing X server (for development)
`--display, -d`	-	:0 or auto	X display to use (e.g., :0)
`--vt`	-	auto-detect	VT to use
`--greeter`	-	from config	Greeter command override
`--test-mode`	-	false	Run IPC server only (no greeter process)

Configuration Files

gardm uses two configuration files:

/etc/gardm/config.toml - Daemon configuration
/etc/gardm/greeter.toml - Greeter visual configuration

Daemon Configuration

Full daemon configuration reference:

# /etc/gardm/config.toml

[general]
default_session = "gar"
greeter = "/usr/bin/gardm-greeter"
vt = 0              # 0 = auto-select
display = ":0"

[greeter]
blur_radius = 20
blur_brightness = 0.7
show_power_buttons = true
show_session_selector = true
use_garbg_wallpaper = true
fallback_wallpaper = "/usr/share/gardm/backgrounds/default.jpg"

[security]
allow_empty_password = false
lockout_attempts = 5
lockout_duration = 300

General Options

Option	Type	Default	Description
`default_session`	string	"gar"	Default session if user has not selected one
`greeter`	path	/usr/bin/gardm-greeter	Path to greeter executable
`vt`	u32	0	VT to use (0 = auto-select next available)
`display`	string	":0"	X11 display to use

Greeter Options (Daemon)

Option	Type	Default	Description
`blur_radius`	u32	20	Background blur radius in pixels
`blur_brightness`	f32	0.7	Background brightness (0.0-1.0, lower = darker)
`show_power_buttons`	bool	true	Show shutdown/reboot/suspend buttons
`show_session_selector`	bool	true	Show session selector dropdown
`use_garbg_wallpaper`	bool	true	Use garbg wallpaper as background
`fallback_wallpaper`	path	/usr/share/gardm/backgrounds/default.jpg	Fallback wallpaper path

Security Options

Option	Type	Default	Description
`allow_empty_password`	bool	false	Allow users with empty passwords to log in
`lockout_attempts`	u32	5	Lock account after N failed attempts (0 = disabled)
`lockout_duration`	u64	300	Lockout duration in seconds

Greeter Configuration

Full greeter visual configuration reference:

# /etc/gardm/greeter.toml

[visual]
blur_radius = 25.0
brightness = 0.6
corner_radius = 16.0
fade_duration_ms = 200

[garbg]
enabled = true
fallback = "/usr/share/gardm/backgrounds/default.jpg"

[theme]
panel_background = "rgba(25, 25, 25, 0.85)"
text_primary = "#ffffff"
text_error = "#ff4d4d"
accent = "#3380cc"
font_family = "Inter"
font_size_normal = 14

[accessibility]
high_contrast = false
large_text = false
reduce_motion = false

Visual Options

Option	Type	Default	Description
`blur_radius`	f32	25.0	Background blur radius
`brightness`	f32	0.6	Background brightness (0.0-1.0)
`corner_radius`	f64	16.0	Corner radius for UI elements
`fade_duration_ms`	u64	200	Fade-out duration when starting session

garbg Integration

Option	Type	Default	Description
`enabled`	bool	true	Use garbg wallpaper integration
`fallback`	string	/usr/share/gardm/backgrounds/default.jpg	Fallback wallpaper if garbg not configured

Theme Options

Option	Type	Default	Description
`panel_background`	color	rgba(0.1, 0.1, 0.1, 0.85)	Login panel background color
`background_overlay`	color	transparent	Overlay color on top of wallpaper
`text_primary`	color	#ffffff	Primary text color
`text_secondary`	color	#cccccc	Secondary text color
`text_error`	color	#ff4d4d	Error message color
`text_info`	color	#b3b3b3	Info message color
`accent`	color	#3380cc	Accent color (buttons, focused inputs)
`font_family`	string	"Sans"	Font family for UI text
`font_size_normal`	i32	14	Normal text size in points
`font_size_large`	i32	18	Large text size in points
`font_size_title`	i32	24	Title text size in points

Accessibility Options

Option	Type	Default	Description
`high_contrast`	bool	false	Enable high contrast mode with increased visibility
`large_text`	bool	false	Increase font sizes by 25%
`reduce_motion`	bool	false	Disable fade transitions for reduced motion

Color Formats

Colors can be specified in several formats:

Hex: #RRGGBB or #RRGGBBAA
RGB: rgb(255, 128, 64)
RGBA: rgba(255, 128, 64, 0.8)
Normalized: rgba(1.0, 0.5, 0.25, 0.8)

Overview

gardm is a display manager that handles the login process for desktop sessions. It manages X11 server startup, displays a graphical login screen (greeter), authenticates users via PAM, and launches their selected session.

Key Features

X11 server management with automatic VT selection
PAM authentication with proper session registration
Support for both X11 and Wayland sessions
Graphical greeter with customizable theming
garbg wallpaper integration
User list with avatar support
Session selector from installed .desktop files
Power management (shutdown, reboot, suspend)
Multi-monitor support via RandR
Accessibility options (high contrast, large text)
systemd integration with sd_notify

Architecture

gardm consists of two processes: the daemon (gardmd) and the greeter UI.

┌─────────────────────────────────────────────────────────┐
│                     gardmd (root)                        │
├─────────────────────────────────────────────────────────┤
│  ┌───────────────┐  ┌───────────────┐  ┌─────────────┐ │
│  │  X11 Server   │  │  IPC Server   │  │    PAM      │ │
│  │  Management   │  │ (Unix socket) │  │  Auth       │ │
│  └───────┬───────┘  └───────┬───────┘  └──────┬──────┘ │
│          │                  │                 │        │
│          ▼                  ▼                 ▼        │
│  ┌─────────────────────────────────────────────────────┐│
│  │              Main Event Loop                        ││
│  │    (greeter lifecycle, session management)          ││
│  └─────────────────────────────────────────────────────┘│
│                         │                               │
│         ┌───────────────┼───────────────┐              │
│         ▼               ▼               ▼              │
│  ┌───────────┐   ┌───────────┐   ┌───────────────┐    │
│  │  Greeter  │   │   User    │   │    Power      │    │
│  │  Process  │   │  Session  │   │  Management   │    │
│  └───────────┘   └───────────┘   └───────────────┘    │
└─────────────────────────────────────────────────────────┘

Daemon (gardmd)

The daemon runs as root and handles:

X11 Server - Starts Xorg on a VT, manages its lifecycle
IPC Server - Unix socket at /run/gardm.sock for greeter communication
PAM Authentication - Verifies credentials and opens sessions
Session Launching - Forks and execs user sessions with proper privileges
Power Management - Calls systemd-logind for shutdown/reboot/suspend
Signal Handling - Graceful shutdown on SIGTERM/SIGINT

Greeter UI

The greeter (gardm-greeter) is a graphical X11 application that:

Displays a blurred wallpaper background (from garbg or fallback)
Shows a user list with avatars
Provides username and password input fields
Offers a session selector dropdown
Shows power buttons (shutdown, reboot, suspend)
Communicates with gardmd via IPC

IPC Protocol

gardmd and the greeter communicate via JSON over a Unix socket.

Requests

Option	Type	Default	Description
`CreateSession`	-	-	Start authentication for a username
`Authenticate`	-	-	Provide password/response for authentication
`StartSession`	-	-	Start user session after successful auth (cmd, session_type, env)
`CancelSession`	-	-	Cancel current authentication attempt
`Shutdown`	-	-	Request system shutdown
`Reboot`	-	-	Request system reboot
`Suspend`	-	-	Request system suspend
`ListSessions`	-	-	Get available X11/Wayland sessions
`ListUsers`	-	-	Get users available for login

Responses

Option	Type	Default	Description
`Success`	-	-	Operation completed successfully
`AuthPrompt`	-	-	PAM requesting input (prompt, echo)
`AuthInfo`	-	-	PAM informational message
`AuthError`	-	-	Authentication failed
`Error`	-	-	General error with message
`Sessions`	-	-	List of available sessions with default
`Users`	-	-	List of available users

Greeter UI

The gardm-greeter provides a graphical login interface with theming support and accessibility options.

UI Elements

Background - Blurred wallpaper from garbg or fallback image
User List - Horizontal list of users with avatars, above login form
Login Form - Username and password fields centered on primary monitor
Session Selector - Dropdown below login form to choose session
Power Buttons - Shutdown, reboot, suspend in bottom-right corner

User Avatars

gardm looks for user avatars in these locations:

~/.face
~/.face.icon
/var/lib/AccountsService/icons/{username}

If no avatar is found, a default placeholder is shown.

Keyboard Navigation

Tab - Move between username and password fields
Enter - Submit login or move to password field
Up/Down - Switch between fields
Left/Right - Move cursor in text fields
Home/End - Move cursor to start/end of field
Backspace/Delete - Delete characters

garbg Integration

When enabled, the greeter uses garbg to resolve the current wallpaper. The wallpaper is then blurred and dimmed according to visual settings.

[garbg]
enabled = true
fallback = "/usr/share/backgrounds/default.jpg"

[visual]
blur_radius = 25.0
brightness = 0.6  # Dim to 60%

High Contrast Mode

For users with visual impairments, high contrast mode provides:

Black background with increased opacity
Yellow secondary text for better visibility
Bright cyan accent colors
Yellow input field borders
Slightly larger default fonts

[accessibility]
high_contrast = true

Multi-Monitor Support

The greeter uses RandR to detect connected monitors. The login form is centered on the primary monitor, while the background spans all monitors.

Session Discovery

gardm discovers available sessions from .desktop files in standard locations:

X11: /usr/share/xsessions/*.desktop
Wayland: /usr/share/wayland-sessions/*.desktop

Session .desktop Files

Session files follow the freedesktop.org Desktop Entry specification:

# /usr/share/xsessions/gar.desktop
[Desktop Entry]
Name=gar
Comment=gardesk window manager
Exec=gar-session.sh
Type=Application

The session selector shows the Name field to users, and executes the Exec command when selected.

Creating a gar Session

Example X11 session file for gar:

# /usr/share/xsessions/gar.desktop
[Desktop Entry]
Name=gar
Comment=gardesk window manager with compositor
Exec=gar-session.sh
Type=Application
DesktopNames=gar

And the session script:

#!/bin/bash
# /usr/local/bin/gar-session.sh

# Start compositor
garchomp &

# Start window manager
exec gar

Wayland Session Example

For Wayland compositors like Hyprland or Sway:

# /usr/share/wayland-sessions/hyprland.desktop
[Desktop Entry]
Name=Hyprland
Comment=Dynamic tiling Wayland compositor
Exec=Hyprland
Type=Application
DesktopNames=Hyprland

When a Wayland session is selected, gardm:

Stops the X server
Transfers TTY ownership to the user
Launches the compositor directly on the VT
Restarts X server when compositor exits

User Enumeration

gardm lists users from /etc/passwd that meet these criteria:

UID between 1000 and 60000 (regular users)
Shell is not /sbin/nologin or /bin/false

Full names are extracted from the GECOS field.

Default Session

The default session is configured in /etc/gardm/config.toml:

[general]
default_session = "gar"

This matches against the session ID (filename without .desktop extension).

Common Issues

Black screen after login

The session command may be failing. Check the session script and logs:

$journalctl -u gardm -b

$cat ~/.xsession-errors# if using startx-style script

"PAM authentication failed"

Ensure the PAM configuration is correct:

$cat /etc/pam.d/gardm

$pamtester gardm $USER authenticate# test PAM config

Wayland compositor fails to start

Wayland compositors need proper session registration with logind. Check:

pam_systemd.so in PAM config
User is in seat group
XDG_RUNTIME_DIR exists

$loginctl show-session $XDG_SESSION_ID# check session state

Greeter not appearing

Check if X server started and greeter logs:

$journalctl -u gardm -b | grep -i error

$ls -l /run/gardm.sock# IPC socket should exist

Power buttons not working

Power management uses logind. Ensure polkit allows it:

$busctl call org.freedesktop.login1 /org/freedesktop/login1 org.freedesktop.login1.Manager CanPowerOff

No sessions in selector

Check for .desktop files in session directories:

$ls -l /usr/share/xsessions/

$ls -l /usr/share/wayland-sessions/

Debugging

Enable Debug Logging

$RUST_LOG=debug gardmd --no-x# daemon with debug output

$RUST_LOG=debug gardm-greeter# greeter with debug output

Test Mode

Run the daemon in test mode (IPC only, no X11) for authentication testing:

$sudo gardmd --test-mode

Development Mode

Use an existing X server for development:

$sudo gardmd --no-x --display :0

Log Locations

systemd journal: journalctl -u gardm
X server log: /var/log/Xorg.0.log
User session errors: ~/.xsession-errors

Getting Help

If you encounter issues not covered here:

Check the GitHub Issues
Include journalctl output when reporting issues
Include your PAM configuration and session .desktop files

gardm

Installation

Using DNF (Recommended)

Building from Source

Components

Enable and Start

PAM Configuration

systemd Service

CLI Options

Configuration Files

Daemon Configuration

General Options

Greeter Options (Daemon)

Security Options

Greeter Configuration

Visual Options

garbg Integration

Theme Options

Accessibility Options

Color Formats

Overview

Key Features

Architecture

Daemon (gardmd)

Greeter UI

IPC Protocol

Requests

Responses

Authentication

PAM Integration

Session Lifecycle

Session Types

X11 Sessions

Wayland Sessions

Power Management

Greeter UI

UI Elements

User Avatars

Keyboard Navigation

garbg Integration

High Contrast Mode

Multi-Monitor Support

Session Discovery

Session .desktop Files

Creating a gar Session

Wayland Session Example

User Enumeration

Default Session

Common Issues

Black screen after login

"PAM authentication failed"

Wayland compositor fails to start

Greeter not appearing

Power buttons not working

No sessions in selector

Debugging

Enable Debug Logging

Test Mode

Development Mode

Log Locations

Getting Help