NAME¶

kmscon - KMS/DRM based System Console

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

OPTIONS¶

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

-v, --verbose

--debug

--silent

--configdir {/path/to/config/dir/}

--listen

Seat Options:

--vt {/path/to/vt}

--switchvt

--seats {list,of,seats}

Session Options:

--session-max {num}

--session-control

--terminal-session

Terminal Options:

-l, --login

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

--reset-env

--sb-size {size}

Input Options:

--xkb-model {model}

--xkb-layout {layout}

--xkb-variant {variant}

--xkb-options {options}

--xkb-keymap {file}

--xkb-compose-file {file}

--xkb-repeat-delay {delay}

--xkb-repeat-rate {rate}

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}

--grab-scroll-down {grab}

--grab-page-up {grab}

--grab-page-down {grab}

--grab-zoom-in {grab}

--grab-zoom-out {grab}

--grab-session-next {grab}

--grab-session-prev {grab}

--grab-session-dummy {grab}

--grab-session-close {grab}

--grab-terminal-new {grab}

Video Options:

--drm

--hwaccel

--gpus {all,aux,primary}

--render-engine {engine}

--render-timing

Font Options:

--font-engine {engine}

--font-size {points}

--font-name {name}

--font-dpi {dpi}

Palette Options:

--palette {name}

In the following options color is an RGB color value written as three comma-separated integers between 0 and 255 inclusive.

--palette-black {color}

--palette-red {color}

--palette-green {color}

--palette-yellow {color}

--palette-blue {color}

--palette-magenta {color}

--palette-cyan {color}

--palette-light-grey {color}

--palette-dark-grey {color}

--palette-light-red {color}

--palette-light-green {color}

--palette-light-yellow {color}

--palette-light-blue {color}

--palette-light-magenta {color}

--palette-light-cyan {color}

--palette-white {color}

--palette-foreground {color}

--palette-background {color}

CONFIGURATION¶

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


      palette-foreground=255, 0, 0


    

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

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.

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.

LISTENER MODE¶

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.

SESSIONS¶

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.

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

SEE ALSO¶

console(4), Compose(5)