KMSCON(1)

📦
version 10.1.0 · 8 versions
, in arch rolling

💅 KMSCON(1) — KMS/DRM based System Console 💅

🎀 NAME 🎀

okay so bestie, this is kmscon — the KMS/DRM based System Console 💖. And yes, the manual name is literally right there: KMSCON(1), slay.

✨ SYNOPSIS ✨

kmscon [OPTIONS...]

kmscon -l [OPTIONS...] -- /bin/login [/bin/login-OPTIONS...]

🌸 DESCRIPTION 🌸

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

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 agetty(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, seat support and more. literally iconic 💅

💖 OPTIONS 💖

Boolean options take no arguments. If the default value is true, then you can disable the option by prefixing it with no-. noted, bestie 🫶

🌸 General Options 🌸

  • -h, --help — Print a short help text and exit. easy peasy ✨
  • -V, --version — Print version information and exit. When combined with --verbose, additional build information is shown including compilation date and time, and enabled build options (DRM 2D/3D support, FBDEV support, Freetype font support). 💖
  • -v, --verbose — Be more verbose. (default: off)
  • --debug — Print debug messages. Works only if KMSCON was compiled with debug mode enabled. (default: off)
  • --silent — Suppress notices and warnings. (default: off)
  • --configdir {/path/to/config/dir/} — Specify path to config directory. (default: /etc/kmscon)

🪑 Seat Options 🪑

  • --vt {/path/to/vt|ttyX|X} — Use this VT. The argument is either the full path /dev/ttyX, the device name ttyX 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 --seats). To avoid this, specify this option in a seat configuration /etc/kmscon/{seat}.kmscon.conf.
bestie, this is important: 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 its controlling terminal as VT and if that fails, it tries to allocate a new unused VT. 💀
  • --switchvt — 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)
  • --libseat — Use libseat for seat management, input and video devices. This option is only available if KMSCON was compiled with libseat support. Use --no-libseat to disable it. (default: off)

🫶 Session Options 🫶

  • --session-max {num} — Change the maximum number of sessions that are allowed on each seat. Use '0' for no limit. (default: 50)
  • --session-control — 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)

🎀 Terminal Options 🎀

  • -l, --login — 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 -- is parsed as regular option by kmscon. (default: /bin/login -p)

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.

This example starts /bin/bash -i on each new terminal session:

./kmscon --login --debug --no-switchvt -- /bin/bash -i
  • --oneshot — When the login process exits, exit kmscon. This is useful for setup scripts, or asking for disk encryption. (default: off)
  • -t {term}, --term {term} — Specify the $TERM environment variable that is set on new terminal sessions. (default: kmscon)
  • --reset-env — Reset environment before spawning the child process. (default: on)
  • --issue — Display issue files before the login prompt. Use --no-issue to let the login process handle it. (default: on)
  • --issue-path — Colon-separated list of issue files and directories to read, ordered by precedence. It implements uapi masking, so if there are multiple files, with the same name, only the first will be parsed. (default: "/etc/issue:/etc/issue.d:/run/issue:/run/issue.d:/usr/lib/issue:/usr/lib/issue.d")
  • --asciicast {path} — Play an asciicast animation after opening the terminal session. The animation is stopped on keyboard input. (default: unset)
  • --asciicast-loop — Loop the asciicast animation. (default: off)
  • --backspace-delete — Send delete character when backspace is pressed. (default: on)
  • --sb-size {size} — Specify the size of the scrollback buffer (in lines). (default: 1000)
  • --bell — Enable bell forwarding to the VT. When enabled, the BEL character (0x07) from applications is forwarded to the underlying VT. (default: off)
  • --blink — Enable cursor and text blink. When enabled, the cursor will blink on the screen, and text with blink attribute will blink too. (default: on)

🦋 Input Options 🦋

  • --xkb-model {model} — Specify the keyboard (xkb) model. This should normally not be changed. (default: {xkb default})
  • --xkb-layout {layout} — Specify the keyboard (xkb) layout. (default: {xkb default})

German keyboard example: --xkb-layout=de

  • --xkb-variant {variant} — Specify the keyboard (xkb) variant. (default: {xkb default})
  • --xkb-options {options} — Specify other keyboard (xkb) options. (default: {xkb default})
  • --xkb-keymap {file} — 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)
  • --xkb-compose-file {file} — 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 Compose(5). The locale is determined from the first of LC_ALL, LC_CTYPE, or LANG that's 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)
  • --xkb-repeat-delay {delay} — Delay after key was pressed until key-repeat starts (in milliseconds). (default: 250)
  • --xkb-repeat-rate {rate} — Time between two key repeats (in milliseconds). (default: 50)
  • --mouse — 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's still experimental, and may not work with specific devices. 🙈
  • --soft-cursor — Force software cursor, if hardware cursor is not working properly. (default: off)
  • --dpms-timeout — Set screen timeout in seconds (default: 600 = 10 minutes). 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. Set to 0 to disable. 💤

