v5-greeter-configuration.md
The greeter stores its settings in /var/lib/noctalia-greeter/greeter.toml using grouped TOML tables (same style as Noctalia shell config).
If the file is missing, the greeter uses built-in defaults (auto UI scale, all monitors, system keymap, and so on). Setup ensures /var/lib/noctalia-greeter/ exists and is owned by the greetd session user from /etc/greetd/config.toml.
Section titled “Keys the greeter remembers”
When you change session or color scheme on the login screen, the greeter writes:
| Key | Purpose |
|---|---|
[session].last | Last Wayland session you picked (by Name from the session picker) |
[appearance].scheme | Last color scheme you picked |
These are updated automatically - you do not need to edit them by hand unless you want to reset them.
Section titled “Admin-only keys”
Set these yourself. The greeter UI does not change them.
| Key | Purpose |
|---|---|
[session].default | Session selected when the greeter opens. Overrides last-used [session].last unless you pass --session on the greetd command line. |
[user].default | Username to select on startup. Opens the password step immediately. --user on the greetd command line wins. Press Esc or Back to pick another user. |
[output].name | Wayland connector name to show the greeter on (see Multi-monitor) |
[output].layout | Multi-monitor positions as NAME:X,Y; ... in logical pixels (see Multi-monitor) |
[output].scale | Manual UI scale factor (see UI scale) |
[cursor].theme | Cursor theme name (e.g. Adwaita); missing → wlroots default cursor (see Cursor theme) |
[cursor].size | Cursor size in pixels (e.g. 24); missing → 24 |
[cursor].path | Colon-separated theme search path (sets XCURSOR_PATH); needed when the theme is not on the default search path (~/.icons:/usr/share/icons:/usr/share/pixmaps) |
[keyboard].layout | XKB layout code(s), e.g. cz, us, de,cz (comma-separated for multiple layouts; see Keyboard layout) |
[keyboard].variant | XKB variant(s), e.g. qwertz (optional; comma-separated when multiple layouts) |
[keyboard].options | XKB options string, e.g. grp:alt_shift_toggle (optional) |
[keyboard].numlock | Start with Num Lock locked: true (default) or false (see Keyboard layout) |
[appearance].password_style | Password mask on the login field: default (filled circles) or random (cycles through multiple glyph shapes, same as Noctalia shell password_style) |
[appearance].hide_logo | Hide the Noctalia brand logo on the greeter screen: true or false (default: false, logo shown) |
[auth].allow_empty_password | Allow submitting with an empty password field. Needed for PAM modules like fprintd or smartcard that handle authentication without a password (PAM expects an empty response to the password prompt). true or false (default: false) |
Example:
[session]default = "niri"last = "niri"
[user]default = "lysec"
[appearance]scheme = "Synced"password_style = "random"hide_logo = false
[output]name = "DP-2"layout = "DP-1:0,0; DP-2:2560,0"scale = 1.5
[cursor]theme = "Adwaita"size = 24path = "/usr/share/icons"
[keyboard]layout = "us,cz"variant = "qwertz"options = "grp:alt_shift_toggle"numlock = true
[auth]allow_empty_password = false
Section titled “Multi-monitor”
The greeter runs inside the bundled wlroots compositor (noctalia-greeter-compositor). By default it shows the same login UI on every connected monitor , with each display sized to its own resolution and scale.
To pin the greeter to a single connector:
[output]name = "DP-2"
When [output].name is set, the compositor disables the other connectors at the KMS level. If it is missing, empty, or names a disconnected connector, the greeter falls back to showing on all outputs.
On multiple monitors, cursor movement follows [output].layout. Without it, the greeter places outputs left-to-right by connector name, which often does not match your desk.
Sync from Noctalia: When you use Settings → Security → Noctalia Greeter → Sync Now , Noctalia copies monitor positions from your desktop compositor (via xdg-output) into [output].layout. Sync skips layout when only one monitor is connected, xdg-output is unavailable, outputs are still enumerating, or all monitors report the same origin.
Set positions manually if needed:
[output]layout = "DP-1:0,0; DP-2:2560,0"
Coordinates are logical pixels from your desktop compositor. The greeter compositor uses them for order and row grouping , then places outputs edge-to-edge using its own output scale (so cursor movement stays continuous).
List connector names from a running Wayland session:
Terminal window
noctalia-greeter outputs
Restart greetd after changing [output].name:
Terminal window
sudo systemctl restart greetd
On high-DPI panels (for example 4K without fractional scaling), the compositor scales output from the monitor’s physical size when EDID reports it, otherwise from resolution. Scale is capped at 2×. The greeter client lays out at logical size and renders HiDPI buffers via Wayland fractional scale.
To override auto scaling, set [output].scale:
[output]scale = 1.5
If [output].scale is missing or invalid (not a positive number), the compositor falls back to auto scaling.
The compositor resolves the cursor theme, size, and search path in this order:
[cursor].theme / [cursor].size / [cursor].path in greeter.tomlXCURSOR_THEME, XCURSOR_SIZE, and XCURSOR_PATH environment variables24)Set the keys in greeter.toml:
[cursor]theme = "Adwaita"size = 24
If the theme is not under the default search path (~/.icons:/usr/share/icons:/usr/share/pixmaps), also set [cursor].path to the directory that contains it:
[cursor]path = "/usr/share/icons"
Section titled “Using environment variables”
greetd starts greeters with an empty environment, so the XCURSOR_* variables must be set in the greetd session command rather than the service environment, for example in /etc/greetd/config.toml:
[default_session]command = "env XCURSOR_THEME=Adwaita XCURSOR_SIZE=24 /usr/bin/noctalia-greeter-session"
Use the programs.noctalia-greeter.settings.cursor options instead of editing greeter.toml or the greetd command by hand. They inject the matching XCURSOR_* variables into the greetd session command and add the theme package’s share/icons to XCURSOR_PATH:
programs.noctalia-greeter.settings.cursor = { theme = "Adwaita"; size = 24; package = pkgs.adwaita-icon-theme;};
| Option | Purpose |
|---|---|
theme | Cursor theme name (XCURSOR_THEME) |
size | Cursor size in pixels (XCURSOR_SIZE) |
package | Package providing the theme; its share/icons is added to XCURSOR_PATH |
Section titled “Keyboard layout”
The compositor loads the XKB keymap in this order:
[keyboard].layout / [keyboard].variant / [keyboard].options in greeter.tomlXKB_DEFAULT_LAYOUT, XKB_DEFAULT_VARIANT, and XKB_DEFAULT_OPTIONS environment variablesExample for Czech QWERTZ:
[keyboard]layout = "cz"
Multiple layouts (cycle with [keyboard].options, e.g. grp:alt_shift_toggle):
[keyboard]layout = "us,cz"options = "grp:alt_shift_toggle"
Use standard XKB layout codes (de, fr, ru, …). List layouts on your system with localectl list-x11-keymap-layouts or check /usr/share/X11/xkb/rules/base.lst.
The compositor locks Num Lock on startup so numeric keypads work without extra setup. If your keyboard misbehaves with Num Lock enabled (for example, the 0 digit key producing incorrect characters), disable it:
[keyboard]numlock = false
The default is true (Num Lock locked). This setting has no effect when Num Lock is not available on the keymap.
greetd starts greeters with an empty environment, so set layout in greeter.toml or prefix the greetd session command:
[default_session]command = "env XKB_DEFAULT_LAYOUT=cz /usr/bin/noctalia-greeter-session"
Section titled “Helper commands”
Terminal window
noctalia-greeter sessions # list valid session names for [session].default / --sessionnoctalia-greeter outputs # list Wayland connector names for [output].name
Sessions come from wayland-sessions .desktop files under /usr/share, each path in XDG_DATA_DIRS, and on NixOS /run/current-system/sw/share.