greetd

Related articles
Display manager
Wayland
Sway
greetd
is a minimal, agnostic and flexible
login manager
daemon which does not make assumptions about what the user wants to launch, should it be console-based or graphical. Any script or program which can be started from the console may be launched by greetd, which makes it particularly suitable for
Wayland compositors
.  It can also launch a
greeter
to start user sessions, like any other display manager.
Installation
Install
the
greetd
or
greetd-git
AUR
packages.
The default greetd configuration file is located at
/etc/greetd/config.toml
.
PAM
-specific configuration is set in
/etc/pam.d/greetd
.
Greeters
Greetd has greetd-agreety as its built-in greeter, however this is a minimal implementation. You should consider using one of the several available greeters:
cosmic-greeter
— A
libcosmic
greeter.
https://github.com/pop-os/cosmic-greeter
||
cosmic-greeter
dlm
— An fbdev greeter.
https://git.sr.ht/~kennylevinsen/dlm
||
greetd-dlm-git
AUR
ddlm
— An fbdev greeter. Enhanced/extended version of
dlm
.
https://github.com/deathowl/ddlm
||
greetd-ddlm-git
AUR
greetd-agreety
— The default, a text-based greeter similar to
agetty
.
https://git.sr.ht/~kennylevinsen/greetd
||
greetd-agreety
gtkgreet
— A
GTK
greeter.
https://git.sr.ht/~kennylevinsen/gtkgreet
||
greetd-gtkgreet
hyprlogin
— Hyprland's simple, yet multi-threaded and GPU-accelerated greetd greeter utility.
https://github.com/AuthenticSm1les/hyprlogin
||
hyprlogin-git
AUR
nwg-hello
— GTK3-based greeter for greetd written in python.
https://github.com/nwg-piotr/nwg-hello
||
nwg-hello
ReGreet
— A
GTK
greeter. Supports various customization options. Wayland only.
https://github.com/rharish101/ReGreet
||
greetd-regreet
qtgreet
— A
Qt
greeter.
https://gitlab.com/marcusbritanicus/QtGreet
||
greetd-qtgreet
AUR
sysc-greet
— A TUI ASCII greeter written in Go.
https://github.com/Nomadcxx/sysc-greet
||
sysc-greet
AUR
tuigreet
— A console UI greeter.
https://github.com/apognu/tuigreet
||
greetd-tuigreet
wlgreet
— A
Wayland
greeter.
https://git.sr.ht/~kennylevinsen/wlgreet
||
greetd-wlgreet
AUR
Starting greetd
Enable
greetd.service
so greetd will be started at boot.
See also
Display manager#Loading the display manager
.
Greeter configuration
Configuring the greeter run by greetd is done using the
command
option in the
default_session
section in
/etc/greetd/config.toml
.
The included
agreety
greeter will be used if no changes are made. Also see
#agreety
.
By default, greeters are run as the
greeter
user. This can be changed by editing the
user
option in the
default_session
section of the configuration file and replacing
another_user
with the chosen user:
...
[default_session]
user = "another_user"
...
Make sure the
ownership
of the
/etc/greetd
directory is set accordingly.
agreety
This is the default greeter. It is launched by greetd with the configuration file set as follows:
...
[default_session]
command = "agreety --cmd $SHELL"
...
agreety can launch any arbitrary command once a user logs in. For example, in order to start
Sway
, replace
$SHELL
in the example above with
sway
.
gtkgreet
In order to run, gtkgreet needs a compositor. For the full experience, a compositor with
wlr-layer-shell-unstable
support is required but others can work. As such, it is recommended to use
sway
, but something like
cage
can also be used. Examples for both cage and sway are provided below.
In order to specify which login environments can be started by gtkgreet, list them in
/etc/greetd/environments
.
For example:
sway
bash
You can also invoke gtkgreet with the
-c
mycommand
parameter, replacing
mycommand
with the desired program (for example,
gtkgreet -c bash
or
gtkgreet -c sway
). Do so in the below compositor examples as desired.
Using cage
Install
cage
and set the
command
option as follows:
...
[default_session]
command = "cage -s -- gtkgreet"
...
The
-s
argument enables VT switching in cage (0.1.2 and newer only), which is highly recommended to prevent locking yourself out.
Using sway
Install
sway
. When using
Sway
, it must be terminated once the user logs in. For that purpose, a specific configuration file must be created, for example in
/etc/greetd/sway-config
, with the following content:
# `-l` activates layer-shell mode. Notice that `swaymsg exit` will run after gtkgreet.
exec "gtkgreet -l; swaymsg exit"

