Beta

gardm

Display Manager

A system-level display manager with graphical greeter for the gar desktop environment. gardm manages X server lifecycle, user authentication via PAM, session launching, and VT allocation. Features a modern Cairo/Pango-rendered login UI with user list, session selection, power management, and garbg wallpaper integration.

View on GitHub Install

System-Level Component

gardm is a system-level display manager that runs as root and replaces your existing display manager (GDM, SDDM, LightDM). Test in a VM or ensure you have TTY access (Ctrl+Alt+F2) before deployment.

Features

Two-process architecture (daemon + greeter)
PAM authentication with state machine
X11 session support (keeps X server running)
Wayland session support (direct VT access)
X server lifecycle management (Xorg spawning)
VT allocation and switching (ioctl-based)
User session forking with privilege dropping
systemd-logind session registration
Unix socket IPC (JSON protocol)
Power management (shutdown, reboot, suspend)
Session discovery from .desktop files
User enumeration with avatar support
garbg wallpaper integration with blur
Accessibility options (high contrast, large text)
Fade-out transition on login
systemd service integration (Type=notify)

Architecture

gardmd (Daemon)

Runs as root, manages X server, spawns greeter, handles PAM auth, forks user sessions. IPC server at /run/gardm.sock.

gardm-greeter (UI)

Graphical login interface with Cairo/Pango rendering. User list, session selector, power buttons. Connects to daemon via IPC.

Process Flow

systemd → gardmd (starts X server on VT) → spawns gardm-greeter

greeter → IPC → gardmd (CreateSession, Authenticate, StartSession)

gardmd → fork/exec → user session (PAM open_session, drop privileges)

session ends → gardmd kills greeter → restart loop

Installation & Setup

Critical Warning

gardm replaces your system display manager. Test in a VM first or ensure you have TTY backup access. If installation fails, you can recover from TTY (Ctrl+Alt+F2).

1. Install gardm

Use the unified installer which handles dependencies, builds, and system integration:

terminal

$ curl -fsSL https://gar.musicsian.com/install.sh | bash -s -- --component=gardm # Install via script (recommended)

$ cd ~/.local/src/gardesk/gardm && cargo build --release -p gardmd -p gardm-greeter # Or build from source

2. Disable Current Display Manager

Disable any existing display manager before enabling gardm:

terminal

$ sudo systemctl disable gdm # GNOME Display Manager

$ sudo systemctl disable sddm # Simple Desktop Display Manager

$ sudo systemctl disable lightdm # LightDM

$ sudo systemctl status display-manager.service # Check current DM

3. Enable gardm Service

Enable gardm as the system display manager:

terminal

$ sudo systemctl enable gardm # Enable gardm service

$ sudo systemctl start gardm # Start now (will replace current X session)

4. Configure (Optional)

Create system configuration:

terminal

$ sudo mkdir -p /etc/gardm # Create config directory

$ sudo $EDITOR /etc/gardm/config.toml # Edit daemon config

$ sudo $EDITOR /etc/gardm/greeter.toml # Edit greeter config

5. Reboot

Reboot to start gardm at boot:

terminal

$ sudo reboot # Reboot system

CLI Flags

gardmd accepts several flags for testing and debugging:

Flag	Description
--no-x	Skip X server startup (use existing DISPLAY)
-d, --display DISPLAY	X11 display to use (default: :0)
--vt N	VT number to use (default: auto-detect)
--greeter PATH	Path to greeter binary
--test-mode	Test mode (skip VT switching and X server)

Recovery Procedure

If gardm fails to start, recover from TTY:

1. Press Ctrl+Alt+F2 to switch to TTY2

2. Login with your username and password

3. Run: sudo systemctl disable gardm

4. Run: sudo systemctl enable gdm (or your previous DM)

5. Run: sudo reboot

Configuration Reference

gardm uses two TOML configuration files: daemon config at /etc/gardm/config.toml and greeter config at /etc/gardm/greeter.toml.

Daemon Configuration

