'\" t .\" Title: kmscon .\" Author: David Herrmann .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: October 2024 .\" Manual: KMSCON .\" Source: KMSCON .\" Language: English .\" .TH "KMSCON" "1" "October 2024" "KMSCON" "KMSCON" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" kmscon \- KMS/DRM based System Console .SH "SYNOPSIS" .HP \w'\fBkmscon\ \fR\fB[OPTIONS...]\fR\ 'u \fBkmscon \fR\fB[OPTIONS...]\fR .HP \w'\fBkmscon\ \-l\ \fR\fB[OPTIONS...]\fR\fB\ \-\-\ /bin/login\ \fR\fB[/bin/login\-OPTIONS...]\fR\ 'u \fBkmscon \-l \fR\fB[OPTIONS...]\fR\fB \-\- /bin/login \fR\fB[/bin/login\-OPTIONS...]\fR .SH "DESCRIPTION" .PP KMSCON is a KMS/DRM\-based system console with an integrated terminal emulator for Linux operating systems\&. It was designed as a replacement for the Linux kernel console and virtual terminals\&. .PP When run in default mode, KMSCON allocates a virtual terminal and provides a terminal emulator on it\&. It can thus be used as replacement for the Linux console and \fBagetty\fR(1) on virtual terminals\&. Compared to the Linux console, KMSCON provides a rich set of enhanced features including full internationalized keyboard support, full UTF\-8 input/font support, hardware\-accelerated rendering, multi\-seat support and more\&. .PP When run in listener mode, KMSCON watches the system for new seats and automatically provides a system console on it\&. .SH "OPTIONS" .PP Boolean options take no arguments\&. If the default value is true, then you can disable the option by prefixing it with \fIno\-\fR\&. .PP General Options: .PP \fB\-h\fR, \fB\-\-help\fR .RS 4 Print a short help text and exit\&. .RE .PP \fB\-V\fR, \fB\-\-version\fR .RS 4 Print version information and exit\&. When combined with \fB\-\-verbose\fR, additional build information is shown including compilation date and time, and enabled build options (DRM 2D/3D support, FBDEV support, Pango font support)\&. .RE .PP \fB\-v\fR, \fB\-\-verbose\fR .RS 4 Be more verbose\&. (default: off) .RE .PP \fB\-\-debug\fR .RS 4 Print debug messages\&. Works only if KMSCON was compiled with debug mode enabled\&. (default: off) .RE .PP \fB\-\-silent\fR .RS 4 Suppress notices and warnings\&. (default: off) .RE .PP \fB\-\-configdir {/path/to/config/dir/}\fR .RS 4 Specify path to config directory\&. (default: /etc/kmscon) .RE .PP \fB\-\-listen\fR .RS 4 Run KMSCON in listen\-mode\&. See section below for more information\&. (default: off) .RE .PP Seat Options: .PP \fB\-\-vt {/path/to/vt|ttyX|X}\fR .RS 4 Use this VT\&. The argument is either the full path `/dev/ttyX\*(Aq, the device name `ttyX\*(Aq or just the tty number\&. If not specified, KMSCON tries to find a VT by itself\&. On seats without VTs, KMSCON simply activates itself automatically without using any VT\&. Please note that you cannot use this option if KMSCON runs on multiple seats (see \fB\-\-seats\fR)\&. To avoid this, specify this option in a seat configuration /etc/kmscon/{seat}\&.kmscon\&.conf\&. .sp You must not run multiple applications on a single VT, otherwise, you might get an unresponsive system\&. Also note, by default, KMSCON tries to use it\*(Aqs controlling terminal as VT and if that fails, it tries to allocate a new unused VT\&. .RE .PP \fB\-\-switchvt\fR .RS 4 If KMSCON is started on a VT that is currently not active, this option makes KMSCON activate this VT during startup\&. The same way, during shutdown KMSCON will reactivate the VT that was previously active\&. (default: on) .RE .PP \fB\-\-seats {list,of,seats}\fR .RS 4 List of seats KMSCON will run on\&. Use `all\*(Aq to make KMSCON run on all seats\&. Use `all,\*(Aq to make KMSCON run on a seat called `all\*(Aq (empty entries are ignored)\&. Use `current\*(Aq to make kmscon run on the current seat\&. (default: current) .sp If KMSCON runs on multiple seats, all seats are independent of each other\&. You can either run a different KMSCON process on each seat or make a single KMSCON process run on multiple seats\&. In the latter case, global state can be shared to reduce memory consumption (like glyph\-caches)\&. .RE .PP Session Options: .PP \fB\-\-session\-max {num}\fR .RS 4 Change the maximum number of sessions that are allowed on each seat\&. Use \*(Aq0\*(Aq for no limit\&. (default: 50) .RE .PP \fB\-\-session\-control\fR .RS 4 Allow keyboard\-shortcuts to control the session manager\&. This allows the user to create new sessions, kill sessions and switch sessions via keyboard input\&. (default: off) .RE .PP \fB\-\-terminal\-session\fR .RS 4 Start a terminal session after setup is done\&. (default: on) .RE .PP Terminal Options: .PP \fB\-l\fR, \fB\-\-login\fR .RS 4 Specify the application that is started on new terminal sessions\&. This takes no argument but instead everything left after all options have been parsed is used as argument to this option\&. Note that nothing after two dashes \fB\-\-\fR is parsed as regular option by kmscon\&. (default: /bin/login \-p) .sp If this option is specified in the configuration file, the argument is split into words using the rules of the POSIX shell\&. It is possible to include whitespace in arguments by enclosing the argument in double or single quotes or by prepending it with a backslash\&. .sp This example starts \*(Aq/bin/bash \-i\*(Aq on each new terminal session: \&./kmscon \-\-login \-\-debug \-\-no\-switchvt \-\- /bin/bash \-i .RE .PP \fB\-t {term}\fR, \fB\-\-term {term}\fR .RS 4 Specify the \fI$TERM\fR environment variable that is set on new terminal sessions\&. (default: xterm\-256color) .RE .PP \fB\-\-reset\-env\fR .RS 4 Reset environment before spawning the child process\&. (default: on) .RE .PP \fB\-\-backspace\-delete\fR .RS 4 Send delete character when backspace is pressed\&. (default: on) .RE .PP \fB\-\-sb\-size {size}\fR .RS 4 Specify the size of the scrollback buffer (in lines)\&. (default: 1000) .RE .PP Input Options: .PP \fB\-\-xkb\-model {model}\fR .RS 4 Specify the keyboard (xkb) model\&. This should normally not be changed\&. (default: {xkb default}) .RE .PP \fB\-\-xkb\-layout {layout}\fR .RS 4 Specify the keyboard (xkb) layout\&. (default: {xkb default}) .sp German keyboard example: \-\-xkb\-layout=de .RE .PP \fB\-\-xkb\-variant {variant}\fR .RS 4 Speicfy the keyboard (xkb) variant\&. (default: {xkb default}) .RE .PP \fB\-\-xkb\-options {options}\fR .RS 4 Specify other keyboard (xkb) options\&. (default: {xkb default}) .RE .PP \fB\-\-xkb\-keymap {file}\fR .RS 4 Path to a single predefined keymap file\&. This takes precedence over the above options\&. An empty path "" is interpreted as not using a keymap\&. (default: not used) .RE .PP \fB\-\-xkb\-compose\-file {file}\fR .RS 4 Path to a single predefined compose file\&. An empty path "" is interpreted as using the default compose file\&. The default compose file search order is described in \fBCompose\fR(5)\&. The locale is determined from the first of \fBLC_ALL\fR, \fBLC_CTYPE\fR, or \fBLANG\fR that\*(Aqs set to a non\-empty value\&. If the locale cannot be determined, C is assumed\&. If no compose file is found, composing is disabled\&. (default: search the compose file corresponding to the current locale) .RE .PP \fB\-\-xkb\-repeat\-delay {delay}\fR .RS 4 Delay after key was pressed until key\-repeat starts (in milliseconds)\&. (default: 250) .RE .PP \fB\-\-xkb\-repeat\-rate {rate}\fR .RS 4 Time between two key repeats (in milliseconds)\&. (default: 50) .RE .PP \fB\-\-mouse\fR .RS 4 Enable mouse/touchpad/trackpoint in kmscon (default: on)\&. It allows to select, and copy/paste text with a pointing device, and also to scroll with the mouse wheel\&. It\*(Aqs still experimental, and may not work with specific devices\&. .RE .PP \fB\-\-dpms\-timeout\fR .RS 4 Set screen timeout in seconds (default: 0 = disabled)\&. When enabled, the screen will automatically turn off (DPMS OFF) after the specified period of keyboard and mouse inactivity\&. Any keyboard or mouse input will turn the screen back on and reset the timer\&. This feature is useful for power saving on systems where the screen is not always needed\&. .RE .PP Grabs / Keyboard Shortcuts: .PP All keyboard shortcuts (here: grabs) in KMSCON can be modified with these options\&. The argument to such an option is a list of comma\-separated keyboard shortcuts that should trigger the specified action\&. .PP To disable a shortcut, pass an empty argument (empty list)\&. A keyboard shortcut consists of a list of modifiers followed by a single key\&. All modifiers must be down when the key is pressed for the shortcut to be detected\&. A modifier is surrounded by \*(Aq<\*(Aq and \*(Aq>\*(Aq (like \*(Aq\*(Aq)\&. A key is the name of a keysym (like \*(Aqa\*(Aq or \*(AqReturn\*(Aq)\&. Keysyms are case\-sensitive and KMSCON will suggest a keysym name if you entered a wrong case\&. However, KMSCON can not always guess the right case as lower\-case\-only keysyms are ambiguous\&. .PP If a key generates multiple keysyms in your keyboard layout, you can match these keys by concatenating the keysyms with a \*(Aq+\*(Aq (like \*(AqH+E+L+L+O\*(Aq)\&. This does not mean that all the listed keys must be pressed! It\*(Aqs rather a way to match multi\-keysym keys\&. .PP Valid modifiers: Shift, Control/Ctrl, Alt, Logo (Windows/Apple key)\&. .PP \fB\-\-grab\-scroll\-up {grab}\fR .RS 4 Scroll up in scrollback buffer by one line\&. (default: Up) .RE .PP \fB\-\-grab\-scroll\-down {grab}\fR .RS 4 Scroll down in scrollback buffer by one line\&. (default: Down) .RE .PP \fB\-\-grab\-page\-up {grab}\fR .RS 4 Scroll up in scrollback buffer by one page\&. (default: Prior/PageUp) .RE .PP \fB\-\-grab\-page\-down {grab}\fR .RS 4 Scroll down in scrollback buffer by one page\&. (default: Next/PageDown) .RE .PP \fB\-\-grab\-zoom\-in {grab}\fR .RS 4 Increase font size of the current terminal\&. (default: plus) .RE .PP \fB\-\-grab\-zoom\-out {grab}\fR .RS 4 Decrease font size of the current terminal\&. (default: minus) .RE .PP \fB\-\-grab\-session\-next {grab}\fR .RS 4 Switch to the next session\&. (default: Right) .RE .PP \fB\-\-grab\-session\-prev {grab}\fR .RS 4 Switch to the previous session\&. (default: Left) .RE .PP \fB\-\-grab\-session\-dummy {grab}\fR .RS 4 Switch to a dummy session (blank screen)\&. (default: Escape) .RE .PP \fB\-\-grab\-session\-close {grab}\fR .RS 4 Press twice to close the current session\&. (default: BackSpace) .RE .PP \fB\-\-grab\-terminal\-new {grab}\fR .RS 4 Create new terminal session next to current session\&. (default: Return) .RE .PP \fB\-\-grab\-rotate\-cw {grab}\fR .RS 4 Rotate output clock\-wise: Normal \-> Right \-> Inverted \-> Left and so on\&. (default: Plus) .RE .PP \fB\-\-grab\-rotate\-ccw {grab}\fR .RS 4 Rotate output counter\-clock\-wise: Normal \-> Left \-> Inverted \-> Right and so on\&. (default: Minus) .RE .PP \fB\-\-grab\-reboot {grab}\fR .RS 4 Reboot the system when this keyboard shortcut is pressed\&. This option is disabled by default (no default key binding)\&. Use with caution as the reboot is immediate without confirmation\&. Example: \-\-grab\-reboot=Delete (default: disabled) .RE .PP Video Options: .PP \fB\-\-drm\fR .RS 4 Use DRM (direct rendering manager) devices (usually GPUs) as display devices\&. fbdev (framebuffer) devices are always used, but DRM devices are only used if this option is enabled\&. (default: on) .RE .PP \fB\-\-hwaccel\fR .RS 4 Use 3D hardware acceleration\&. On newer hardware, this can speed up rendering by multiple orders of magnitude\&. However, on older hardware this might slow down rendering speed\&. (default: off) .sp Note: This option should be enabled in conjunction with \fB\-\-drm\fR .RE .PP \fB\-\-gpus {all,aux,primary}\fR .RS 4 Specify which GPU(s) could be used for terminal output\&. If `all\*(Aq is specified, then all GPUs found are used\&. If `aux\*(Aq is specified, then both primary and auxiliary GPUs are used\&. If `primary\*(Aq is specified, then only primary GPUs are used\&. (default: all) .sp Note: Primary GPUs are the default GPU on a seat\&. There is always only one primary GPU on a seat\&. Auxiliary GPUs are hot\- pluggable GPUs that provide additional independent displays\&. .RE .PP \fB\-\-use\-original\-mode\fR .RS 4 Use original KMS mode to prevent modesetting\&. (default: on) .sp This option is incompatible with \-\-mode\&. .RE .PP \fB\-\-mode {width}x{height}\fR .RS 4 Set the desired output mode\&. The given width and height must match a supported more exactly for this option to have any effect; if there is no supported mode that matches exactly, or if there is an error when using the desired mode, then the default mode (first valid mode found) will be used\&. .sp \-\-use\-original\-mode must be disabled in order to use this option\&. .sp Modesetting is only supported in DRM mode, so this option does nothing with fbdev\&. However, fbset can still be used to externally set the mode when fbdev is in use\&. .sp Other system components may need configuration in order to use the desired mode effectively\&. For example, the `video={width}x{height}` kernel parameter may be required in order to ensure that there is enough memory to store the framebuffers for a large resolution\&. .RE .PP \fB\-\-rotate {orientation}\fR .RS 4 Select the desired orientation of the output\&. Available orientations are \*(Aqnormal\*(Aq meaning output is not rotated, \*(Aqright\*(Aq meaning output is rotated 90\(de clock\-wise, \*(Aqupside\-down\*(Aq meaning output is rotated 180\(de clock\-wise and \*(Aqleft\*(Aq meaning output is rotated 90\(de counter clock\-wise\&. This has only effect for the \*(Aqgltex\*(Aq render\-engine\&. (default: \*(Aqnormal\*(Aq) .RE .PP Font Options: .PP \fB\-\-font\-engine {engine}\fR .RS 4 Specify the font rendering engine\&. Available engines are `pango\*(Aq, `unifont\*(Aq, and `8x16\*(Aq\&. (default: pango) .RE .PP \fB\-\-font\-size {points}\fR .RS 4 Font size in points (pt)\&. (default: 12) .RE .PP \fB\-\-font\-name {name}\fR .RS 4 Name of the font to be used, note that Fontconfig fallback may be used if the `pango\*(Aq font rendering engine is specified\&. (default: monospace) .RE .PP \fB\-\-font\-dpi {dpi}\fR .RS 4 DPI (dots\-per\-inch) used for font\-rendering\&. Per monitor DPI values override this global default\&. (default: 96) .RE .PP Palette Options: .PP \fB\-\-palette {name}\fR .RS 4 Specify the default color palette\&. Specify custom to make use of the color palette from the following options\&. .RE .PP In the following options, \fIcolors\fR are specified in RGB color value, written in three comma\-separated integers between 0 and 255 inclusive\&. .PP \fB\-\-palette\-black {color}\fR .RS 4 Specify the black color in the custom palette to \fIcolor\fR\&. (default: 0, 0, 0) .RE .PP \fB\-\-palette\-red {color}\fR .RS 4 Specify the red color in the custom palette to \fIcolor\fR\&. (default: 205, 0, 0) .RE .PP \fB\-\-palette\-green {color}\fR .RS 4 Specify the green color in the custom palette to \fIcolor\fR\&. (default: 0, 205, 0) .RE .PP \fB\-\-palette\-yellow {color}\fR .RS 4 Specify the yellow color in the custom palette to \fIcolor\fR\&. (default: 205, 205, 0) .RE .PP \fB\-\-palette\-blue {color}\fR .RS 4 Specify the blue color in the custom palette to \fIcolor\fR\&. (default: 0, 0, 238) .RE .PP \fB\-\-palette\-magenta {color}\fR .RS 4 Specify the magenta color in the custom palette to \fIcolor\fR\&. (default: 205, 0, 205) .RE .PP \fB\-\-palette\-cyan {color}\fR .RS 4 Specify the cyan color in the custom palette to \fIcolor\fR\&. (default: 0, 205, 205) .RE .PP \fB\-\-palette\-light\-grey {color}\fR .RS 4 Specify the light grey color in the custom palette to \fIcolor\fR\&. (default: 229, 229, 229) .RE .PP \fB\-\-palette\-dark\-grey {color}\fR .RS 4 Specify the dark grey color in the custom palette to \fIcolor\fR\&. (default: 127, 127, 127) .RE .PP \fB\-\-palette\-light\-red {color}\fR .RS 4 Specify the light red color in the custom palette to \fIcolor\fR\&. (default: 255, 0, 0) .RE .PP \fB\-\-palette\-light\-green {color}\fR .RS 4 Specify the light green color in the custom palette to \fIcolor\fR\&. (default: 0, 255, 0) .RE .PP \fB\-\-palette\-light\-yellow {color}\fR .RS 4 Specify the light yellow color in the custom palette to \fIcolor\fR\&. (default: 255, 255, 0) .RE .PP \fB\-\-palette\-light\-blue {color}\fR .RS 4 Specify the light blue color in the custom palette to \fIcolor\fR\&. (default: 92, 92, 255) .RE .PP \fB\-\-palette\-light\-magenta {color}\fR .RS 4 Specify the light magenta color in the custom palette to \fIcolor\fR\&. (default: 255, 0, 255) .RE .PP \fB\-\-palette\-light\-cyan {color}\fR .RS 4 Specify the light cyan color in the custom palette to \fIcolor\fR\&. (default: 0, 255, 255) .RE .PP \fB\-\-palette\-white {color}\fR .RS 4 Specify the white color in the custom palette to \fIcolor\fR\&. (default: 255, 255, 255) .RE .PP \fB\-\-palette\-foreground {color}\fR .RS 4 Specify the default foreground color in the custom palette to \fIcolor\fR\&. (default: 229, 229, 229) .RE .PP \fB\-\-palette\-background {color}\fR .RS 4 Specify the default background color in the custom palette to \fIcolor\fR\&. (default: 0, 0, 0) .RE .SH "CONFIGURATION" .PP The default configuration directory is /etc/kmscon and the main configuration file is named /etc/kmscon/kmscon\&.conf\&. You can provide an additional configuration file for each seat via /etc/kmscon/{seatname}\&.kmscon\&.conf\&. Any command\-line option that can be passed to KMSCON can also be put into those configuration files\&. For example: .sp .if n \{\ .RS 4 .\} .nf font\-name=Meslo LG M font\-size=14 login=/bin/bash \-i palette\-foreground=255, 0, 0 .fi .if n \{\ .RE .\} .PP Command\-line options override configuration file options\&. And per\-seat configuration files override the global configuration file\&. .SH "DEFAULT MODE" .PP In default mode, KMSCON acts as a replacement for \fBagetty\fR(1)\&. KMSCON opens a virtual terminal and provides a system console on it\&. It replaces the linux\-console on this VT\&. You can select the virtual terminal via the \fB\-\-vt\fR option\&. KMSCON will seamlessly integrate into existing setups so you can use X, Wayland or any other Graphics Systems simultaneously\&. You can even use the linux\-console on all the other virtual terminals\&. .PP By default, KMSCON runs on \fIseat0\fR but you can change the seat via the \fB\-\-seats\fR option\&. For seats without virtual terminals, KMSCON will automatically activate itself and run exclusively on that seat\&. If the virtual terminal or the seat that kmscon runs on is gone, KMSCON will automatically exit\&. See the \fIListener\-Mode\fR to avoid this\&. .PP KMSCON spawns \fBlogin\fR(1) on each new terminal\&. After a session exits, KMSCON automatically respawns the next session\&. You can change the program that is spawned with the \fB\-\-login\fR option\&. To stop kmscon, send SIGTERM to the KMSCON process\&. .PP Keyboard input is done by \fIlibxkbcommon\fR\&. This provides the same features as the X11 Keyboard System but without any dependencies on X11 libraries\&. See the \fI\-\-xkb\-{option}\fR options for ways to change the keyboard layout, model, repeat rates and more\&. For instance \fB\-\-xkb\-layout=de\fR changes the keyboard layout to German\&. .PP KMSCON uses KMS/DRM to access graphics devices (like the X\-Server does)\&. Compared to the Linux console this allows KMSCON to provide much better font\-rendering and enhanced monitor control\&. However, for backwards compatibility, KMSCON can also use fbdev devices\&. Hotpluggable graphics devices are marked as auxiliary devices, primary GPUs on a seat are marked as primary\&. Other GPUs stay unmarked\&. By default KMSCON uses all graphics devices but you can make it use only primary or auxiliary devices with the \fB\-\-gpus\fR option\&. .SH "LISTENER MODE" .PP If started in listen\-mode (\fB\-\-listen\fR), KMSCON will run as system daemon and provide a system console on each seat that shows up if that seat does not have virtual terminals\&. On seats with virtual terminals you should run KMSCON in default mode\&. .PP Several options are exclusively limited to listen\-mode, other than these, KMSCON behaves the same way as in default\-mode\&. .SH "SESSIONS" .PP If KMSCON is active on a seat, the internal session\-manager is woken up\&. At most times, only the terminal\-session is active, but KMSCON can also support any other session type\&. You can switch between sessions with keyboard\-shortcuts and you can create/destroy sessions during runtime\&. .PP Dummy sessions simply show a black screen and are used if no other session is available\&. Otherwise, dummy sessions are hidden from the user so they cannot switch to it\&. .PP Terminal sessions provide a terminal emulator\&. They are the main session type and provide all the terminal\-emulation functionality\&. .SH "VIRTUAL TERMINALS" .PP Historically, Linux provides virtual terminals (VT) only on seat \fIseat0\fR\&. This is because only one VT can be active at a time but in multi\-seat environments you want multiple active VTs, one per seat\&. It is easy to run KMSCON on seat0 on a VT, however, if you want to run KMSCON on another seat, there are no VTs\&. This means, you can only run one application that uses graphics devices on these seats\&. In most environments this is the X\-Server\&. But if you want to run KMSCON together with the X\-Server (or any other graphics server), you need a mechanism to notify these servers when they are active\&. This is done via VT APIs on seat0\&. But note that if the kernel is compiled without CONFIG_VT (which controls whether VTs are available), then even seat0 does not have VTs\&. .SH "SEE ALSO" .PP \fBconsole\fR(4), \fBCompose\fR(5)