gentoo-legion/docs/greetd-setup.md

greetd Display Manager Setup

Guide for configuring greetd with regreet (GTK greeter) on Gentoo with Hyprland.

Overview

greetd is a minimal display manager that launches regreet inside a temporary Hyprland session. This provides a graphical login screen that works well with Wayland compositors.

Architecture:

greetd (daemon) → Hyprland (minimal) → regreet (GTK greeter) → User session

Installation

Required Packages

emerge gui-libs/greetd gui-apps/regreet gui-libs/display-manager-init

Enable Service

# Set greetd as display manager
echo 'DISPLAYMANAGER="greetd"' > /etc/conf.d/display-manager

# Add to default runlevel
rc-update add display-manager default

Configuration Files

/etc/greetd/config.toml

Main greetd configuration:

[terminal]
vt = 7

[default_session]
command = "start-hyprland -- --config /etc/greetd/hyprland.conf > /var/log/hyprland-greeter.log 2>&1"
user = "greetd"

/etc/greetd/regreet.toml

GTK greeter theming:

[background]
path = "/usr/share/backgrounds/default.png"
fit = "Cover"

[GTK]
application_prefer_dark_theme = true

[commands]
reboot = ["loginctl", "reboot"]
poweroff = ["loginctl", "poweroff"]

Note: Uses loginctl for power commands (OpenRC-compatible, not systemd).

/etc/greetd/hyprland.conf

Minimal Hyprland config for the greeter session:

exec-once = regreet; hyprctl dispatch exit

env = XCURSOR_THEME,Bibata-Modern-Ice
env = XCURSOR_SIZE,24

# Force greeter to laptop display only
monitor=eDP-2, 1920x1080@60, 0x0, 1
monitor=DP-1, disable
monitor=DP-2, disable

cursor {
    default_monitor = eDP-2
}

input {
    touchpad {
        disable_while_typing = true
        natural_scroll = true
        tap-to-click = true
    }
}

misc {
    disable_hyprland_logo = true
    disable_splash_rendering = true
    disable_autoreload = true
}

debug {
    disable_logs = true
}

/etc/pam.d/greetd

Custom PAM configuration to prevent user.greetd errors:

# greetd PAM configuration
# Omits pam_openrc.so to prevent user.greetd service errors

auth            include         system-local-login
account         include         system-local-login
password        include         system-local-login
session         optional        pam_loginuid.so
session         required        pam_env.so envfile=/etc/profile.env
session         include         system-auth
session         optional        pam_motd.so motd=/etc/motd
session         optional        pam_lastlog.so never showfailed
session         optional        pam_mail.so
-session        optional        pam_elogind.so

Why custom PAM? The default PAM chain includes pam_openrc.so which tries to start a user session service (user.greetd). Since greetd is a system service, not a user login, this fails and generates errors at boot.

User Session Launcher

/usr/local/bin/start-hyprland-dbus

Wrapper script for user Hyprland sessions with logging:

#!/bin/bash
exec dbus-run-session /usr/bin/start-hyprland > ~/.local/log/hyprland.log 2>&1

Update Desktop Entry

Modify /usr/share/wayland-sessions/hyprland.desktop:

Exec=/usr/local/bin/start-hyprland-dbus

Create Log Directory

mkdir -p ~/.local/log

Log Files

Log	Location	Purpose
Greeter	/var/log/hyprland-greeter.log	Greeter Hyprland session
User	~/.local/log/hyprland.log	User Hyprland session

The greeter log file needs correct ownership:

sudo touch /var/log/hyprland-greeter.log
sudo chown greetd:greetd /var/log/hyprland-greeter.log

Customization

Change Background

Edit /etc/greetd/regreet.toml:

[background]
path = "/path/to/your/wallpaper.png"

Change Cursor Theme

Edit /etc/greetd/hyprland.conf:

env = XCURSOR_THEME,<your-cursor-theme>
env = XCURSOR_SIZE,24

Enable External Monitors at Login

Remove or modify the disable lines in /etc/greetd/hyprland.conf:

# Enable external monitors
monitor=DP-1, 1920x1080@60, 0x0, 1
monitor=eDP-2, 1920x1080@60, 1920x0, 1

Troubleshooting

"failed to start user.greetd" at boot

Ensure you're using the custom /etc/pam.d/greetd that omits pam_openrc.so.

Black screen at login

1. Check /var/log/hyprland-greeter.log for errors
2. Verify monitor configuration in /etc/greetd/hyprland.conf
3. Ensure greetd user has access to DRI devices

regreet not appearing

1. Verify regreet is installed: which regreet
2. Check the exec-once line in hyprland.conf
3. Review greeter logs

Keyboard not working

Ensure elogind is running and in boot runlevel:

rc-update add elogind boot
rc-service elogind start

Service management

# Check status
rc-service display-manager status

# Restart
rc-service display-manager restart

# View logs
cat /var/log/hyprland-greeter.log