/etc/gardm/config.toml

# ═══════════════════════════════════════════
# gardm daemon configuration
# Display manager daemon settings
# ═══════════════════════════════════════════

[general]
# Default session to launch (without .desktop extension)
# This is used if no session is explicitly selected
default_session = "gar"

# Path to greeter executable
greeter = "/usr/bin/gardm-greeter"

# VT to use (0 = auto-select using VT_OPENQRY ioctl)
vt = 0

# X11 display number
display = ":0"

[greeter]
# Blur radius for background screenshot
blur_radius = 20

# Background brightness (0.0 = black, 1.0 = original)
blur_brightness = 0.7

# Show power buttons (shutdown, reboot, suspend)
show_power_buttons = true

# Show session selector dropdown
show_session_selector = true

# Use garbg's current wallpaper as background
use_garbg_wallpaper = true

# Fallback wallpaper path if garbg not available
fallback_wallpaper = "/usr/share/gardm/backgrounds/default.jpg"

[security]
# Allow empty passwords (NOT recommended)
allow_empty_password = false

# Lock greeter after N failed attempts (0 = disabled)
lockout_attempts = 5

# Lockout duration in seconds
lockout_duration = 300

Greeter Configuration

/etc/gardm/greeter.toml

# ═══════════════════════════════════════════
# gardm greeter configuration
# Graphical login UI settings
# ═══════════════════════════════════════════

[visual]
# Blur radius for background (0 = no blur)
blur_radius = 25.0

# Background brightness (0.0-1.0, lower = darker)
brightness = 0.6

# Corner radius for UI elements
corner_radius = 16.0

# Fade-out duration in milliseconds when starting session
fade_duration_ms = 200

[garbg]
# Whether to use garbg wallpaper as background
enabled = true

# Fallback wallpaper if garbg not available
fallback = "/usr/share/gardm/backgrounds/default.jpg"

[theme]
# Font family
font_family = "Sans"

# Normal text size
font_size_normal = 14

# Large text size
font_size_large = 16

# Primary color (hex format)
color_primary = "#61afef"

# Background color
color_background = "#1e2127"

# Text color
color_text = "#abb2bf"

# Error color
color_error = "#e06c75"

[accessibility]
# High contrast mode (increases contrast for visibility)
high_contrast = false

# Large text mode (increases font sizes)
large_text = false

# Reduce motion (disables fade transitions)
reduce_motion = false

PAM Configuration

The installer creates /etc/pam.d/gardm automatically:

/etc/pam.d/gardm

#%PAM-1.0
# gardm display manager PAM configuration

# Authentication
auth        required      pam_unix.so

# Account management
account     required      pam_unix.so

# Password management
password    required      pam_unix.so

# Session management - pam_systemd registers with logind
-session    optional      pam_systemd.so
session     required      pam_unix.so

Overview

gardm is a system-level display manager for X11 and Wayland sessions. It consists of two processes: gardmd (daemon running as root) and gardm-greeter (graphical UI). Communication happens via JSON over Unix socket.

Key Components

gardmd: Daemon managing X server, VTs, authentication, and sessions
gardm-greeter: Graphical login UI with Cairo/Pango rendering
gardm-ipc: Shared IPC protocol library
PAM: Authentication via pam crate
systemd-logind: Session registration and power management

File Locations

/usr/bin/gardmd	Display manager daemon
/usr/bin/gardm-greeter	Graphical greeter
/etc/gardm/config.toml	Daemon configuration
/etc/gardm/greeter.toml	Greeter configuration
/etc/pam.d/gardm	PAM service configuration
/run/gardm.sock	IPC Unix socket
/usr/lib/systemd/system/gardm.service	systemd service file

IPC Protocol

Communication between greeter and daemon uses JSON messages over Unix socket at /run/gardm.sock.

Requests (Greeter → Daemon)

// Create auth session for user
{"type": "create_session", "username": "alice"}

// Provide password
{"type": "authenticate", "response": "secret123"}

