emptty.1

.TH EMPTTY 1 "August 2022" "emptty 0.8.1" emptty

.SH NAME
emptty \- Dead simple CLI Display Manager on TTY

.SH SYNOPSIS
.B emptty [-v] [--version] [-d] [--daemon] [-c PATH] [--config PATH] [-i] [--ignore-config] [-t TTY] [--tty TTY] [-u defaultUser] [--default-user defaultUser] [-a [session]] [--autologin [session]]

.SH DESCRIPTION
.B emptty
Simple CLI Display Manager, that allows to select DE/WM after login, use predefined config or allows autologin, if selected user is part of
.I nopasswdlogin
group.

.SH OPTIONS
.IP "\-v, \-\-version"
Display the version of the program.

.IP "\-d, \-\-daemon"
Starts emptty as daemon, that does not require agetty.

.IP "\-c, \-\-config PATH"
Loads configuration from specified path.

.IP "\-i, \-\-ignore-config"
Skips loading of configuration from file, loads only argument configuration.

.IP "\-t, \-\-tty TTY"
Overrides loaded configuration by setting defined TTY.

.IP "\-u, \-\-default-user defaultUser"
Overrides loaded configuration by setting defined defaultUser.

.IP "\-a, \-\-autologin [session]"
Overrides loaded configuration by enabling autologin. If session is defined, it overrides autologin session.

.SH CONFIG
/etc/emptty/conf

.IP TTY_NUMBER
TTY, where emptty will start.
.IP SWITCH_TTY
Enables switching to defined TTY number. Default is true.
.IP PRINT_ISSUE
Enables printing of /etc/issue in daemon mode.
.IP PRINT_MOTD
Enables printing of default motd, static motd or dynamic motd.
.IP DEFAULT_USER
Preselected user, if AUTOLOGIN is enabled, this user is logged in.
.IP DEFAULT_SESSION
Preselected desktop session, if user does not use `emptty` file. Has lower priority than
.I AUTOLOGIN_SESSION
.IP DEFAULT_SESSION_ENV
Optional environment of preselected desktop session, if user does not use `emptty` file. Possible values are "xorg" and "wayland".
.IP AUTOLOGIN
Enables Autologin, if DEFAULT_USER is defined. Possible values are "true" or "false". Default value is false.

.B NOTE:
to enable autologin DEFAULT_USER must be in group
.I nopasswdlogin
, otherwise user will NOT be authorized.
.IP AUTOLOGIN_SESSION
The default session used, if Autologin is enabled. If session is not found in list of session, it proceeds to manual selection.
.IP AUTOLOGIN_SESSION_ENV
Optional environment of autologin desktop session. Possible values are "xorg" and "wayland".
.IP 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.
.IP LANG
defines locale for all users. Default value is "en_US.UTF-8"
.IP DBUS_LAUNCH
Starts "dbus-launch" before desktop command. After end of session "dbus-daemon" is interrupted. Default value is true. If
.I user config
is handled as script (does not contain
.I Exec
option), this config is overriden to false.
.IP ALWAYS_DBUS_LAUNCH
Starts "dbus-launch" before desktop command in any case,
.I DBUS_LAUNCH
value is ignored. It also starts even if
.I
XINITRC_LAUNCH
is set to `true`. After end of session "dbus-daemon" is interrupted. Default value is false.
.IP XINITRC_LAUNCH
Starts Xorg desktop with calling
.I ~/.xinitrc
script with session exec as argument, if is true, file exists and selected WM/DE is Xorg session, it overrides DBUS_LAUNCH. If
.I user config
is handled as script (does not contain
.I Exec
option), this config is overriden to false.
.IP VERTICAL_SELECTION
Prints available WM/DE each on new line instead of printing on single line.
.IP LOGGING
Defines how logging is handled. Possible values are "default", "appending" or "disabled". Default value is "default".
.IP LOGGING_FILE
Overrides path of log file. Default value is
.I /var/log/emptty/[TTY_NUMBER].log

.B NOTE:
It expects existence of directories to defined logging file.

.IP XORG_ARGS
Arguments passed to Xorg server.
.IP DYNAMIC_MOTD
Allows to use dynamic motd script to generate custom MOTD. Possible values are "true" or "false". Default value is false.

.B 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
.I root

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

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

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

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

.IP DISPLAY_START_SCRIPT
Script started before Display (Xorg/Wayland) starts.

.B NOTE:
The script is started as default user; in daemon mode it means
.I root

.IP DISPLAY_STOP_SCRIPT
Script started after Display (Xorg/Wayland) stops.

.B NOTE:
The script is started as default user; in daemon mode it means
.I root

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

.IP SESSION_ERROR_LOGGING
Defines how logging of session errors is handled. Possible values are "default", "appending" or "disabled". Default value is "disabled".
.IP SESSION_ERROR_LOGGING_FILE
Overrides path of session errors log file. Default value is
.I /var/log/emptty/session-errors.[TTY_NUMBER].log

.B NOTE:
It expects existence of directories to defined logging file.
.IP 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.

.B NOTE:
Be aware, that setting to "true" could lead to unexpected behaviour.

.IP 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.

.IP 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.

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

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

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

.SH DYNAMIC MOTD
Optional file stored by default as /etc/emptty/motd-gen.sh. Could be overriden.

If
.IDYNAMIC_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!

.SH CUSTOM MOTD
Optional file stored by default as /etc/emptty/motd. Could be overriden.

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

.SH USER CONFIG
Optional file stored as ${HOME}/.config/emptty or ${HOME}/.emptty

Configuration file stored as ${HOME}/.config/emptty has higher priority on loading.
.IP Name
Optional name to be used as Session Name.
.IP Exec
Defines command to start Desktop Environment/Window Manager. This value does not need to be defined, if user config is presented as shell script (with shebang at the start and execution permissions).
.IP Environment
Selects, which environment should be defined for following command. Possible values are "xorg" and "wayland", "xorg" is default.
.IP Lang
Defines locale for logged user, has higher priority than LANG from global configuration
.IP Selection
Requires selection of desktop, basically turns
.I emptty
file into
.I .xinitrc
for Xorg and Wayland. In this case
.I Exec
is skipped.
.IP 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"

.SH 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".

.IP Name
Defines name of Desktop Environment/Window Manager.
.IP Exec
Defines command to start Desktop Environment/Window Manager. It could contain multiple arguments same as in *.desktop files.
.IP Environment
Selects, which environment should be defined for following command. Possible values are "xorg" and "wayland", "xorg" is default.

.SH LAST SESSION
The last user selection of session is stored into ~/.cache/emptty/last-session

.SH 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
.I LOGGING_FILE
, that is stored in
.I /etc/emptty/conf

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

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

.IP appending
This option provides functionality that logs everything into
.I /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).

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

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

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

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

BLACK, RED, GREEN, YELLOW, BLUE, PURPLE, CYAN, WHITE

LIGHT_BLACK, LIGHT_RED, LIGHT_GREEN, LIGHT_YELLOW, LIGHT_BLUE, LIGHT_PURPLE, LIGHT_CYAN, LIGHT_WHITE