greetd - ArchWiki

Jump to content

# greetd

From ArchWiki

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-gitAUR 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-gitAUR

- ddlm — An fbdev greeter. Enhanced/extended version of `dlm`.

  https://github.com/deathowl/ddlm || greetd-ddlm-gitAUR

- 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-gitAUR

- 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-qtgreetAUR

- sysc-greet — A TUI ASCII greeter written in Go.

  https://github.com/Nomadcxx/sysc-greet || sysc-greetAUR

- tuigreet — A console UI greeter.

  https://github.com/tuigreet/tuigreet || greetd-tuigreet

- wlgreet — A Wayland greeter.

  https://git.sr.ht/~kennylevinsen/wlgreet || greetd-wlgreetAUR

## 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.lua"
    ...

Then create `/etc/greetd/hyprland.lua` as:

    /etc/greetd/hyprland.lua

    hl.on("hyprland.start", function()
      hl.exec_cmd("regreet; hyprctl dispatch exit")
    end)

Note Before Hyprland v0.55, config files used Hyprlang instead of Lua as the default format. This is deprecated in current versions and will be removed in a future release.

Instead of a Lua file, you would create a /etc/greetd/hyprland.conf with the following:

    /etc/greetd/hyprland.conf

    exec-once = regreet; hyprctl dispatch exit

The greetd config.toml would also use the .conf extension instead:

    /etc/greetd/config.toml

    ...
    [default_session]
    command = "start-hyprland -- -c /etc/greetd/hyprland.conf"
    ...

### 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

For Wayfire 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.lua"
    ...

Then create `/etc/greetd/hyprland.lua` as:

    /etc/greetd/hyprland.lua

    hl.on("hyprland.start", function()
      hl.exec_cmd("qtgreet; hyprctl dispatch exit")
    end)

Note Before Hyprland v0.55, config files used Hyprlang instead of Lua as the default format. This is deprecated in current versions and will be removed in a future release.

Instead of a Lua file, you would create a configuration as follows:

    /etc/greetd/hyprland.conf

    exec-once = qtgreet; hyprctl dispatch exit

The greetd `config.toml` would also use the `.conf` extension instead:

    /etc/greetd/config.toml

    ...
    [default_session]
    command = "start-hyprland -- -c /etc/greetd/hyprland.conf"
    ...

### nwg-hello

The nwg-hello greeter, supports Sway and Hyprland.

#### Using Sway

For Sway 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

For Hyprland set the `command` option as follows:

    ...
    [default_session]
    command = "start-hyprland -- -c /etc/nwg-hello/hyprland.lua"
    ...

The Hyprland configuration file referred to is included with nwg-hello.

Note The current version of nwg-hello uses Hyprlang `.conf` which has been deprecated since v0.55 and is set to be removed in a future update in favor of the new Lua configuration system. There is a chance that this included configuration file will no longer work in the future - refer to above sections for a working Hyprland Lua config.

## 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 (pam-fde-boot-pw-gitAUR).

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/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 `[terminal]` section

    /etc/greetd/config.toml

    ...
    [terminal]
    vt = "next"
    ...

## See also

- greetd project page
- greetd source code
- greetd wiki

Category:

- Display managers

greetd
Add topic