// Start user session
{
  "type": "start_session",
  "cmd": ["gar-session.sh"],
  "session_type": "x11",
  "env": []
}

// Cancel authentication
{"type": "cancel_session"}

// Power actions
{"type": "shutdown"}
{"type": "reboot"}
{"type": "suspend"}

// List available sessions
{"type": "list_sessions"}

// List available users
{"type": "list_users"}

Responses (Daemon → Greeter)

// Success
{"type": "success"}

// PAM prompt
{"type": "auth_prompt", "prompt": "Password:", "echo": false}

// PAM info message
{"type": "auth_info", "message": "Welcome"}

// Auth failed
{"type": "auth_error", "message": "Incorrect password"}

// General error
{"type": "error", "message": "Session not found"}

// Sessions list
{
  "type": "sessions",
  "sessions": [
    {
      "id": "gar",
      "name": "gar",
      "comment": "Tiling window manager",
      "exec": "gar-session.sh",
      "session_type": "x11"
    }
  ]
}

// Users list
{
  "type": "users",
  "users": [
    {
      "name": "alice",
      "full_name": "Alice Smith",
      "home": "/home/alice",
      "avatar": "/home/alice/.face"
    }
  ]
}

X11 Sessions

X11 sessions reuse the X server started by gardmd.

Procedure

X server keeps running (started at daemon init)
gardmd forks child process
Child authenticates with PAM and opens session
Child drops privileges to target user (setuid/setgid)
Child sets environment (DISPLAY, XAUTHORITY, XDG_SESSION_TYPE=x11)
Child execve session command (e.g., gar-session.sh)
Parent waits for child to exit
When session ends, restart greeter

Environment Variables

Variable	Example Value
DISPLAY	:0
XAUTHORITY	/home/user/.Xauthority
XDG_SESSION_TYPE	x11
XDG_CURRENT_DESKTOP	gar
XDG_SESSION_DESKTOP	gar
XDG_VTNR	1

Session Discovery

gardmd discovers available sessions by parsing .desktop files from standard directories.

Search Directories

X11 sessions:

/usr/share/xsessions

/usr/local/share/xsessions

Wayland sessions:

/usr/share/wayland-sessions

/usr/local/share/wayland-sessions

Desktop File Format

/usr/share/xsessions/gar.desktop

[Desktop Entry]
Name=gar
Comment=Tiling window manager for X11
Exec=gar-session.sh
Type=Application

X Server Management

gardmd spawns and manages Xorg server lifecycle.

Xorg Command

/usr/bin/Xorg :0 vt1 \
  -keeptty \
  -noreset \
  -novtswitch \
  -nolisten tcp \
  -auth /dev/null

Flags Explained

