Skip to content

Latest commit

 

History

History
290 lines (201 loc) · 14.7 KB

README.md

File metadata and controls

290 lines (201 loc) · 14.7 KB
Raw

emptty

Release GitHub Workflow Status Go Report Card

Dead simple CLI Display Manager on TTY

Packaging status

Configuration

NOTE: Please be aware that emptty does not source any kind of .profile scripts by default. If you want to use them, please see samples.

/etc/emptty/conf

Default startup configuration. On each change it requires to restart emptty.

TTY_NUMBER TTY, where emptty will start.

SWITCH_TTY Enables switching to defined TTY number. Default is true.

PRINT_ISSUE Enables printing of /etc/issue in daemon mode.

PRINT_MOTD Enables printing of default motd, static motd or dynamic motd.

DEFAULT_USER Preselected user, if AUTOLOGIN is enabled, this user is logged in.

DEFAULT_SESSION Preselected desktop session, if user does not use emptty file. Has lower priority than AUTOLOGIN_SESSION

DEFAULT_SESSION_ENV Optional environment of preselected desktop session, if user does not use emptty file. Possible values are "xorg" and "wayland".

AUTOLOGIN Enables Autologin, if DEFAULT_USER is defined. Possible values are "true" or "false". Default value is false. NOTE: to enable autologin DEFAULT_USER must be in group nopasswdlogin, otherwise user will NOT be authorized.

AUTOLOGIN_SESSION The default session used, if Autologin is enabled. If session is not found in list of session, it proceeds to manual selection.

AUTOLOGIN_SESSION_ENV Optional environment of autologin desktop session. Possible values are "xorg" and "wayland".

AUTOLOGIN_MAX_RETRY If Autologin is enabled and session does not start correctly, the number of retries in short period is kept to eventually stop the infinite loop of restarts. -1 is for infinite retries, 0 is for no retry. Default value is 2.

LANG defines locale for all users. Default value is "en_US.UTF-8"

DBUS_LAUNCH Starts "dbus-launch" before desktop command. After end of session "dbus-daemon" is interrupted. Default value is true. If user config is handled as script (does not contain Exec option), this config is overridden to false.

ALWAYS_DBUS_LAUNCH Starts "dbus-launch" before desktop command in any case, DBUS_LAUNCH value is ignored. It also starts even if XINITRC_LAUNCH is set to true. After end of session "dbus-daemon" is interrupted. Default value is false.

XINITRC_LAUNCH Starts Xorg desktop with calling "~/.xinitrc" script with session exec as argument, if is true, file exists and selected WM/DE is Xorg session, it overrides DBUS_LAUNCH. If user config is handled as script (does not contain Exec option), this config is overridden to false.

VERTICAL_SELECTION Prints available WM/DE each on new line instead of printing on single line.

LOGGING Defines the way, how is logging handled. Possible values are "rotate", "appending" or "disabled". Default value is "rotate".

LOGGING_FILE Overrides path of log file. Default value is /var/log/emptty/[TTY_NUMBER].log. NOTE: It expects existence of directories to defined logging file.

XORG_ARGS Arguments passed to Xorg server.

DYNAMIC_MOTD Allows to use dynamic motd script to generate custom MOTD. Possible values are "true" or "false". Default value is false. NOTE: Be sure, that dynamic motd has correct content and permissions (e.g. 744), the script is started as default user; in daemon mode it means root.

DYNAMIC_MOTD_PATH Allows to override default path to dynamic motd. Default value is /etc/emptty/motd-gen.sh

MOTD_PATH Allows to override default path to static motd. Default value is /etc/emptty/motd

FG_COLOR Foreground color, available only in daemon mode. List of colors is listed below.

BG_COLOR Background color, available only in daemon mode. List of colors is listed below.

DISPLAY_START_SCRIPT Script started before Display (Xorg/Wayland) starts. NOTE: The script is started as default user; in daemon mode it means root.

DISPLAY_STOP_SCRIPT Script started after Display (Xorg/Wayland) stops. NOTE: The script is started as default user; in daemon mode it means root.

ENABLE_NUMLOCK Enables numlock in daemon mode. Possible values are "true" or "false". Default value is false.

SESSION_ERROR_LOGGING Defines how logging of session errors is handled. Possible values are "rotate", "appending" or "disabled". Default value is "disabled".