💅 Grabs / Keyboard Shortcuts 💅

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.

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 < and > (like <shift>). A key is the name of a keysym (like a or Return). 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.

If a key generates multiple keysyms in your keyboard layout, you can match these keys by concatenating the keysyms with a + (like H+E+L+L+O). This does not mean that all the listed keys must be pressed! It's rather a way to match multi-keysym keys.

Valid modifiers: Shift, Control/Ctrl, Alt, Logo (Windows/Apple key).

  • --grab-scroll-up {grab} — Scroll up in scrollback buffer by one line. (default: <Shift>Up)
  • --grab-scroll-down {grab} — Scroll down in scrollback buffer by one line. (default: <Shift>Down)
  • --grab-page-up {grab} — Scroll up in scrollback buffer by one page. (default: <Shift>Prior/PageUp)
  • --grab-page-down {grab} — Scroll down in scrollback buffer by one page. (default: <Shift>Next/PageDown)
  • --grab-zoom-in {grab} — Increase font size of the current terminal. (default: <Ctrl>plus)
  • --grab-zoom-out {grab} — Decrease font size of the current terminal. (default: <Ctrl>minus)
  • --grab-session-next {grab} — Switch to the next session. (default: <Ctrl><Logo>Right)
  • --grab-session-prev {grab} — Switch to the previous session. (default: <Ctrl><Logo>Left)
  • --grab-session-close {grab} — Press twice to close the current session. (default: <Ctrl><Logo>BackSpace)
  • --grab-terminal-new {grab} — Create new terminal session next to current session. (default: <Ctrl><Logo>Return)
  • --grab-rotate-cw {grab} — Rotate output clock-wise: Normal -> Right -> Inverted -> Left and so on. (default: <Logo>Plus)
  • --grab-rotate-ccw {grab} — Rotate output counter-clock-wise: Normal -> Left -> Inverted -> Right and so on. (default: <Logo>Minus)
  • --grab-reboot {grab} — 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=<Ctrl><Alt>Delete (default: disabled)
⚠️ okay bestie, that reboot grab is not a vibe to enable casually — immediate reboot, no confirmation.

🌈 Video Options 🌈

  • --drm — 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)
  • --hwaccel — turns on 3D hardware acceleration ✨ on newer hardware this can speed up rendering by multiple orders of magnitude, which honestly? iconic. but bestie, warning 🫶 on older hardware it might actually make rendering slower. (default: off)
💡 note: this one should be enabled in conjunction with --drm — they're a package deal, iykyk.
  • --gpus {all,aux,primary} — picks which GPU(s) are allowed to do terminal output 💅 all means every GPU found gets used. aux means both primary and auxiliary GPUs get used. primary means only primary GPUs get used. (default: all)
🎀 note: primary GPUs are the default GPU on a seat — there is always only one primary GPU on a seat. auxiliary GPUs are the hot-pluggable ones that bring additional independent displays.
  • --use-original-mode — uses the original KMS mode to prevent modesetting, only for drm devices. (default: off)
💀 heads up: this option is incompatible with --mode. pick one, bestie.
  • --mode {gpu}[{connector}]{width}x{height}@{rate} — sets the desired output mode 🌈 for this to do literally anything, the given width, rate and height have to match a supported mode exactly. if there's no supported mode that matches exactly, or if something errors when using the desired mode, then the default mode (the first valid mode found) gets used instead. gpu, connector, and rate are all optional — but if you specify gpu you must also specify the connector, no cap. you can find the name of the gpu and connector by looking at the kmscon logs:
journalctl -u kmsconvt@* | grep display

modesetting is only supported in DRM mode, so this option does nothing at all with fbdev 🙈 however, fbset can still be used to externally set the mode when fbdev is in use.

other system components may need configuration too, so the desired mode actually works effectively 🦋 for example, the video={width}x{height} kernel parameter may be required to make sure there's enough memory to store the framebuffers for a large resolution.

  • --multi-monitor {clone,largest,scaled} — when there's more than one monitor, this controls how they get used 💖

clone: all monitors will have the same size. the smallest monitor is used to determine the size.

largest: the largest monitor is used to determine the size, and the other monitors get disabled. if multiple monitors have the largest size, they all get used.

scaled: all monitors display the same number of columns and rows based on the smallest monitor, with the larger monitors scaling up their font size to fill the screen.

default: scaled

  • --screen {gpu}[{connector}]{config} — selects the desired screen configuration 🎀 gpu and connector are optional; config is one of 'normal', 'upside-down', 'left', 'right' and 'disabled'. if config is 'disabled' then kmscon won't use this display — unless it's the only available display, in which case, well 😭 if gpu/connector aren't specified, this applies to all available displays.

