<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
          "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  Written 2012 by David Herrmann <dh.herrmann@googlemail.com>
  Dedicated to the Public Domain
-->

<!--
  Revised 2024 by Mingcong Bai <jeffbai@aosc.io>
-->

<refentry id="kmscon">
  <refentryinfo>
    <title>KMSCON</title>
    <productname>KMSCON</productname>
    <date>October 2024</date>
    <authorgroup>
      <author>
        <contrib>Developer</contrib>
        <firstname>David</firstname>
        <surname>Herrmann</surname>
        <email>dh.herrmann@googlemail.com</email>
        <contrib>Developer</contrib>
        <firstname>Mingcong</firstname>
        <surname>Bai</surname>
        <email>jeffbai@aosc.io</email>
      </author>
    </authorgroup>
  </refentryinfo>

  <refmeta>
    <refentrytitle>kmscon</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>kmscon</refname>
    <refpurpose>KMS/DRM based System Console</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>kmscon <arg choice="opt" rep="repeat">OPTIONS</arg></command>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>kmscon -l <arg choice="opt" rep="repeat">OPTIONS</arg> -- /bin/login <arg choice="opt" rep="repeat">/bin/login-OPTIONS</arg></command>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>
    <para>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.</para>

    <para>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
          <citerefentry><refentrytitle>agetty</refentrytitle><manvolnum>1</manvolnum></citerefentry>
          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.</para>

    <para>When run in listener mode, KMSCON watches the system for new seats and
          automatically provides a system console on it.</para>
  </refsect1>

  <refsect1>
    <title>Options</title>
    <para>Boolean options take no arguments. If the default value is true, then
          you can disable the option by prefixing it with
          <emphasis>no-</emphasis>.</para>

    <para>General Options:</para>

    <variablelist>
      <varlistentry>
        <term><option>-h</option></term>
        <term><option>--help</option></term>
        <listitem>
          <para>Print a short help text and exit.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-V</option></term>
        <term><option>--version</option></term>
        <listitem>
          <para>Print version information and exit. When combined with
                <option>--verbose</option>, additional build information is shown
                including compilation date and time, and enabled build options
                (DRM 2D/3D support, FBDEV support, Pango font support).</para>
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><option>-v</option></term>
        <term><option>--verbose</option></term>
        <listitem>
          <para>Be more verbose. (default: off)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--debug</option></term>
        <listitem>
          <para>Print debug messages. Works only if KMSCON was compiled with
                debug mode enabled. (default: off)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--silent</option></term>
        <listitem>
          <para>Suppress notices and warnings. (default: off)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--configdir {/path/to/config/dir/}</option></term>
        <listitem>
          <para>Specify path to config directory. (default: @CONFIG_DIR@)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--listen</option></term>
        <listitem>
          <para>Run KMSCON in listen-mode. See section below for more
                information. (default: off)</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>Seat Options:</para>

    <variablelist>
      <varlistentry>
        <term><option>--vt {/path/to/vt|ttyX|X}</option></term>
        <listitem>
          <para>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 <option>--seats</option>). To avoid this,
                specify this option in a seat configuration
                <filename>@CONFIG_DIR@/{seat}.kmscon.conf</filename>.</para>
          <para>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.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--switchvt</option></term>
        <listitem>
          <para>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)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--seats {list,of,seats}</option></term>
        <listitem>
          <para>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)</para>

          <para>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).</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>Session Options:</para>

    <variablelist>
      <varlistentry>
        <term><option>--session-max {num}</option></term>
        <listitem>
          <para>Change the maximum number of sessions that are allowed on each
                seat. Use '0' for no limit. (default: 50)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--session-control</option></term>
        <listitem>
          <para>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)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--terminal-session</option></term>
        <listitem>
          <para>Start a terminal session after setup is done.
                (default: on)</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>Terminal Options:</para>

    <variablelist>
      <varlistentry>
        <term><option>-l</option></term>
        <term><option>--login</option></term>
        <listitem>
          <para>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 <option>--</option>
                is parsed as regular option by kmscon.
                (default: /bin/login -p)</para>

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

          <para>This example starts '/bin/bash -i' on each new terminal session:
                ./kmscon --login --debug --no-switchvt -- /bin/bash -i</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-t {term}</option></term>
        <term><option>--term {term}</option></term>
        <listitem>
          <para>Specify the <varname>$TERM</varname> environment variable
                that is set on new terminal sessions.
                (default: linux)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--reset-env</option></term>
        <listitem>
          <para>Reset environment before spawning the child process.
                (default: on)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--backspace-delete</option></term>
        <listitem>
          <para>Send delete character when backspace is pressed.
                (default: on)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--sb-size {size}</option></term>
        <listitem>
          <para>Specify the size of the scrollback buffer (in lines). (default: 1000)</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>Input Options:</para>

    <variablelist>
      <varlistentry>
        <term><option>--xkb-model {model}</option></term>
        <listitem>
          <para>Specify the keyboard (xkb) model. This should normally not be changed.
                (default: {xkb default})</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--xkb-layout {layout}</option></term>
        <listitem>
          <para>Specify the keyboard (xkb) layout. (default: {xkb default})</para>
          <para>German keyboard example: --xkb-layout=de</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--xkb-variant {variant}</option></term>
        <listitem>
          <para>Speicfy the keyboard (xkb) variant. (default: {xkb default})</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--xkb-options {options}</option></term>
        <listitem>
          <para>Specify other keyboard (xkb) options. (default: {xkb default})</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--xkb-keymap {file}</option></term>
        <listitem>
          <para>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)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--xkb-compose-file {file}</option></term>
        <listitem>
          <para>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
                <citerefentry><refentrytitle>Compose</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
                The locale is determined from the first of
                <envar>LC_ALL</envar>, <envar>LC_CTYPE</envar>, or
                <envar>LANG</envar> that's set to a non-empty value. If the
                locale cannot be determined, <literal>C</literal> is assumed. If
                no compose file is found, composing is disabled. (default:
                search the compose file corresponding to the current
                locale)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--xkb-repeat-delay {delay}</option></term>
        <listitem>
          <para>Delay after key was pressed until key-repeat starts (in
                milliseconds). (default: 250)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--xkb-repeat-rate {rate}</option></term>
        <listitem>
          <para>Time between two key repeats (in milliseconds).
                (default: 50)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--mouse</option></term>
        <listitem>
          <para>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.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--dpms-timeout</option></term>
        <listitem>
          <para>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.
          </para>
        </listitem>
      </varlistentry>

    </variablelist>

    <para>Grabs / Keyboard Shortcuts:</para>
    <para>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.</para>
    <para>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 '&lt;' and '&gt;' (like
          '&lt;shift&gt;'). 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.</para>

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

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

    <variablelist>
      <varlistentry>
        <term><option>--grab-scroll-up {grab}</option></term>
        <listitem>
          <para>Scroll up in scrollback buffer by one line.
                (default: &lt;Shift&gt;Up)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--grab-scroll-down {grab}</option></term>
        <listitem>
          <para>Scroll down in scrollback buffer by one line.
                (default: &lt;Shift&gt;Down)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--grab-page-up {grab}</option></term>
        <listitem>
          <para>Scroll up in scrollback buffer by one page.
                (default: &lt;Shift&gt;Prior/PageUp)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--grab-page-down {grab}</option></term>
        <listitem>
          <para>Scroll down in scrollback buffer by one page.
                (default: &lt;Shift&gt;Next/PageDown)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--grab-zoom-in {grab}</option></term>
        <listitem>
          <para>Increase font size of the current terminal.
                (default: &lt;Ctrl&gt;plus)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--grab-zoom-out {grab}</option></term>
        <listitem>
          <para>Decrease font size of the current terminal.
                (default: &lt;Ctrl&gt;minus)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--grab-session-next {grab}</option></term>
        <listitem>
          <para>Switch to the next session.
                (default: &lt;Ctrl&gt;&lt;Logo&gt;Right)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--grab-session-prev {grab}</option></term>
        <listitem>
          <para>Switch to the previous session.
                (default: &lt;Ctrl&gt;&lt;Logo&gt;Left)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--grab-session-dummy {grab}</option></term>
        <listitem>
          <para>Switch to a dummy session (blank screen).
                (default: &lt;Ctrl&gt;&lt;Logo&gt;Escape)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--grab-session-close {grab}</option></term>
        <listitem>
          <para>Press twice to close the current session.
                (default: &lt;Ctrl&gt;&lt;Logo&gt;BackSpace)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--grab-terminal-new {grab}</option></term>
        <listitem>
          <para>Create new terminal session next to current session.
                (default: &lt;Ctrl&gt;&lt;Logo&gt;Return)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--grab-rotate-cw {grab}</option></term>
        <listitem>
          <para>Rotate output clock-wise: Normal -> Right -> Inverted -> Left and so on.
                (default: &lt;Logo&gt;Plus)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--grab-rotate-ccw {grab}</option></term>
        <listitem>
          <para>Rotate output counter-clock-wise: Normal -> Left -> Inverted -> Right and so on.
                (default: &lt;Logo&gt;Minus)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--grab-reboot {grab}</option></term>
        <listitem>
          <para>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=&lt;Ctrl&gt;&lt;Alt&gt;Delete
                (default: disabled)</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>Video Options:</para>

    <variablelist>
      <varlistentry>
        <term><option>--drm</option></term>
        <listitem>
          <para>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)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--hwaccel</option></term>
        <listitem>
          <para>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)</para>
          <para>Note: This option should be enabled in conjunction with
                <option>--drm</option></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--gpus {all,aux,primary}</option></term>
        <listitem>
          <para>Specify which GPU(s) could be used for terminal output. If `all'
                is specified, then all GPUs found are used. If `aux' is
                specified, then both primary and auxiliary GPUs are used. If
                `primary' is specified, then only primary GPUs are used.
                (default: all)</para>
          <para>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.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--use-original-mode</option></term>
        <listitem>
          <para>Use original KMS mode to prevent modesetting. (default: on)</para>

          <para>This option is incompatible with --mode.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--mode {width}x{height}</option></term>
        <listitem>
          <para>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.</para>

          <para>--use-original-mode must be disabled in order to use this option.</para>

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

          <para>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.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--rotate {orientation}</option></term>
        <listitem>
          <para>Select the desired orientation of the output. Available orientations
                are 'normal' meaning output is not rotated, 'right' meaning output is
                rotated 90° clock-wise, 'upside-down' meaning output is rotated 180°
                clock-wise and 'left' meaning output is rotated 90° counter clock-wise.
                This has only effect for the 'gltex' render-engine. (default: 'normal')
          </para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>Font Options:</para>

    <variablelist>
      <varlistentry>
        <term><option>--font-engine {engine}</option></term>
        <listitem>
          <para>Specify the font rendering engine. Available engines are
                `pango', `unifont', and `8x16'. (default: pango)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--font-size {points}</option></term>
        <listitem>
          <para>Font size in points (pt). (default: 12)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--font-name {name}</option></term>
        <listitem>
          <para>Name of the font to be used, note that Fontconfig fallback may
                be used if the `pango' font rendering engine is specified.
                (default: monospace)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--font-dpi {dpi}</option></term>
        <listitem>
          <para>DPI (dots-per-inch) used for font-rendering. Per monitor DPI
                values override this global default. (default: 96)</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>Palette Options:</para>

    <variablelist>
      <varlistentry>
        <term><option>--palette {name}</option></term>
        <listitem>
          <para>Specify the default color palette. Specify
                <literal>custom</literal> to make use of the color palette from
                the following options.</para>
        </listitem>
      </varlistentry>

      <para>In the following options, <replaceable>colors</replaceable> are
            specified in RGB color value, written in three comma-separated
            integers between 0 and 255 inclusive.</para>

      <varlistentry>
        <term><option>--palette-black {color}</option></term>
        <listitem>
          <para>Specify the black color in the custom palette to
                <replaceable>color</replaceable>.
                (default: 0, 0, 0)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--palette-red {color}</option></term>
        <listitem>
          <para>Specify the red color in the custom palette to
                <replaceable>color</replaceable>.
                (default: 205, 0, 0)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--palette-green {color}</option></term>
        <listitem>
          <para>Specify the green color in the custom palette to
                <replaceable>color</replaceable>.
                (default: 0, 205, 0)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--palette-yellow {color}</option></term>
        <listitem>
          <para>Specify the yellow color in the custom palette to
                <replaceable>color</replaceable>.
                (default: 205, 205, 0)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--palette-blue {color}</option></term>
        <listitem>
          <para>Specify the blue color in the custom palette to
                <replaceable>color</replaceable>.
                (default: 0, 0, 238)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--palette-magenta {color}</option></term>
        <listitem>
          <para>Specify the magenta color in the custom palette to
                <replaceable>color</replaceable>.
                (default: 205, 0, 205)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--palette-cyan {color}</option></term>
        <listitem>
          <para>Specify the cyan color in the custom palette to
                <replaceable>color</replaceable>.
                (default: 0, 205, 205)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--palette-light-grey {color}</option></term>
        <listitem>
          <para>Specify the light grey color in the custom palette to
                <replaceable>color</replaceable>.
                (default: 229, 229, 229)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--palette-dark-grey {color}</option></term>
        <listitem>
          <para>Specify the dark grey color in the custom palette to
                <replaceable>color</replaceable>.
                (default: 127, 127, 127)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--palette-light-red {color}</option></term>
        <listitem>
          <para>Specify the light red color in the custom palette to
                <replaceable>color</replaceable>.
                (default: 255, 0, 0)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--palette-light-green {color}</option></term>
        <listitem>
          <para>Specify the light green color in the custom palette to
                <replaceable>color</replaceable>.
                (default: 0, 255, 0)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--palette-light-yellow {color}</option></term>
        <listitem>
          <para>Specify the light yellow color in the custom palette to
                <replaceable>color</replaceable>.
                (default: 255, 255, 0)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--palette-light-blue {color}</option></term>
        <listitem>
          <para>Specify the light blue color in the custom palette to
                <replaceable>color</replaceable>.
                (default: 92, 92, 255)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--palette-light-magenta {color}</option></term>
        <listitem>
          <para>Specify the light magenta color in the custom palette to
                <replaceable>color</replaceable>.
                (default: 255, 0, 255)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--palette-light-cyan {color}</option></term>
        <listitem>
          <para>Specify the light cyan color in the custom palette to
                <replaceable>color</replaceable>.
                (default: 0, 255, 255)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--palette-white {color}</option></term>
        <listitem>
          <para>Specify the white color in the custom palette to
                <replaceable>color</replaceable>.
                (default: 255, 255, 255)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--palette-foreground {color}</option></term>
        <listitem>
          <para>Specify the default foreground color in the custom
                palette to <replaceable>color</replaceable>.
                (default: 229, 229, 229)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--palette-background {color}</option></term>
        <listitem>
          <para>Specify the default background color in the custom
                palette to <replaceable>color</replaceable>.
                (default: 0, 0, 0)</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Configuration</title>
    <para>The default configuration directory is <filename>@CONFIG_DIR@</filename>
          and the main configuration file is named
          <filename>@CONFIG_DIR@/kmscon.conf</filename>. You can provide an
          additional configuration file for each seat via
          <filename>@CONFIG_DIR@/{seatname}.kmscon.conf</filename>.
          Any command-line option that can be passed to KMSCON can also be put
          into those configuration files.  For example:</para>

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

    <para>Command-line options override
          configuration file options. And per-seat configuration files override
          the global configuration file.</para>
  </refsect1>

  <refsect1>
    <title>Default Mode</title>
    <para>In default mode, KMSCON acts as a replacement for
          <citerefentry><refentrytitle>agetty</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
          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 <option>--vt</option> 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.</para>

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

    <para>KMSCON spawns
          <citerefentry><refentrytitle>login</refentrytitle><manvolnum>1</manvolnum></citerefentry>
          on each new terminal. After a session exits, KMSCON automatically
          respawns the next session. You can change the program that is spawned
          with the <option>--login</option> option. To stop kmscon, send SIGTERM
          to the KMSCON process.</para>

    <para>Keyboard input is done by <emphasis>libxkbcommon</emphasis>. This
          provides the same features as the X11 Keyboard System but without any
          dependencies on X11 libraries. See the
          <emphasis>--xkb-{option}</emphasis> options for ways to change the
          keyboard layout, model, repeat rates and more. For instance
          <option>--xkb-layout=de</option> changes the keyboard layout to
          German.</para>

    <para>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 <option>--gpus</option>
          option.</para>
  </refsect1>

  <refsect1>
    <title>Listener Mode</title>
    <para>If started in listen-mode (<option>--listen</option>), 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.</para>

    <para>Several options are exclusively limited to listen-mode, other than
          these, KMSCON behaves the same way as in default-mode.</para>
  </refsect1>

  <refsect1>
    <title>Sessions</title>
    <para>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.</para>

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

    <para>Terminal sessions provide a terminal emulator. They are the main
          session type and provide all the terminal-emulation
          functionality.</para>
  </refsect1>

  <refsect1>
    <title>Virtual Terminals</title>
    <para>Historically, Linux provides virtual terminals (VT) only on seat
          <emphasis>seat0</emphasis>. 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.</para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <citerefentry><refentrytitle>console</refentrytitle><manvolnum>4</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>Compose</refentrytitle><manvolnum>5</manvolnum></citerefentry>
    </para>
  </refsect1>
</refentry>