Configuration

The greeter stores its settings in a simple key-value file:

/var/lib/noctalia-greeter/greeter.conf

Lines use key = value syntax. Lines starting with # are comments.

• Keys the greeter remembers
• Admin-only keys
• Multi-monitor
• UI scale
• Cursor theme
• Keyboard layout
• Helper commands

---

Keys the greeter remembers

When you change session or color scheme on the login screen, the greeter writes:

Key	Purpose
session	Last Wayland session you picked (by Name from the session picker)
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.

---

Admin-only keys

Set these yourself. The greeter UI does not change them.

Key	Purpose
default_session	Session selected when the greeter opens. Overrides last-used session unless you pass --session on the greetd command line.
default_user	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.
greeter_user	greetd account name (written during setup; used for logging)
output	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)
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)

Example:

default_session = niri
default_user = lysec
output = "DP-2"
scale = 1.5

---

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 = "DP-2"

When output is set, the compositor disables the other connectors at the KMS level. If output is missing, empty, or names a disconnected connector, the greeter falls back to showing on all outputs.

On multiple monitors, cursor movement follows the layout in 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:

noctalia-greeter outputs

Restart greetd after changing output:

sudo systemctl restart greetd

---

UI scale

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 scale:

scale = 1.5

If scale is missing or invalid (not a positive number), the compositor falls back to auto scaling.

Note

Manual scale is separate from compositor or desktop scaling. It only affects the greeter session’s output scaling.

---

Cursor theme

The compositor resolves the cursor theme, size, and search path in this order:

1. cursor_theme / cursor_size / cursor_path in greeter.conf
2. The XCURSOR_THEME, XCURSOR_SIZE, and XCURSOR_PATH environment variables
3. The wlroots defaults (built-in cursor at size 24)

Set the keys in greeter.conf:

cursor_theme = Adwaita
cursor_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

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"

On NixOS

Use the programs.noctalia-greeter.settings.cursor options instead of editing greeter.conf 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

---

Keyboard layout

The compositor loads the XKB keymap in this order:

1. keyboard_layout / keyboard_variant / keyboard_options in greeter.conf
2. The XKB_DEFAULT_LAYOUT, XKB_DEFAULT_VARIANT, and XKB_DEFAULT_OPTIONS environment variables
3. The system default keymap

Example for Czech QWERTZ:

keyboard_layout = cz

Multiple layouts (cycle with keyboard_options, e.g. grp:alt_shift_toggle):

keyboard_layout = us,cz
keyboard_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.

greetd starts greeters with an empty environment, so set layout in greeter.conf or prefix the greetd session command:

[default_session]
command = "env XKB_DEFAULT_LAYOUT=cz /usr/bin/noctalia-greeter-session"

---

Helper commands

noctalia-greeter sessions   # list valid session names for default_session / --session
noctalia-greeter outputs    # list Wayland connector names for output

Sessions come from wayland-sessions .desktop files under /usr/share, each path in XDG_DATA_DIRS, and on NixOS /run/current-system/sw/share.