This project uses a wayland display server and a wayland based terminal emulator to bring a full screen terminal experiance in userspace, for kernels without VTs

Instead of a terminal emulator being in kernel mode, the terminal emulators are in user space, and except for the recovery consoles, they run as a non-root user.

[Warning] It is not recommended to install with sddm v0.21. The multiseat handling is broken. It is fixed in SDDM's branch, which is yet to be tagged.
          Debian ships sddm with these fixes. The seat-vtty seat created for the vtty sessions is seen as a second seat by display managers.

============================================================================================================================

There are several different components
   1. recinit: Runs as root (for single-user mode, before logind starts, usually in an initrd that fails)

   2. UvTTY: Runs as the user, as a Wayland session

   3. vTTY: Runs as a non-root user, presenting a login, that runs as a systemd service
      There is the vtty-seatmanager service as well that can replace display-manager.service for systems without any other display managers, or display servers, or desktop environments.


  Administrators on VT-enabled kernels can use vttys by running `ln -s /usr/lib/systemd/system/vtty-frontend@.service /etc/systemd/system/autovt@.service` to replace the default gettys.
  Because of systemd parameters, the vtty-backend@.service and vtty-frontend@.service pair up with each other, and are for when seat0 is running on a kernel with VTs.

  More of the focus now is for VT-less kernels these days, so this configuration is not maintained as much, but this can allow for testing without changing the kernel.


  vtty-backend-seat@.service and vtty-frontend-seat@.service are for VT-less seats, including seat0 when there are no VTs (A VT-less kernel)
  It takes the seat as the parameter. However the seat can be followed by a "@" with a comment, to allow a second instance on the seat.

  Enabling vtty-frontend-seat@seat0.service is possible, to allow a singular instance on seat0.
  Enabling vtty-frontend-seat@seat0@mysession1.service and vtty-frontend-seat@seat0@mysession2.service is also possible to allow 2 sessions on seat0.


  Using vtty-seatmanager.service is recommended though, instead of hardcoding that.
  It detects the running seats, and it starts sessions on them.

============================================================================================================================
recinit

  recinit only is recommended for kernels without VTs.

  recinit can be started as init=/bin/recinit in an emergency. When recinit is pid 1

  It differs from init=/bin/bash in that when done, instead of running 'exec /sbin/init' instead, 'exit'-ing out makes it continue. and it runs 'exec /sbin/init' as soon as the terminal emulator quits.

  To make it run a different command, replace '/run/recinit/init' with a different command.


  recinit can also run in an initrd, usually to allow a console when the initrd fails to mount the root file system, to give the user a recovery console
  
  In testing, recinit can add around 12MB (pre-compressed file size) to the initrd.

  Hooks for initramfs-tools, initcpio, and dracut are included

============================================================================================================================

vtty-seatmanager

  This acts as a minimal 'display manager' for systems without a desktop environment
  It starts vtty frontends on all seats.

  It starts up to NAutoVTs (configured in logind) instances on a seat. logind typically defaults to 6.
  logind can be changed to add more or less, using /etc/systemd/logind.conf .

  For seat0, it will start at vtty-frontend-seat@seat0@vtty1.service
  and by default, it will go up to vtty-frontend-seat@seat0@vtty6.service 

  Upon start, it only starts the first instance on the seat.

  It only starts a new instance if a user is logged into the first instance, *and then* logind emits the SecureAttentionKey dbus signal, presenting a login to the user for the second instance
     (logind by default emits the signal when the user presses Ctrl+Alt+Shift+Esc)

  If a user logs into the second instance, and then presses Ctrl+Alt+Shift+Esc, it starts the third instance on the seat. Provided that both instances are still in use.

  If a user logs out of one of the instances, and Ctrl+Alt+Shift+Esc is pressed, it finds a free instance, allowing the user to log in

  When NAutoVTs is hit (6 sessions by default), further presses of Ctrl+Alt+Shift+Esc cycles through running sessions.

  To switch between sessions with less than 6, users can switch with Ctrl+Alt+F(x), just like switching with VTs. Most Display Servers handle this on seats without VTs.

============================================================================================================================

vTTY

  The vttys are started by systemd. There are two components, the backend, and the frontend.

  The backend runs a getty (or other command) under a socat instance. This allows the getty prompt to run as root without setuid.
  It also allows the commands to be resillent if the frontend ever crashes, the user sessions remain running..

  The frontend is the foot terminal emulator, running under the cage display server. The frontend runs as a non-root "vtty" user to protect the running system.
  Under foot, it starts a socat client to connect to the backend's socket, allowing the pty to appear on the frontend.

  The frontend traps the WINCH signal, the backend listends on a ptycommandproxy FIFO, and when the frontend terminal emulator size changes, it sets the PTY size of the backend.
  This allows TUI applications, like nmtui to work correctly

  Users who log in to vTTYs instead of starting under seat0, or a physical seat, start under the seat-vtty seat.
  seat-vtty is created by 72-seat-vtty.rules that makes this fake seat. This allows users under vTTYs to have fully functional PAM sessions

  For vTTYs, once logged in, users can use the 'vtty-launch' utility.

  For example 'vtty-launch weston' starts Weston

  vtty-launch allows commands like Weston or ffmpeg, or another display server to be run. vtty-launch suspends the frontend, and starts a session as the user, with the user's environment, on the same seat as the frontend.

============================================================================================================================

UvTTY

  The principals are similar for UvTTY as it is for vTTY.

  They are client-server like vTTYs, however the server and the client run as the same user, and the backend starts the user's $SHELL instead of a getty.


  /usr/share/wayland-sessions/fullscreenterminal.desktop is a "wayland session" that when selected from under a full-featured login manager, starts a UvTTY session

  This is for users who want to log into a full screen terminal experiance

  Users who want to run or test or develop display servers, can use uvtty-launch, very similar to vtty-launch.

============================================================================================================================

Configuring

  /usr/bin/vtty-login-program: This can be a symlink to any program, to make the vTTY sessions run a specific command instead of a getty.
    Distributions might want to do this for a first-time run program, such as 'console-conf' or something similar.

  /etc/vtty/footkiosk.conf: configures foot for the recinit, the vTTYs, and the user's UvTTYs
    Users can provide thier own ~/.config/uvtty/footkiosk.conf to override the settings in thier UvTTY sessions

  /etc/vtty/kanshiconfig.conf: This configures the kanshi daemon that enforces cage to be in clone mode.
    This is applicable in recinit, vTTYs, and UvTTYs
    Users can provide their their own ~/.config/uvtty/kanshiconfig.conf, but this is less-likely to be needed over footkiosk.conf.

  /etc/vconsole.conf: This is a system-wide file maintained by systemd-localed, and has gotten pretty standard. Keyboard settings are handled from this file
    Users can provide their own ~/.config/uvtty/vconsole.conf file however though for their UvTTY sessions.

  In the same vein as the vconsole.keymap= option would be handled for the kernel mode console
  the kernel command line arguments vconsole.xkblayout=, vconsole.xkbmodel=, vconsole.xkbvariant=, vconsole.xkboptions= are also handled by recinit, vTTYs and UvTTYs

============================================================================================================================

Requirements and dependencies

  cage             (the display server)
  foot             (the terminal emulator)
  socat            (The client/server utility)
  wl-clipboard     (for vTTYs to be able to clear the clipboard upon the next prompt for user log in)
  kanshi 1.9.0+    (for setting the cage multi-outputs to clone mode)
  libnet-dbus-perl (for vtty-seatmanager's interactions with dbus)