SESSION_ERROR_LOGGING_FILE Overrides path of session errors log file. Default value is /var/log/emptty/session-errors.[TTY_NUMBER].log. NOTE: It expects existence of directories to defined logging file.

NO_XDG_FALLBACK Disallows setting of fallback values for all XDG environmental variables and leaves it on Login Controls. Possible values are "true" or "false". Default value is false. NOTE: Be aware, that setting to "true" could lead to unexpected behaviour.

DEFAULT_XAUTHORITY If set true, it will not use .emptty-xauth file, but the standard ~/.Xauthority file. This allows to handle xauth issues. Possible values are "true" or "false". Default value is false.

ROOTLESS_XORG If set true, Xorg will be started as rootless, if system allows and emptty is running in daemon mode. Possible values are "true" or "false". Default value is false. NOTE: Rootless Xorg requires additional changes changes in Xorg config.

IDENTIFY_ENVS If set true, environmental groups are printed to differ Xorg/Wayland/Custom/UserCustom desktops. Possible values are "true" or "false". Default value is false.

HIDE_ENTER_LOGIN If set true, "hostname login:" is not displayed. Possible values are "true" or "false". Default value is false.

HIDE_ENTER_PASSWORD If set true, "Password:" is not displayed. Possible values are "true" or "false". Default value is false.

XORG_SESSIONS_PATH Path to directory, where Xorg sessions' desktop files are stored. Default value is "/usr/share/xsessions/".

WAYLAND_SESSIONS_PATH Path to directory, where Wayland sessions' desktop files are stored. Default value is "/usr/share/wayland-sessions/".

SELECT_LAST_USER Enables funtionality of saving last successfully logged in user for next login. Possible values are "false", "per-tty" or "global". Default value is false.

AUTO_SELECTION If set to "true" and only one desktop is available, it automatically select that desktop. Possible values are "true" or "false". Default value is false.

ALLOW_COMMANDS If set to "true" and no default user is selected, it allows to enter commands into login input. Possible values are "true" or "false", Default value is true.

CMD_POWEROFF Command to be used to perform poweroff. Default value is "poweroff".

CMD_REBOOT Command to be used to perform reboot. Default value is "reboot".

CMD_SUSPEND Command to be used to perform suspend. Default value is blank, but it tries to use "systemctl suspend", "loginctl suspend" or "zzz".

Commands

If commands are allowed and default user is not defined, there could be used commands in login input. All of these commands need to start with colon :. Escape characters are ignored to prevent issues with muscle memory from VI.

  • :help, :? prints available commands
  • :poweroff, :shutdown processess poweroff command
  • :reboot processes reboot command
  • :suspend, :zzz processes suspend command

Dynamic MOTD

If DYNAMIC_MOTD is set to true, this file exists and is executable for its owner, the result is printed as your own MOTD. Be very careful with this script!

Static MOTD

