Configuration

Administrator-controlled settings live in /var/lib/noctalia-greeter/greeter.toml. Noctalia Sync and choices made on the login screen use the lower-priority sync.toml; they never rewrite greeter.toml.

Configuration files
Keys the greeter remembers
Configuration reference
Default session
Default user
Full example

Configuration files

Path	Role
`/var/lib/noctalia-greeter/greeter.toml`	Full declarative configuration. Wins over Sync when the same value is set
`/var/lib/noctalia-greeter/sync.toml`	Mutable Sync and UI state: appearance, last session/scheme, session actions, and output layout
`/var/lib/noctalia-greeter/wallpaper*`	Wallpaper images installed by Sync

If greeter.toml is missing, the greeter uses built-in defaults. System setup creates the state directory and files owned by the greetd session user.

On NixOS, use services.displayManager.noctalia-greeter.settings with both the nixpkgs, and project flake modules. Both materialize greeter.toml using a tmpfiles L+ entry.

The Synced scheme uses a complete [appearance.palette] from greeter.toml when present, otherwise the same keys from sync.toml. Legacy live appearance.json is migrated into sync.toml once. See Sync with Noctalia for the complete precedence and authorization model.

Wallpaper configuration is independent of the selected color scheme and does not require an [appearance.palette]. A wallpaper declared in greeter.toml therefore also works with built-in schemes such as Noctalia.

Keys the greeter remembers

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

Key in `sync.toml`	Purpose
`[session].last`	Last Wayland session selected, using its desktop-entry `Name=`
`[appearance].scheme`	Last color scheme selected, unless `greeter.toml` pins one

Appearance Sync sets the scheme to Synced while preserving the last session and existing session commands.

Configuration reference

Set these keys in greeter.toml. A command-line --session or --user value takes precedence over the corresponding default.

Key	Purpose
`[session].default`	Session selected on startup; overrides `[session].last`
`[user].default`	Username selected on startup; opens the password step
`[appearance].scheme`	Color scheme: `Synced` or a built-in name such as `Noctalia`
`[appearance].password_style`	Password mask: `default` or `random`
`[appearance].hide_logo`	Hide the Noctalia brand logo
`[appearance].power_buttons_position`	Power controls: `bottom-right` (default), `bottom-left`, `top-left`, `top-right`, or `hidden`
`[appearance].scheme_selector_position`	Scheme picker: `top-right` (default), `top-left`, `bottom-left`, `bottom-right`, or `hidden`
`[appearance].theme_mode`	Theme mode for the Synced appearance, such as `dark`
`[appearance].corner_radius_scale`	Corner-radius scale for the Synced appearance
`[appearance].font_family`	Fontconfig family for the Synced appearance
`[appearance.palette]`	Complete Synced palette; takes precedence over Sync appearance
`[appearance.wallpaper]`	Default wallpaper `path`, `fill_mode`, and `fill_color`; `fill_color` also works without an image, and `fill_mode` accepts `center`, `crop`, `fit`, `stretch`, `repeat`, or `span`
`[appearance.wallpapers.<connector>]`	Per-output wallpaper override using the same fill modes
`[output].name`	Connector or stable EDID identifier on which to pin the greeter
`[output].layout`	Multi-monitor positions; overrides synced layout
`[output].width` / `.height`	Preferred DRM mode size
`[output].refresh_rate`	Preferred DRM mode refresh rate in hertz, globally or per output
`[output].transforms`	Per-connector DRM transform; overrides synced transforms
`[output].scales`	Per-connector scale; overrides synced scales
`[output].scale`	Manual UI scale for every output
`[idle].timeout`	Seconds before outputs blank; `0` disables
`[cursor].theme` / `.size` / `.path`	Cursor theme
`[keyboard].layout` / `.variant` / `.options` / `.numlock`	XKB keymap
`[auth].allow_empty_password`	Permit an empty submission to start fprintd or smartcard PAM; this does not make password and fingerprint checks run in parallel
`[auth].request_timeout`	Seconds to wait for each greetd reply (`0`–`3600`, default `60`); `0` disables the watchdog

Display and input settings have task-oriented guides:

Displays: connectors, layout, mode, transforms, scale, and idle blanking
Keyboard and cursor: navigation, XKB, Num Lock, and cursor themes

PAM handles authentication methods in the order configured by the system. In particular, pam_fprintd cannot accept a password while it is waiting for a fingerprint. See Fingerprint blocks password login for the limitation and configuration options.

Default session

The value is the desktop entry’s exact Name=, which is the same text shown in the picker, not the .desktop filename. List available names with:

noctalia-greeter sessions

Sessions are discovered from wayland-sessions and xsessions directories under /usr/local/share, /usr/share, /run/current-system/sw/share, and each base path in XDG_DATA_DIRS. Name lookup is case-insensitive, but using the exact picker spelling keeps the configuration unambiguous. If a wayland-sessions and an xsessions entry share the same Name=, the wayland-sessions entry wins.

An xsessions entry’s Exec= is run through noctalia-greeter-xsession, which bootstraps Xorg via startx before running it — startx handles DISPLAY/Xauthority setup for the client. This requires xinit (for startx) to be installed; without it, the session fails with a clear “startx not found” error instead of starting. The wrapper runs:

startx <session Exec=> -- -seat "${XDG_SEAT:-seat0}" -keeptty vt${XDG_VTNR}

-seat/vt${XDG_VTNR} let Xorg get the GPU device and VT through elogind/systemd-logind instead of needing root: -seat gets the device handoff, and the explicit vtN is required separately because Xorg only skips its normally-root-only /dev/tty0 probe when a VT number is given directly on the command line. XDG_SEAT/XDG_VTNR come from the PAM session the same way XDG_SESSION_TYPE does. The wrapper also resolves a bare Exec= program name (e.g. Exec=bspwm) to an absolute path before handing it to startx, since some startx implementations only accept the client as a direct path and silently fall back to their default client (xterm) otherwise. See X11 session doesn’t start if it still fails.

Set the default declaratively, especially when it contains spaces or punctuation:

[session]
default = "Hyprland (uwsm-managed)"

Alternatively, a simple name can be passed through the greetd command:

command = "/usr/bin/noctalia-greeter-session -- --session niri"

Resolution order is command-line --session, [session].default, remembered [session].last, then the first discovered session. An unknown name is ignored.

Before PAM opens the selected session, the greeter passes XDG_SESSION_TYPE=wayland and derives XDG_CURRENT_DESKTOP and XDG_SESSION_DESKTOP from the desktop entry’s DesktopNames=. This helps environments that expect systemd-managed session metadata. GNOME support remains best-effort compared with GDM.

Default user

To open directly on one account’s password step:

[user]
default = "alice"

You can instead pass --user alice after the session wrapper’s --. Use the exact login name from /etc/passwd. Esc or the back button returns to the user list.

Resolution order is command-line --user, then [user].default, then the user picker.

Full example

Use the maintained full greeter.toml example as the canonical reference. Copy it to /var/lib/noctalia-greeter/greeter.toml, then remove the values you do not want to override.

Restart greetd after changing startup, output, input, or idle settings. Appearance and picker state are otherwise read the next time the greeter starts.