latchd/docs/configuration.md

Configuration reference

Latchd uses /etc/latchd/config.toml as its service configuration. The complete example is ../extra/config.toml. Copy it to the main file, then change the required values.

Command-line overrides

These command-line options replace selected values for one run:

Option	Field changed
--tty N	tty
--xsessions PATH	x11.sessions_path
--wlsessions PATH	wayland.sessions_path
--initial-path PATHS	initial_path

Use these options for a one-time test. Put permanent values in the main file.

Top-level fields

Field	Default	Description
tty	2	Virtual terminal number. Valid values are 1 through 63.
main_log_path	/var/log/latchd.log	Main service log.
client_log_path	/var/log/latchd.client.log	Output log for graphical session clients.
pam_service	latchd	Name of the PAM service file in /etc/pam.d/.
system_shell	/bin/sh	Shell used by the TTY session and the preflight check.
initial_path	/usr/local/sbin:/usr/local/bin:/usr/bin	Absolute directories used to resolve session programs.

The path fields in this table must be absolute. initial_path must contain only non-empty absolute directories separated by colons.

[x11]

The X server starts only when the selected session has kind X11.

Field	Default	Description
display	:1	X display name passed to Xorg and the session.
server_path	/usr/bin/X	X server executable.
xauth_path	/usr/bin/xauth	Program that writes the temporary Xauthority file.
server_timeout_secs	60	Maximum wait for the X server readiness signal.
server_log_path	/var/log/latchd.xorg.log	X server log.
sessions_path	/usr/share/xsessions	Directory with X11 .desktop files.
scripts_path	/etc/latchd/wms	Directory with administrator X11 session scripts.

Set absolute paths for the X server and xauth. Latchd passes display, vtN, and the authority file to Xorg.

[wayland]

Field	Default	Description
sessions_path	/usr/share/wayland-sessions	Directory with Wayland .desktop files.
scripts_path	/etc/latchd/wayland	Directory with administrator Wayland session scripts.

The selected Wayland program starts with these values; latchd does not start a compositor or create a Wayland socket.

[environment_switcher]

Field	Default	Description
include_tty_shell	false	Add the TTY shell when graphical sessions exist.
max_display_length	18	Maximum display width used for session titles. Must be greater than zero.
remember_last_session	true	Remember the last successful session for each account.
last_session_path	/var/lib/latchd/last-session.toml	File for the saved session preference.

The preference file stores a session kind and title for each account; it holds at most 128 entries, writes a synced temporary file, and renames it into place. The file and its parent directory must belong to the account that runs latchd and must not be writable by group or other users.

Set remember_last_session = false to disable reads and writes; latchd ignores the path in that case.

[accounts]

Field	Default	Description
minimum_uid	1000	Lowest UID that account enumeration includes.
excluded_users	[]	Usernames that account enumeration skips.
enumerate	true	Discover accounts through NSS for the account list.
faillock_path	/usr/sbin/faillock	Faillock helper executable.
faillock_config	/etc/security/faillock.conf	File from which Latchd reads the deny value.
shadow_path	/etc/shadow	Shadow file used for account status display.

Account enumeration also requires an absolute login shell and a safe home directory; /bin/false, /usr/sbin/nologin, and /sbin/nologin are excluded.

Latchd reads the shadow file only when it is a root-owned, non-writable regular file. The screen can show these states:

• Locked when the password hash starts with ! or *;
• PasswordExpired when the last-change day is zero or the maximum age passed;
• AccountExpired when the account expiry day passed;
• AccountInactive when the inactive period passed;
• NoLoginShell when the shell does not permit login;
• Unknown when shadow data is not available.

The faillock check only adds status text. The helper runs:

faillock --user USERNAME --legacy-output

The query stops after 750 milliseconds. Bad output, a missing helper, or a timeout removes the faillock status from the screen.

[visual]

Field	Default	Description
wallpaper_path	not set	Optional PNG or JPEG file for the TUI background.
background_enabled	true	Draw the wallpaper and ambient background.
animations	true	Update the ambient cellular animation.
notifications	true	Show short status notices in the TUI.
reduced_motion	false	Start with the ambient animation disabled.
max_wallpaper_bytes	8388608	Maximum wallpaper file size. Valid range is 1 to 67108864 bytes.

The wallpaper path must be absolute, and the file must be root-owned, regular, and not group-writable or other-writable. Source images are limited to 8192 by 8192 pixels and 16,777,216 pixels total, then scaled for the terminal.

The TUI also caps the animation state at 160 columns by 64 rows. Press Ctrl-B to toggle the background. Press Ctrl-M to toggle reduced motion.

[power_controls]

Power actions are disabled in preview mode. Each action needs an absolute program path and a function-key label:

[[power_controls.entries]]
key = "F1"
hint = "Power off"
program = "/usr/bin/systemctl"
args = ["poweroff"]

key must be F1 through F12, and hint must not be empty; program starts directly with args, without a shell, after the TUI asks for confirmation.

Desktop entry rules

Only the [Desktop Entry] section is read, with these keys:

Key	Use
Name	Session title.
Type	Must be Application when present.
Hidden	true hides the entry.
NoDisplay	true hides the entry.
TryExec	Optional executable check.
Exec	Program and arguments.
DesktopNames	Values for XDG_CURRENT_DESKTOP and XDG_SESSION_DESKTOP.

Plain and quoted arguments are accepted; desktop field codes such as %u and %f, plus shell syntax, are rejected.

Validation failures

The parser rejects unknown fields. The validator rejects these common errors:

• a virtual terminal outside 1 through 63;
• an empty PAM service name;
• an empty path or a relative directory in initial_path;
• a relative path in a required absolute-path field;
• a zero session title width;
• a relative last-session path when preferences are enabled;
• a zero or oversized wallpaper limit;
• an empty X display or zero X server timeout;
• an invalid power-action key, label, or program path.

Use --preview --no-tui to report these errors without starting the screen.