Custom file, that prints your own MOTD. Reading this file supports colors (e.g. \x1b[31m or \033[32m).

User Config (${HOME}/.config/emptty or ${HOME}/.emptty)

Optional configuration file, that could be also handled as shell script. If is not presented, emptty shows selection of installed desktops. Configuration file stored as ${HOME}/.config/emptty has higher priority on loading. See samples

Name Optional name to be used as Session Name.

Exec Defines command to start Desktop Environment/Window Manager. It could contain multiple arguments same as in *.desktop files. This value does not need to be defined, if user config file is presented as shell script (with shebang at the start and execution permissions).

Environment Selects, which environment should be defined for following command. Possible values are "xorg" and "wayland", "xorg" is default.

Lang Defines locale for logged user, has higher priority than LANG from global configuration

Selection Requires selection of desktop, basically turns emptty file into .xinitrc for Xorg and Wayland. In this case Exec is skipped. Possible values are "false" for never using selection, "true" for always showing selection or "auto" for showing selection or first option autoselect, if there is no other desktop. Defauls value is false.

LoginShell Defines custom shell to be used to start the session. This allows to start the session with non-interactive shell e.g. /bin/bash --login

DesktopNames Value passed into XDG_CURRENT_DESKTOP variable.

User Exit Script ${HOME}/.config/emptty-exit

Optional script file, that is handled as shell script and is started, when session is going end. Script is started even if emptty is being terminated. The default timeout to finish script is 3 seconds, but it is configurable from the script itself by setting variable Timeout.

Timeout Optional custom timeout for script to finish its run, number represents seconds. Default is 3.

/etc/emptty/custom-sessions/ or ${HOME}/.config/emptty-custom-sessions/

Optional folders for custom sessions, that could be available system-wide (in case of /etc/emptty/custom-sessions/) or user-specific (in case of ${HOME}/.config/emptty-custom-sessions/), but do not have .desktop file stored on standard paths for Xorg or Wayland sessions. Expected suffix of each file is ".desktop". See samples

Name Defines name of Desktop Environment/Window Manager.

Exec Defines command to start Desktop Environment/Window Manager.

Environment Selects, which environment should be defined for following command. Possible values are "xorg" and "wayland", "xorg" is default.

DesktopNames Value passed into XDG_CURRENT_DESKTOP variable.

NoDisplay / Hidden Boolean value, that controls visibility of desktop session.

${HOME}./xinitrc

If config XINITRC_LAUNCH is set to true, it enables possibility to use .xinitrc script. See samples

Colors

Please, be aware that LIGHT_ colors could be unavailable as background color.

List of colors
  • BLACK
  • RED
  • GREEN
  • YELLOW
  • BLUE
  • PURPLE
  • CYAN
  • WHITE
  • LIGHT_BLACK
  • LIGHT_RED
  • LIGHT_GREEN
  • LIGHT_YELLOW
  • LIGHT_BLUE
  • LIGHT_PURPLE
  • LIGHT_CYAN
  • LIGHT_WHITE

Rootless Xorg

If Rootless Xorg does not work as expected, make sure you have set following lines in your /etc/X11/Xwrapper.config.

needs_root_rights = no
allowed_users = anybody

Logging

As it is mentioned in configuration, there are three options to handle logging of emptty. The logs contains not just logs from emptty, but also from Xorg (if used) and user's WM/DE. Described log location could differ according configuration LOGGING_FILE, that is stored in /etc/emptty/conf.

rotate

This option provides simple solution, when current instance of emptty logs into /var/log/emptty/[TTY_NUMBER].log and the previous version is stored as /var/log/emptty/[TTY_NUMBER].log.old.

NOTE: Current instance always move previous log into old file, if emptty crashes and is started again, previous log is in /var/log/emptty/[TTY_NUMBER].log.old.

appending

This option provides functionality that logs everything into /var/log/emptty/[TTY_NUMBER].log and does not handle log rotation by itself. It leaves the option for user to handle it themselves (e.g. with logrotate).

NOTE: Appending without roration could cause large log file, be sure that log file is rotated.

disabled

This option points all log into /dev/null, so no log is available.

NOTE: If any issue starts to appear and you want to report it, ensure you do not use this option.

Build & install

Build dependencies

  • go (>= 1.20)
  • gcc
  • pam-devel
  • libx11-devel (libx11)

Dependencies

  • pam
  • libx11
  • xorg / xorg-server (optional)
  • xauth / xorg-xauth (required for xorg)
  • mcookie (required for xorg)
  • wayland (optional)

Make Commands

  • make clean to cleanup already built binary.
  • make build to build binary and gzip man page.
  • make install to install binary.
  • make install-pam to install pam module.
  • make install-pam-debian to install pam module for Debian.
  • make install-pam-fedora to install pam module for Fedora.
  • make install-pam-suse to install pam module for openSUSE.
  • make install-manual to install man page.
  • make install-all to install binary, pam module and man page.
  • make install-config to create default conf file in /etc/emptty/.
  • make install-dinit to install dinit service.
  • make install-runit to install runit service.
  • make install-runit-artix to install runit to Artix service folder.
  • make install-openrc to install openrc service.
  • make install-s6 to install s6 service.
  • make install-systemd to install systemd service.
  • make install-motd-gen to create default motd-gen.sh in /etc/emptty/.
  • make uninstall to remove emptty from your system

Build tags

Different distros could handle libc dependencies in different ways and emptty have direct references to these libc functions. For these cases there are Build tags to disable incompatible functionality or just to avoid some unwanted dependency. The usage during build is really simple, just add parameter and optional tags split with ",".

$ make build TAGS=tag1,tag2

nopam

This tag disables dependency on PAM. In Linux it switch to basic authentication with shadow.

noxlib

This tag disables dependency on libx11, could be useful, if only Wayland desktop is expected to be used.

noutmp

This tag disables dependency on UTMP/UTMPX. Its implementation is different by each libc/distro, this provides ability to build if incompatibility occurs.