kmscon - Man Page

• Start kmscon on the first available TTY, as reported by fgconsole --next-available: sudo kmscon
• Start kmscon in a specific TTY: sudo kmscon --vt /dev/ttyX|ttyX|X
• Enable mouse support: sudo kmscon --mouse
• Specify the command to use for login: sudo kmscon [-l|--login] command
• Always start kmscon in a specific terminal: systemctl enable --now kmsconvt@ttyX

tldr.sh

kmscon [Options...]

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

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, multi-seat support and more​.

When run in listener mode, kmscon watches the system for new seats and automatically provides a system console on it​.

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

General Options:

-h,  --help

Prints a short help text and exits​. (default: off)

-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/)

--listen

Run kmscon in listen-mode​. See section below for more information​. (default: off)

Seat Options:

--vt {/path/to/vt}

Use this VT​. 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​.

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's 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)

--seats {list,of,seats}

List of seats kmscon will run on​. Use 'all' to make kmscon run on all seats​. Use 'all,' to make kmscon run on a seat called 'all' (empty entries are ignored)​. Use 'current' to make kmscon run on the current seat​. (default: "current")

If kmscon runs on multiple seats, all seats are independent of each other​. You can either run a different kmscon process on ecah 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)​.

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 use to create new sessions, kill sessions and switch sessions via keyboard input​. (default: off)

--terminal-session

Start a terminal session after setup is done​. (default: on)

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)

This example starts '/bin/bash -i' on each new terminal session: ​./kmscon --login --debug --no-switchvt -- /bin/bash -i

-t {term}, --term {term}

This changes the $TERM environment variable that is set on new terminal sessions​. (default: xterm-256color)

--reset-env

Reset environment before spawning the child process​. (default: on)

--palette {name}

Change the default color-palette​. This shouldn't be used anymore​. Dynamic color palettes should be implemented instead​.

--sb-size {size}

Maximum scrollback-buffer line count​. (default: 1000)

Input Options:

--xkb-model {model}

Keyboard model​. This should normally not be changed​. (default: {xkb default})

--xkb-layout {layout}

Keyboard layout​. (default: {xkb default})

German keyboard example: --xkb-layout=de

--xkb-variant {variant}

Keyboard variant​. (default: {xkb default})

--xkb-options {options}

Keyboard 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-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)

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 exists 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 are: 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 next session​. (default: <Ctrl><Logo>Right)

--grab-session-prev {grab}

Switch to previous session​. (default: <Ctrl><Logo>Left)

--grab-session-dummy {grab}

Switch to dummy session (black screen)​. (default: <Ctrl><Logo>Escape)

--grab-session-close {grab}

Close current session (press twice to kill it)​. (default: <Ctrl><Logo>BackSpace)

--grab-terminal-new {grab}

Create new terminal session next to current session​. (default: <Ctrl><Logo>Return)

Video Options:

--drm

Use DRM devices as display devices, too​. fbdev devices are always used, but DRM devices are only used if this option is on​. (default: on)

--hwaccel

Use 3D hardware acceleration​. Note that this should be used in conjunction with --drm​. On newer hardware, this can speed up rendering by multiple orders of magnitude​. However, on older hardware this might even slow down rendering speed​. (default: off)

--gpus {all,aux,primary}

GPU selection algorithm​. If 'all' then all found GPUs are used​. If 'aux' then primary and auxiliary GPUs are used​. If 'primary' then only primary GPUs are used​. Primary GPUs are the default GPU on a seat​. There is always only one primary GPU on a seat​. Auxiliary GPUs are hotpluggable GPUs that provide additional independent displays​. (default: all)

--render-engine {engine}

Select console render engine​. Available engines are 'bblit', 'bbulk' and 'gltex'​. (default: detect by GPU type)

--render-timing

Display timing information of the render engines​. This should only be used to debug render engines​. (default: off)

Font Options:

--font-engine {engine}

Select font-engine​. Available engines are 'pango', 'unifont' and '8x16'​. (default: pango)

--font-size {points}

Font size in points​. (default: 12)

--font-name {name}

Font name​. (default: monospace)

--font-dpi {dpi}

DPI used for font-rendering​. Per monitor DPI values overwrite this global default​. (default: 96)

Default configuration directory is /etc/kmscon/ and the main configuration file is called /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:

      font-name=Meslo LG M
      font-size=14
      login=/bin/bash -i

Command-line options overwrite configuration file options​. And per-seat configuration files overwrite the global configuration file​.

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

By default, kmscon runs on seat0 but you can change the seat via the --seats 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 Listener-Mode to avoid this​.

kmscon spawns login(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 --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​. 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​.

If started in listen-mode (--listen) 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​.

Several options are exclusively limited to listen-mode, other than these, kmscon behaves the same way as in default-mode​.

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

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

Terminal sessions provide a terminal emulator​. They are the main session type and provide all the terminal-emulation functionality​.

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

kmscon.conf(5), console(4)