Flag	Purpose
-keeptty	Keep using the VT (don't close TTY)
-noreset	Don't reset when last client exits
-novtswitch	Disable VT switching via Ctrl+Alt+Fn
-nolisten tcp	No TCP connections (local only)
-auth /dev/null	No initial auth file (managed later)

Readiness Check

After spawning Xorg, gardmd polls for readiness using x11rb::connect() with 10-second timeout. Once connection succeeds, X server is considered ready for greeter.

VT Management

Virtual Terminal allocation and switching via Linux ioctl syscalls.

VT Allocation

gardmd finds an unused VT using VT_OPENQRY ioctl on /dev/tty0. Returns first available VT number (typically 1 or 7).

fn find_unused_vt() -> Result<u32> {
    let console = OpenOptions::new().read(true).write(true).open("/dev/tty0")?;
    let mut vt: libc::c_int = 0;
    unsafe { libc::ioctl(console.as_raw_fd(), VT_OPENQRY, &mut vt) };
    Ok(vt as u32)
}

VT Switching

Uses VT_ACTIVATE and VT_WAITACTIVE ioctls to switch to the allocated VT.

fn switch_to_vt(vt: u32) -> Result<()> {
    let console = OpenOptions::new().read(true).write(true).open("/dev/tty0")?;
    let fd = console.as_raw_fd();
    unsafe {
        libc::ioctl(fd, VT_ACTIVATE, vt as libc::c_int);
        libc::ioctl(fd, VT_WAITACTIVE, vt as libc::c_int);
    }
    Ok(())
}

TTY Ownership

For Wayland sessions, gardmd changes /dev/ttyN ownership to the target user with chown(). This allows the compositor to open the TTY for direct KMS/DRM access.

Power Management

Power actions (shutdown, reboot, suspend) via systemd-logind D-Bus API.

D-Bus Methods

Action	D-Bus Method
Shutdown	org.freedesktop.login1.Manager.PowerOff
Reboot	org.freedesktop.login1.Manager.Reboot
Suspend	org.freedesktop.login1.Manager.Suspend

Permission Check

Can check if actions are allowed using CanPowerOff, CanReboot, CanSuspend methods. Returns "yes", "no", "challenge", or "na".

Interactive Flag

Power methods take interactive boolean parameter. gardmd uses false (no polkit prompt). Requires appropriate polkit policy for passwordless power actions at login screen.

Rendering

Rendering uses Cairo ImageSurface with manual frame copying to X11.

Rendering Stack

1. Cairo Context: 2D graphics rendering

2. Pango Layout: Text rendering and layout

3. Image Surface: ARGB32 framebuffer (full screen size)

4. X11 PutImage: Copy framebuffer to window

Frame Loop

loop

// Clear and render background

render_background(&ctx, &blurred_image)

// Render UI widgets

user_list.render(&ctx, &pango_ctx, &theme)

login_form.render(&ctx, &pango_ctx, &theme)

session_selector.render(&ctx, &pango_ctx, &theme)

power_buttons.render(&ctx)

// Copy to X11 window

window.put_image(surface.data())

// Handle events

process_x11_events()

sleep(16ms) // ~60fps

Background Blur

Greeter attempts to use garbg wallpaper, falls back to configured path. Image is loaded, blurred via Gaussian blur (downsample-blur-upsample), and brightness-adjusted.

Widgets

The greeter UI consists of modular widgets.

Keyboard Shortcuts

Key	Action
Tab	Move focus between username and password fields
Enter / Return	Submit login form
Up / Down	Navigate user list
Shift+Home / Shift+End	Select text to start/end of field
Ctrl+A	Select all text in field
Escape	Clear password / cancel authentication

Widget Types

UserList

Displays available users with avatars. Avatars are loaded from ~/.face, /var/lib/AccountsService/icons/USER, or ~/.face.icon. Auto-selects first user. Click or arrow keys to switch user.

Position: Above login form

LoginForm

Username and password input fields with login button. Keyboard navigation, cursor positioning, text selection.

Position: Centered on primary monitor

SessionSelector

Dropdown showing available sessions from .desktop files. Click to expand, select X11 or Wayland session.

Position: Below login form

PowerButtons

Icons for shutdown, reboot, suspend. Tooltips on hover. Sends power IPC requests to daemon.

Position: Bottom-right corner

Accessibility

Greeter supports accessibility options configured in greeter.toml.

Options

Option	Effect
high_contrast	Increases contrast for better visibility
large_text	Increases all font sizes
reduce_motion	Disables fade-out animation

/etc/gardm/greeter.toml

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

Common Workflows

Practical examples of using and configuring gardm.

Adding a Custom Session

Create a .desktop file for your session:

$ sudo $EDITOR /usr/share/xsessions/mysession.desktop # For X11 session

$ sudo $EDITOR /usr/share/wayland-sessions/mysession.desktop # For Wayland session

/usr/share/xsessions/mysession.desktop

[Desktop Entry]
Name=My Custom Session
Comment=My custom desktop environment
Exec=/usr/local/bin/my-session-start.sh
Type=Application

Debugging gardm Issues

Check gardm logs:

$ sudo journalctl -u gardm -f # Follow gardm service logs

$ sudo journalctl -u gardm --since "5 minutes ago" # Recent logs

$ RUST_LOG=debug sudo systemctl restart gardm # Enable debug logging

Testing gardm in Xephyr

Test gardm safely in nested X:

$ Xephyr :1 -screen 1920x1080 & # Start nested X server

$ DISPLAY=:1 gardmd --no-x --test-mode # Run daemon in test mode

$ DISPLAY=:1 gardm-greeter # Run greeter in nested display

Custom Wallpaper

Set a specific wallpaper for greeter:

/etc/gardm/greeter.toml

[garbg]
enabled = false
fallback = "/usr/share/backgrounds/my-wallpaper.png"

Custom Theme

Customize greeter colors:

/etc/gardm/greeter.toml

[theme]
font_family = "JetBrains Mono"
font_size_normal = 14
color_primary = "#bd93f9"      # Purple accent
color_background = "#282a36"   # Dracula background
color_text = "#f8f8f2"         # Light text
color_error = "#ff5555"        # Red errors

Switching Back to Previous DM

Restore your previous display manager:

$ sudo systemctl disable gardm # Disable gardm

$ sudo systemctl enable gdm # Enable GDM (or sddm/lightdm)

$ sudo systemctl start gdm # Start immediately

IPC & API Reference

gardm uses a Unix domain socket for IPC between gardmd (daemon) and gardm-greeter (UI). The greeter sends authentication requests and receives session control messages.

Socket Location

/run/gardm.sock

Only accessible by root and gardm-greeter process

Greeter → Daemon Commands

Command	Args	Description
authenticate	username, password	Authenticate user via PAM
start_session	username, session	Start user session
get_users	-	List available users
get_sessions	-	List available sessions
power_off	-	System shutdown
reboot	-	System reboot
suspend	-	System suspend

Daemon → Greeter Events

Event	Data	Description
auth_success	username	Authentication succeeded
auth_failure	reason	Authentication failed
session_started	session, pid	Session launched
session_ended	session, exit_code	Session terminated
users_list	[users]	Response to get_users

Request Format

JSON messages sent over Unix socket:

Authentication request

{
  "command": "authenticate",
  "args": {
    "username": "alice",
    "password": "***"
  }
}

Start session request

{
  "command": "start_session",
  "args": {
    "username": "alice",
    "session": "gar"
  }
}

Response Format

Success response

{
  "success": true,
  "event": "auth_success",
  "data": {
    "username": "alice"
  }
}

Error response

{
  "success": false,
  "event": "auth_failure",
  "data": {
    "reason": "Invalid password"
  }
}

User Object

{
  "username": "alice",
  "uid": 1000,
  "gid": 1000,
  "gecos": "Alice User",
  "home": "/home/alice",
  "shell": "/bin/bash",
  "face_icon": "/var/lib/AccountsService/icons/alice"
}

Session Object

{
  "id": "gar",
  "name": "gar Desktop",
  "comment": "The gar window manager",
  "exec": "/usr/bin/gar-session.sh",
  "type": "x11",
  "desktop_file": "/usr/share/xsessions/gar.desktop"
}

Security Notes

Socket only accessible by root and greeter process
Passwords transmitted in plaintext over socket (local only)
PAM handles actual authentication and password verification
Greeter drops privileges after connecting
Session processes run as authenticated user, not root

Power Management

Power commands use systemd-logind:

Command	D-Bus Method	Notes
power_off	PowerOff(false)	May require polkit rule
reboot	Reboot(false)	May require polkit rule
suspend	Suspend(false)	Hardware support required

Troubleshooting

gardm service won't start

Check service status and logs:

$ sudo systemctl status gardm # Check service status

$ sudo journalctl -xeu gardm # View detailed logs

$ ls -l /usr/bin/gardmd /usr/bin/gardm-greeter # Verify binaries exist

Ensure PAM config exists: ls -l /etc/pam.d/gardm

Black screen / X server fails to start

Check X server logs:

$ cat /var/log/Xorg.0.log | grep EE # Check for X errors

$ sudo journalctl -u gardm | grep "X server" # gardm X server logs

Verify Xorg is installed: which Xorg

Greeter not appearing

Check if greeter process started:

$ ps aux | grep gardm-greeter # Check if greeter running

$ echo $DISPLAY # Verify display is set

$ DISPLAY=:0 xdpyinfo # Test X connection

Cannot authenticate / PAM errors

Verify PAM configuration:

$ cat /etc/pam.d/gardm # Check PAM config

$ sudo journalctl -u gardm | grep -i pam # PAM-related logs

Ensure PAM config includes pam_unix.so or pam_systemd.so.

Session starts but immediately ends

Check session command and logs:

$ cat /usr/share/xsessions/gar.desktop # Verify session Exec command

$ which gar-session.sh # Check if session script exists

$ sudo journalctl -u gardm | grep "session" # Session start/end logs

Verify session command is executable and has correct shebang.

Wayland session fails to start

Check TTY ownership and session logs:

$ ls -l /dev/tty1 # Check TTY ownership

$ loginctl show-session # Verify logind session

$ sudo journalctl -u gardm | grep -i wayland # Wayland session logs

Ensure compositor has permissions and pam_systemd is configured.

Power buttons don't work

Check systemd-logind permissions:

$ systemctl status systemd-logind # Verify logind running

$ loginctl show-seat seat0 | grep CanPowerOff # Check permissions

May require polkit policy for passwordless power actions. Check /etc/polkit-1/rules.d/

IPC connection refused

Check socket exists and permissions:

$ ls -l /run/gardm.sock # Verify socket exists

$ sudo systemctl restart gardm # Restart to recreate socket

Stuck at greeter / can't login to TTY

Emergency recovery:

Reboot system
At GRUB, select "Advanced options"
Boot to single-user mode or recovery mode
Run: systemctl disable gardm
Run: systemctl enable gdm (or previous DM)
Reboot

Enable verbose logging

For maximum debug output:

/etc/systemd/system/gardm.service.d/override.conf

[Service]
Environment="RUST_LOG=gardmd=trace,gardm_greeter=trace"

$ sudo systemctl daemon-reload # Reload systemd

$ sudo systemctl restart gardm # Restart with debug logging

$ sudo journalctl -u gardm -f # Follow logs

Releases

v0.3.0 Latest

RPM (x86_64) RPM (aarch64) Source (.tar.gz)

Back to home

gardm

Features

Architecture

gardmd (Daemon)

gardm-greeter (UI)

Process Flow

Installation & Setup

1. Install gardm

2. Disable Current Display Manager

3. Enable gardm Service

4. Configure (Optional)

5. Reboot

CLI Flags

Recovery Procedure

Configuration Reference

Daemon Configuration

Greeter Configuration

PAM Configuration

Overview

Key Components

File Locations

Architecture

gardmd Daemon

Responsibilities

Main Loop

gardm-greeter UI

Responsibilities

Rendering Pipeline

IPC Protocol

Requests (Greeter → Daemon)

Responses (Daemon → Greeter)

Session Management

X11 Sessions

Procedure

Environment Variables

Wayland Sessions

Procedure

Why Stop X Server?

Session Lifecycle

Fork/Exec Flow

PAM Session

Session Discovery

Search Directories

Desktop File Format

Authentication

PAM Integration

Two-Phase Authentication

Why Two Phases?

Auth Flow

Auth States

Flow Diagram

Security Features

Failed Attempt Tracking

Empty Password Blocking

Privilege Separation

Password Handling

X Server Management

Xorg Command

Flags Explained

Readiness Check

VT Management

VT Allocation

VT Switching

TTY Ownership

Power Management

D-Bus Methods

Permission Check

Interactive Flag

Greeter UI

Rendering

Rendering Stack

Frame Loop

Background Blur

Widgets

Keyboard Shortcuts

Widget Types

Accessibility

Options

Common Workflows

Adding a Custom Session