🎨 Font Options:

  • --font-engine {engine} — specifies the font rendering engine. available engines are freetype, pango, unifont, psf, and 8x16. (default: freetype)
  • --font-size {pixels} — font height in pixels. 0 will auto-detect. (default: 0)
  • --font-name {name} — name (or path, for psf) of the font to use 💜 note that Fontconfig fallback may be used if the freetype or pango font rendering engine is specified. (default: monospace)

🌈 Palette Options:

  • --palette {name} — specifies the default color palette. specify custom to make use of the color palette from the following options 👑

in the following options, colors are specified as RGB color values, written as three comma-separated integers between 0 and 255 inclusive 🍓

  • --palette-black {color} — specifies the black color in the custom palette to color. (default: 0, 0, 0)
  • --palette-red {color} — specifies the red color in the custom palette to color. (default: 205, 0, 0)
  • --palette-green {color} — specifies the green color in the custom palette to color. (default: 0, 205, 0)
  • --palette-yellow {color} — specifies the yellow color in the custom palette to color. (default: 205, 205, 0)
  • --palette-blue {color} — specifies the blue color in the custom palette to color. (default: 0, 0, 238)
  • --palette-magenta {color} — specifies the magenta color in the custom palette to color. (default: 205, 0, 205)
  • --palette-cyan {color} — specifies the cyan color in the custom palette to color. (default: 0, 205, 205)
  • --palette-light-grey {color} — specifies the light grey color in the custom palette to color. (default: 229, 229, 229)
  • --palette-dark-grey {color} — specifies the dark grey color in the custom palette to color. (default: 127, 127, 127)
  • --palette-light-red {color} — specifies the light red color in the custom palette to color. (default: 255, 0, 0)
  • --palette-light-green {color} — specifies the light green color in the custom palette to color. (default: 0, 255, 0)
  • --palette-light-yellow {color} — specifies the light yellow color in the custom palette to color. (default: 255, 255, 0)
  • --palette-light-blue {color} — specifies the light blue color in the custom palette to color. (default: 92, 92, 255)
  • --palette-light-magenta {color} — specifies the light magenta color in the custom palette to color. (default: 255, 0, 255)
  • --palette-light-cyan {color} — specifies the light cyan color in the custom palette to color. (default: 0, 255, 255)
  • --palette-white {color} — specifies the white color in the custom palette to color. (default: 255, 255, 255)
  • --palette-foreground {color} — specifies the default foreground color in the custom palette to color. (default: 229, 229, 229)
  • --palette-background {color} — specifies the default background color in the custom palette to color. (default: 0, 0, 0)

📁 CONFIGURATION

the default configuration directory is /etc/kmscon and the main configuration file is named /etc/kmscon/kmscon.conf 🎀 you can also 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 go into those configuration files, periodt. for example:

          font-name=Meslo LG M
          font-size=14
          login=/bin/bash -i
          palette-foreground=255, 0, 0

command-line options override configuration file options 💅 and per-seat configuration files override the global configuration file. hierarchy, bestie.

👑 DEFAULT MODE

in default mode, KMSCON acts as a replacement for agetty(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 --vt 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. the range.

by default, KMSCON runs on the current seat. (often it's seat0). 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. it knows when to leave the group chat.

KMSCON spawns login(1) on each new terminal. after a session exits, KMSCON automatically respawns the next session 🔁 you can change the program that gets spawned with the --login option. to stop kmscon, send SIGTERM to the KMSCON process.

keyboard input is done by libxkbcommon 💖 this provides the same features as the X11 Keyboard System but without any dependencies on X11 libraries. see the --xkb-{option} options for ways to change the keyboard layout, model, repeat rates and more. for instance --xkb-layout=de changes the keyboard layout to German 🇩🇪

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, and other GPUs stay unmarked. by default KMSCON uses all graphics devices, but you can make it use only primary or auxiliary devices with the --gpus option 💅

🧚 SESSIONS

if KMSCON is active on a seat, the internal session-manager is woken up ⭐ at most times, only the terminal-session is active. you can switch between sessions with keyboard-shortcuts, and you can create/destroy terminal sessions during runtime 🙈

terminal sessions provide a terminal emulator. they're the only session type, and they provide all the terminal-emulation functionality. main character energy, honestly.

🖥️ VIRTUAL TERMINALS

historically, Linux provides virtual terminals (VT) only on seat seat0 💀 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's 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're active. this is done via VT APIs on seat0. but note — if the kernel is compiled without CONFIG_VT (which controls whether VTs are available), then even seat0 does not have VTs 🙈

🌸 SEE ALSO

console(4), Compose(5)

and that's the whole page, bestie 🫶 this one's from the KMSCON source, dated October 2024 — go forth and configure your terminals, you absolute icon 💅✨

📦 where this page comes from