bindsym Mod4+shift+e exec swaynag \
-t warning \
-m 'What do you want to do?' \
-b 'Poweroff' 'systemctl poweroff' \
-b 'Reboot' 'systemctl reboot'

include /etc/sway/config.d/*
Then, greetd must be set to start
Sway
with the configuration file above. Set the
command
option as follows:
...
[default_session]
command = "sway --config /etc/greetd/sway-config"
...
ReGreet
Similar to gtkgreet, ReGreet needs a compositor. For example, both Cage and Sway can be used just like they are used for gtkgreet, replacing the
gtkgreet
command with
regreet
. The config for Sway would thus look like:
# Notice that `swaymsg exit` will run after ReGreet.
exec "regreet; swaymsg exit"

bindsym Mod4+shift+e exec swaynag \
-t warning \
-m 'What do you want to do?' \
-b 'Poweroff' 'systemctl poweroff' \
-b 'Reboot' 'systemctl reboot'

include /etc/sway/config.d/*
ReGreet picks up available sessions from
/usr/share/xsession
(for X11 sessions) and
/usr/share/wayland-sessions
(for Wayland sessions). Thus, there is no need to list sessions in
/etc/greetd/environments
.
ReGreet can be configured through a TOML file in
/etc/greetd/regreet.toml
. A sample file is provided in
/usr/share/doc/greetd-regreet/regreet.sample.toml
with all available options. Copy this to
/etc/greetd/regreet.toml
and make the changes you want, commenting out or deleting the lines you do not need. Any invalid options are ignored.
Using Hyprland
Set the
command
option as follows:
...
[default_session]
command = "start-hyprland -- -c /etc/greetd/hyprland.conf"
...
Then create
/etc/greetd/hyprland.conf
as:
/etc/greetd/hyprland.conf
exec-once = regreet; hyprctl dispatch exit
wlgreet
In order to start wlgreet, a compositor with
wlr-layer-shell-unstable
is required. Follow the steps required to set up gtkgreet with Sway as
described above
but use the following for
/etc/greetd/sway-config
instead:
exec "wlgreet --command sway; swaymsg exit"

bindsym Mod4+shift+e exec swaynag \
-t warning \
-m 'What do you want to do?' \
-b 'Poweroff' 'systemctl poweroff' \
-b 'Reboot' 'systemctl reboot'

include /etc/sway/config.d/*
tuigreet
tuigreet does not require any special setup. Set the
command
option as follows, replacing
sway
if you use a different desktop environment/window manager:
...
[default_session]
command = "tuigreet --cmd sway"
...
tuigreet --help
will display customization options.
ddlm
ddlm does not require any special setup, just set the
command
option as follows, replacing
sway
if you use a different desktop environment/window manager:
...
[default_session]
command = "ddlm --target sway"
...
qtgreet
In order to use qtgreet, you need a WLR based compositor (e.g.
wayfire
,
sway
).
Using Wayfire
Install
wayfire
and set the
command
option as follows:
...
[default_session]
command = "wayfire --config /etc/qtgreet/wayfire.ini"
...
The Wayfire configuration file referred to is included with qtgreet.
Using Hyprland
Set the
command
option as follows:
...
[default_session]
command = "start-hyprland -- -c /etc/greetd/hyprland.conf"
...
Then create
/etc/greetd/hyprland.conf
as:
/etc/greetd/hyprland.conf
exec-once = qtgreet; hyprctl dispatch exit
nwg-hello
In order to use nwg-hello, you either need
sway
or
hyprland
.
Using Sway
Install
sway
and set the
command
option as follows:
...
[default_session]
command = "sway -c /etc/nwg-hello/sway-config"
...
The Sway configuration file referred to is included with nwg-hello.
Using Hyprland
Install
hyprland
and set the
command
option as follows:
...
[default_session]
command = "start-hyprland -- -c /etc/nwg-hello/hyprland.conf"
...
The Hyprland configuration file referred to is included with nwg-hello.
Tips and tricks
Enabling autologin
If you want a user to be logged in automatically, an
initial_session
section must be defined in
/etc/greetd/config.toml
:
...
[initial_session]
command = "sway"
user = "
myuser
"
...
The
command
option may contain the name of any executable file. In the example above, Sway will be started by
myuser
at boot.
If you do not want to use
greetd
and always want autologin to be enabled, see
autologin
.
Unlocking keyring on autologin using the cryptsetup password
Autologin is often used on a single-user system with
full disk encryption
.
Both
GNOME/Keyring
and
KDE Wallet
can be unlocked using the encryption password entered at boot.
In the case of other display managers, this typically requires an entry such as
auth optional pam_systemd_loadkey.so
,
auth optional pam_gdm.so
, or similar, in the PAM config.
However, this setup does not work with greetd because it skips the
auth
stack entirely. 
Instead, use the
pam_fde_boot_pw
module (currently not packaged and not in AUR).
After installing the module to
/usr/local/lib/security/pam_fde_boot_pw.so
, use the following PAM config. Substitute
inject_for=gkr
(GNOME Keyring) with
inject_for=kwallet5
for KDE Wallet.
/etc/pam.d/greetd
#%PAM-1.0

auth       required     pam_securetty.so
auth       requisite    pam_nologin.so
auth       include      system-local-login
account    include      system-local-login
session    optional     /usr/local/lib/security/pam_fde_boot_pw.so inject_for=gkr
session    include      system-local-login
session    optional     pam_gnome_keyring.so auto_start
Run local programs
Add the
PATH
environment variable
to
~/.profile
, or the desktop environment called by greetd will not be able to run local programs. Greetd will not source
shell configuration files
and thus not get any modified variables from these files.
~/.profile
export PATH="$HOME/.local/bin:$PATH"
Setting the environment
By default greetd does not set environment variables such as
XDG_SESSION_TYPE
and
XDG_CURRENT_DESKTOP
, unless the greeter sets them based on the session you chose (for example TUI will set the session type based on the location of the session file chosen). One way to solve this is to use a wrapper script that sets any desired environment variables before running the actual command. For example to start sway:
/usr/local/bin/start-sway
#!/bin/sh
export XDG_SESSION_TYPE=wayland
export XDG_SESSION_DESKTOP=sway
export XDG_CURRENT_DESKTOP=sway

# Wayland stuff
export QT_QPA_PLATFORM=wayland
export SDL_VIDEODRIVER=wayland
export _JAVA_AWT_WM_NONREPARENTING=1

exec sway "$@"
then use this wrapper script as the command the greeter runs. For example with
gtkgreet
you could use
/etc/greetd/config.toml
...
[default_session]
command = "gtkgreet -c /usr/local/bin/start-sway"
...
or put
start-sway
in
/etc/greetd/environments
.
See
How to Set XDG_SESSION_TYPE=wayland
Setting logind session type
Note
This is necessary for running GNOME on Wayland properly.
The logind session type is set by the XDG_SESSION_TYPE environment variable. However, it must be set
before
the PAM session is opened. Because of this, setting the variable through
~/.profile
or a wrapper script will not work (both happen after session open).
The correct way to achieve this is through the environment variables sent by greeters (these are set before session open). So if your greeter supports it, just make it send the appropriate
XDG_SESSION_TYPE=xxx.
If your greeter does not support this, it is also possible to use
pam_env
under the auth group. The drawback is that all the sessions spawned by greetd will use that session type, which may or may not be problematic depending on your use case.
Here is how one could use the pam_env method to have a Wayland session:
/etc/greetd/config.toml
[general]
service = "greetd-spawn"
/etc/greetd/greetd-spawn.pam_env.conf
XDG_SESSION_TYPE DEFAULT=wayland OVERRIDE=wayland
/etc/pam.d/greetd-spawn
auth       include      greetd
auth       required     pam_env.so conffile=/etc/greetd/greetd-spawn.pam_env.conf
account    include      greetd
session    include      greetd
Missing mouse cursor
If you are using
qtgreet
with a compositor such as
wayfire
and generally need to export variables, such as
WLR_NO_HARDWARE_CURSORS=1
to get the mouse cursor working, one solution would be to create a separate
executable
script and then calling that from
/etc/greetd/config.toml
.
/usr/local/bin/greetd-startup.sh
#!/bin/sh
export WLR_NO_HARDWARE_CURSORS=1
exec wayfire --config /etc/qtgreet/wayfire.ini
/etc/greetd/config.toml
...
[default_session]
command = "/usr/local/bin/greetd-startup.sh"
...
Prevent systemd messages from overwriting console-based greeterd
If you are using console-based greeters such as
tuigreet
systemd messages can overwrite UI. To prevent this you may use
console=quiet
kernel parameter
as it prevents display of any messages (also during boot).
If you still would like to see messages during boot, you could instead append
console=tty1
to
kernel parameters
. This would redirect all messages from
/dev/console
(which broadcasts to all ttys) to
/dev/tty1
, which is utilized during boot. Now you just need to select any other TTY for greeter. Either specify particular tty (other than tty1) or use
next
option. According to
greetd(5)
this must be in the
[termina]
section
/etc/greetd/config.toml
...
[terminal]
vt = "next"
...
See also
greetd project page
greetd source code
greetd wiki