1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 Written 2012 by David Herrmann <dh.herrmann@googlemail.com>
7 Dedicated to the Public Domain
10 <refentry id="kmscon">
13 <productname>kmscon</productname>
14 <date>December 2012</date>
17 <contrib>Developer</contrib>
18 <firstname>David</firstname>
19 <surname>Herrmann</surname>
20 <email>dh.herrmann@googlemail.com</email>
26 <refentrytitle>kmscon</refentrytitle>
27 <manvolnum>1</manvolnum>
31 <refname>kmscon</refname>
32 <refpurpose>KMS/DRM based System Console</refpurpose>
37 <command>kmscon <arg choice="opt" rep="repeat">OPTIONS</arg></command>
40 <command>kmscon -l <arg choice="opt" rep="repeat">OPTIONS</arg> -- /bin/login <arg choice="opt" rep="repeat">/bin/login-OPTIONS</arg></command>
45 <title>Description</title>
46 <para>kmscon is a KMS/DRM-based system console with an integrated terminal
47 emulator for linux operating systems. It was designed as a replacement
48 for the linux kernel console and virtual terminals.</para>
50 <para>When run in default mode, kmscon allocates a virtual terminal and
51 provides a terminal emulator on it. It can thus be used as replacement
52 for the linux console and
53 <citerefentry><refentrytitle>agetty</refentrytitle><manvolnum>1</manvolnum></citerefentry>
55 Compared to the linux console, kmscon provides a rich set of enhanced
56 features including full internationalized keyboard support, full UTF-8
57 input/font support, hardware-accelerated rendering, multi-seat
58 support and more.</para>
60 <para>When run in listener mode, kmscon watches the system for new seats and
61 automatically provides a system console on it.</para>
65 <title>Options</title>
66 <para>Boolean options take no arguments. If the default value is true, then
67 you can disable the option by prefixing it with
68 <emphasis>no-</emphasis>.</para>
70 <para>General Options:</para>
74 <term><option>-h</option></term>
75 <term><option>--help</option></term>
77 <para>Prints a short help text and exits. (default: off)</para>
82 <term><option>-v</option></term>
83 <term><option>--verbose</option></term>
85 <para>Be more verbose. (default: off)</para>
90 <term><option>--debug</option></term>
92 <para>Print debug messages. Works only if kmscon was compiled with
93 debug mode enabled. (default: off)</para>
98 <term><option>--silent</option></term>
100 <para>Suppress notices and warnings. (default: off)</para>
105 <term><option>--configdir {/path/to/config/dir/}</option></term>
107 <para>Specify path to config directory. (default: /etc/kmscon/)</para>
112 <term><option>--listen</option></term>
114 <para>Run kmscon in listen-mode. See section below for more
115 information. (default: off)</para>
120 <para>Seat Options:</para>
124 <term><option>--vt {/path/to/vt}</option></term>
126 <para>Use this VT. If not specified, kmscon tries to find a VT by
127 itself. On seats without VTs, kmscon simply activates itself
128 automatically without using any VT. Please note that you cannot
129 use this option if kmscon runs on multiple seats
130 (see <option>--seats</option>). To avoid this, specify this
131 option in a seat configuration
132 <filename>/etc/kmscon/{seat}.kmscon.conf</filename>.</para>
133 <para>You must not run multiple applications on a single VT,
134 otherwise, you might get an unresponsive system. Also note, by
135 default, kmscon tries to use it's controlling terminal as VT and
136 if that fails, it tries to allocate a new unused VT.</para>
141 <term><option>--switchvt</option></term>
143 <para>If kmscon is started on a VT that is currently not active, this
144 option makes kmscon activate this VT during startup. The same
145 way, during shutdown kmscon will reactivate the VT that was
146 previously active. (default: on)</para>
151 <term><option>--seats {list,of,seats}</option></term>
153 <para>List of seats kmscon will run on. Use 'all' to make kmscon run
154 on all seats. Use 'all,' to make kmscon run on a seat called
155 'all' (empty entries are ignored). Use 'current' to make kmscon
156 run on the current seat. (default: "current")</para>
158 <para>If kmscon runs on multiple seats, all seats are independent of
159 each other. You can either run a different kmscon process on
160 ecah seat or make a single kmscon process run on multiple seats.
161 In the latter case, global state can be shared to reduce memory
162 consumption (like glyph-caches).</para>
167 <para>Session Options:</para>
171 <term><option>--session-max {num}</option></term>
173 <para>Change the maximum number of sessions that are allowed on each
174 seat. Use '0' for no limit. (default: 50)</para>
179 <term><option>--session-control</option></term>
181 <para>Allow keyboard-shortcuts to control the session manager. This
182 allows the use to create new sessions, kill sessions and switch
183 sessions via keyboard input. (default: off)</para>
188 <term><option>--terminal-session</option></term>
190 <para>Start a terminal session after setup is done.
196 <para>Terminal Options:</para>
200 <term><option>-l</option></term>
201 <term><option>--login</option></term>
203 <para>Specify the application that is started on new terminal
204 sessions. This takes no argument but instead everything left
205 after all options have been parsed is used as argument to this
206 option. Note that nothing after two dashes <option>--</option>
207 is parsed as regular option by kmscon.
208 (default: /bin/login -p)</para>
210 <para>This example starts '/bin/bash -i' on each new terminal session:
211 ./kmscon --login --debug --no-switchvt -- /bin/bash -i</para>
216 <term><option>-t {term}</option></term>
217 <term><option>--term {term}</option></term>
219 <para>This changes the <varname>$TERM</varname> environment variable
220 that is set on new terminal sessions.
221 (default: xterm-256color)</para>
226 <term><option>--reset-env</option></term>
228 <para>Reset environment before spawning the child process.
234 <term><option>--palette {name}</option></term>
236 <para>Change the default color-palette. This shouldn't be used
237 anymore. Dynamic color palettes should be implemented
243 <term><option>--sb-size {size}</option></term>
245 <para>Maximum scrollback-buffer line count. (default: 1000)</para>
250 <para>Input Options:</para>
254 <term><option>--xkb-model {model}</option></term>
256 <para>Keyboard model. This should normally not be changed.
257 (default: {xkb default})</para>
262 <term><option>--xkb-layout {layout}</option></term>
264 <para>Keyboard layout. (default: {xkb default})</para>
265 <para>German keyboard example: --xkb-layout=de</para>
270 <term><option>--xkb-variant {variant}</option></term>
272 <para>Keyboard variant. (default: {xkb default})</para>
277 <term><option>--xkb-options {options}</option></term>
279 <para>Keyboard options. (default: {xkb default})</para>
284 <term><option>--xkb-keymap {file}</option></term>
286 <para>Path to a single predefined keymap file. This takes precedence
287 over the above options. An empty path "" is interpreted as not
288 using a keymap. (default: not used)</para>
293 <term><option>--xkb-repeat-delay {delay}</option></term>
295 <para>Delay after key was pressed until key-repeat starts (in
296 milliseconds). (default: 250)</para>
301 <term><option>--xkb-repeat-rate {rate}</option></term>
303 <para>Time between two key-repeats (in milliseconds).
309 <para>Grabs / Keyboard-Shortcuts:</para>
310 <para>All keyboard shortcuts (here: grabs) in kmscon can be modified with
311 these options. The argument to such an option is a list of
313 keyboard-shortcuts that should trigger the specified action. To
314 disable a shortcut, pass an empty argument (empty list). A keyboard
315 shortcut exists of a list of modifiers followed by a single key. All
316 modifiers must be down when the key is pressed for the shortcut to be
317 detected. A modifier is surrounded by '<' and '>' (like
318 '<shift>'). A key is the name of a keysym (like 'a' or
319 'Return'). Keysyms are case-sensitive and kmscon will suggest a keysym
320 name if you entered a wrong case. However, kmscon can not always guess
321 the right case as lower-case-only keysyms are ambiguous.</para>
323 <para>If a key generates multiple keysyms in your keyboard layout, you can
324 match these keys by concatenating the keysyms with a '+' (like
325 'H+E+L+L+O'). This does not mean that all the listed keys must be
326 pressed! It's rather a way to match multi-keysym keys.</para>
328 <para>Valid modifiers are: Shift, Control/Ctrl, Alt, Logo (Windows/Apple
333 <term><option>--grab-scroll-up {grab}</option></term>
335 <para>Scroll up in scrollback buffer by one line.
336 (default: <Shift>Up)</para>
341 <term><option>--grab-scroll-down {grab}</option></term>
343 <para>Scroll down in scrollback buffer by one line.
344 (default: <Shift>Down)</para>
349 <term><option>--grab-page-up {grab}</option></term>
351 <para>Scroll up in scrollback buffer by one page.
352 (default: <Shift>Prior/PageUp)</para>
357 <term><option>--grab-page-down {grab}</option></term>
359 <para>Scroll down in scrollback buffer by one page.
360 (default: <Shift>Next/PageDown)</para>
365 <term><option>--grab-zoom-in {grab}</option></term>
367 <para>Increase font size of the current terminal.
368 (default: <Ctrl>Plus)</para>
373 <term><option>--grab-zoom-out {grab}</option></term>
375 <para>Decrease font size of the current terminal.
376 (default: <Ctrl>Minus)</para>
381 <term><option>--grab-session-next {grab}</option></term>
383 <para>Switch to next session.
384 (default: <Ctrl><Logo>Right)</para>
389 <term><option>--grab-session-prev {grab}</option></term>
391 <para>Switch to previous session.
392 (default: <Ctrl><Logo>Left)</para>
397 <term><option>--grab-session-dummy {grab}</option></term>
399 <para>Switch to dummy session (black screen).
400 (default: <Ctrl><Logo>Escape)</para>
405 <term><option>--grab-session-close {grab}</option></term>
407 <para>Close current session (press twice to kill it).
408 (default: <Ctrl><Logo>BackSpace)</para>
413 <term><option>--grab-terminal-new {grab}</option></term>
415 <para>Create new terminal session next to current session.
416 (default: <Ctrl><Logo>Return)</para>
421 <para>Video Options:</para>
425 <term><option>--drm</option></term>
427 <para>Use DRM devices as display devices, too. fbdev devices are
428 always used, but DRM devices are only used if this option is on.
434 <term><option>--hwaccel</option></term>
436 <para>Use 3D hardware acceleration. Note that this should be used in
437 conjunction with <option>--drm</option>. On newer hardware, this
438 can speed up rendering by multiple orders of magnitude. However,
439 on older hardware this might even slow down rendering speed.
440 (default: off)</para>
445 <term><option>--gpus {all,aux,primary}</option></term>
447 <para>GPU selection algorithm. If 'all' then all found GPUs are used.
448 If 'aux' then primary and auxiliary GPUs are used. If 'primary'
449 then only primary GPUs are used. Primary GPUs are the default
450 GPU on a seat. There is always only one primary GPU on a seat.
451 Auxiliary GPUs are hotpluggable GPUs that provide additional
452 independent displays. (default: all)</para>
457 <term><option>--render-engine {engine}</option></term>
459 <para>Select console render engine. Available engines are 'bblit',
460 'bbulk' and 'gltex'. (default: detect by GPU type)</para>
465 <term><option>--render-timing</option></term>
467 <para>Display timing information of the render engines. This should
468 only be used to debug render engines. (default: off)</para>
473 <para>Font Options:</para>
477 <term><option>--font-engine {engine}</option></term>
479 <para>Select font-engine. Available engines are 'pango', 'freetype2',
480 'unifont' and '8x16'. (default: pango)</para>
485 <term><option>--font-size {points}</option></term>
487 <para>Font size in points. (default: 12)</para>
492 <term><option>--font-name {name}</option></term>
494 <para>Font name. (default: monospace)</para>
499 <term><option>--font-dpi {dpi}</option></term>
501 <para>DPI used for font-rendering. Per monitor DPI values overwrite
502 this global default. (default: 96)</para>
509 <title>Configuration</title>
510 <para>Default configuration directory is <filename>/etc/kmscon/</filename>
511 and the main configuration file is called
512 <filename>/etc/kmscon/kmscon.conf</filename>. You can provide an
513 additional configuration file for each seat via
514 <filename>/etc/kmscon/{seatname}.kmscon.conf</filename>.
515 Any command-line option that can be passed to kmscon can also be put
516 into those configuration files. For example:</para>
524 <para>Command-line options overwrite
525 configuration file options. And per-seat configuration files overwrite
526 the global configuration file.</para>
530 <title>Default Mode</title>
531 <para>In default mode, kmscon acts as a replacement for
532 <citerefentry><refentrytitle>agetty</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
533 kmscon opens a virtual terminal and
534 provides a system console on it. It replaces the linux-console on this
535 VT. You can select the virtual terminal
536 via the <option>--vt</option> option. kmscon will seamlessly integrate
537 into existing setups so you can use X, Wayland or any other Graphics
538 Systems simultaneously. You can even use the linux-console on all the
539 other virtual terminals.</para>
541 <para>By default, kmscon runs on
542 <emphasis>seat0</emphasis> but you can change the seat via the
543 <option>--seats</option> option. For seats without virtual terminals,
544 kmscon will automatically activate itself and run exclusively on that
545 seat. If the virtual terminal or the seat that kmscon
546 runs on is gone, kmscon will automatically exit. See the
547 <emphasis>Listener-Mode</emphasis> to avoid this.</para>
550 <citerefentry><refentrytitle>login</refentrytitle><manvolnum>1</manvolnum></citerefentry>
551 on each new terminal. After a session exits, kmscon automatically
552 respawns the next session. You can change the program that is spawned
553 with the <option>--login</option> option. To stop kmscon, send SIGTERM
554 to the kmscon process.</para>
556 <para>Keyboard input is done by <emphasis>libxkbcommon</emphasis>. This
557 provides the same features as the X11 Keyboard System but without any
558 dependencies on X11 libraries. See the
559 <emphasis>--xkb-{option}</emphasis> options for ways to change the
560 keyboard layout, model, repeat rates and more. For instance
561 <option>--xkb-layout=de</option> changes the keyboard layout to
564 <para>kmscon uses KMS/DRM to access graphics devices (like the X-Server
565 does). Compared to the linux console this allows kmscon to provide
566 much better font-rendering and enhanced monitor control. However, for
567 backwards compatibility, kmscon can also use fbdev devices.
568 Hotpluggable graphics devices are marked as auxiliary devices, primary
569 GPUs on a seat are marked as primary. Other GPUs stay unmarked. By
570 default kmscon uses all graphics devices but you can make it use only
571 primary or auxiliary devices with the <option>--gpus</option>
576 <title>Listener Mode</title>
577 <para>If started in listen-mode (<option>--listen</option>) kmscon will run
578 as system daemon and provide a system console on each seat that shows
579 up if that seat does not have virtual terminals. On seats with virtual
580 terminals you should run kmscon in default mode.</para>
582 <para>Several options are exclusively limited to listen-mode, other than
583 these, kmscon behaves the same way as in default-mode.</para>
587 <title>Sessions</title>
588 <para>If kmscon is active on a seat, the internal session-manager is woken
589 up. At most times, only the terminal-session is active, but kmscon can
590 also support any other session type. You can switch between sessions
591 with keyboard-shortcuts and you can create/destroy sessions during
594 <para>Dummy sessions simply show a black screen and are used if no other
595 session is available. Otherwise, dummy sessions are hidden from the
596 user so they cannot switch to it.</para>
598 <para>Terminal sessions provide a terminal emulator. They are the main
599 session type and provide all the terminal-emulation
600 functionality.</para>
604 <title>Virtual Terminals</title>
605 <para>Historically, linux provides virtual terminals (VT) only on seat
606 <emphasis>seat0</emphasis>. This is because only one VT can be active
607 at a time but in multi-seat environments you want multiple active VTs,
608 one per seat. It is easy to run kmscon on seat0 on a VT, however, if
609 you want to run kmscon on another seat, there are no VTs. This means,
610 you can only run one application that uses graphics devices on these
611 seats. In most environments this is the X-Server. But if you want to
612 run kmscon together with the X-Server (or any other graphics server),
613 you need a mechanism to notify these servers when they are active.
614 This is done via VT APIs on seat0. But note that if the kernel is
615 compiled without CONFIG_VT (which controls whether VTs are available),
616 then even seat0 does not have VTs.</para>
620 <title>See Also</title>
622 <citerefentry><refentrytitle>kmscon.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
623 <citerefentry><refentrytitle>console</refentrytitle><manvolnum>4</manvolnum></citerefentry>