How it works

The way how snenslock locks your screen can be best explained with a flowchart:

Additional notes

• The currently active user session is determined via logind's DBus API, namely org.freedesktop.login1(5).
• The following safe-guards are implemented:
  • The lockscreen is rendered to an unused TTY. To prohibit switching back to another TTY, the ioctl(2) called VT_LOCKSWITCH is used.
  • The log-level for the console is set to 1 to make sure that no kernel messages are written to the TTY.
  • The sysrq shortcuts to kill a process and to alter the log-level are disabled.
• By default, the machine asks for the root password if the password of the locking user was wrongly entered five times. This can be changed using the CLI flag -t (or programs.snenslock.rootAtAuthTimes).
• Optionally it's possible to initiate a shutdown if the authentication failed N times. This can be configured using the CLI flag -p N (or programs.snenslock.poweroffAfter)
• The purple box is considered a "safe state": as soon as that is reached, the machine can be considered to be locked. If the greeter crashes, it will be restarted. However, please make sure that this state is actually reached, before that your machine is not locked!
• There are two greeters: a tui greeter (see screenshot above) and a minimal greeter. Since greeters can have arbitrarily complex GUI code (e.g. future greeters being fully graphic), a fallback is implemented to use a very minimal greeter. If the selected greeter crashes >3 times, this one is activated rather than restarting the previously used greeter.
• The code of the main process (i.e. the code that does locking, PAM check etc) is designed to not crash. If the greeter (i.e. the process interacting with the user to get a password) crashes, it will be restarted. However, software does crash. That means if snenslock itself crashes, the machine remains locked, but cannot be unlocked with snenslock. In that case there are two ways to unlock:
  • Force a reboot with sysrq.
  • Login via SSH and unlock the TTYs manually.

Important Assumptions

There are a few assumptions that must be met to make sure this software functions properly:

• The software is installed via the NixOS module in the repository's flake.
• As soon as the lock is active, the computer can be considered secured.
  • The systemd unit is considered active after this has happened. Before it's only in state activating. It must be ensured that the lock can be created.
• There must be a free, unused TTY. Otherwise creating the lock fails.
• The software is used to either lock TTYs or Wayland sessions (only tested with sway currently). E.g. X11 support is explicitly out of scope. It may work, but it was never tested. You'll probably want to use XScreenSaver then.