From b985e55d3a145aaa616fe3e2002b38365884e00f Mon Sep 17 00:00:00 2001 From: David Herrmann Date: Sun, 9 Dec 2012 13:18:56 +0100 Subject: Add manpage infrastructure and kmscon.1 manpage Add a very basic man-page infrastructure so we can easily add new docbook-style manpages. Also add kmscon.1 man-page with a basic overview. Signed-off-by: David Herrmann --- docs/man/kmscon.xml | 627 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 627 insertions(+) create mode 100644 docs/man/kmscon.xml (limited to 'docs') diff --git a/docs/man/kmscon.xml b/docs/man/kmscon.xml new file mode 100644 index 0000000..e49cd2c --- /dev/null +++ b/docs/man/kmscon.xml @@ -0,0 +1,627 @@ + + + + + + + + kmscon + kmscon + December 2012 + + + Developer + David + Herrmann + dh.herrmann@googlemail.com + + + + + + kmscon + 1 + + + + kmscon + KMS/DRM based System Console + + + + + 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 + agetty1 + 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. + + 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. Command-line options overwrite + configuration file options. And per-seat configuration files overwrite + the global configuration file. + + + + 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: + + + + + + + Prints a short help text and exits. (default: off) + + + + + + + + Be more verbose. (default: off) + + + + + + + Print debug messages. Works only if kmscon was compiled with + debug mode enabled. (default: off) + + + + + + + Suppress notices and warnings. (default: off) + + + + + + + Specify path to config directory. (default: /etc/kmscon/) + + + + + + + Run kmscon in listen-mode. See section below for more + information. (default: off) + + + + + Seat Options: + + + + + + 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 ). 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. + + + + + + + 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) + + Note that this option is required on seats without virtual + terminals, as there is no way to notify kmscon to activate + later. + So disable this option only during debugging or on seats with + virtual terminals. + + + + + + + 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). (default: "seat0") + + 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: + + + + + + Change the maximum number of sessions that are allowed on each + seat. Use '0' for no limit. (default: 50) + + + + + + + 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) + + + + + + + Start a terminal session after setup is done. + (default: on) + + + + + + + Start cdev-VT-emulation session after setup is done. This is + limited to + mode. (default: off) + + + + + Terminal Options: + + + + + + + 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) + + This example starts '/bin/bash -i' on each new terminal session: + ./kmscon --login --debug --no-switchvt -- /bin/bash -i + + + + + + + + This changes the $TERM environment variable + that is set on new terminal sessions. + (default: xterm-256color) + + + + + + + Change the default color-palette. This shouldn't be used + anymore. Dynamic color palettes should be implemented + instead. + + + + + + + Maximum scrollback-buffer line count. (default: 1000) + + + + + Input Options: + + + + + + Keyboard model. This should normally not be changed. + (default: {xkb default}) + + + + + + + Keyboard layout. (default: {xkb default}) + German keyboard example: --xkb-layout=de + + + + + + + Keyboard variant. (default: {xkb default}) + + + + + + + Keyboard options. (default: {xkb default}) + + + + + + + Delay after key was pressed until key-repeat starts (in + milliseconds). (default: 250) + + + + + + + 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 sorrounded 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) + + + + + + Scroll up in scrollback buffer by one line. + (default: <Shift>Up) + + + + + + + Scroll down in scrollback buffer by one line. + (default: <Shift>Down) + + + + + + + Scroll up in scrollback buffer by one page. + (default: <Shift>Prior/PageUp) + + + + + + + Scroll down in scrollback buffer by one page. + (default: <Shift>Next/PageDown) + + + + + + + Switch to next session. + (default: <Ctrl><Logo>Right) + + + + + + + Switch to previous session. + (default: <Ctrl><Logo>Left) + + + + + + + Switch to dummy session (black screen). + (default: <Ctrl><Logo>Escape) + + + + + + + Close current session (press twice to kill it). + (default: <Ctrl><Logo>BackSpace) + + + + + + + Create new terminal session next to current session. + (default: <Ctrl><Logo>Return) + + + + + Video Options: + + + + + + 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) + + + + + + + Use 3D hardware acceleration. Note that this should be used in + conjunction with . 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) + + + + + + + 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) + + + + + + + Select console render engine. Available engines are 'bblit', + 'bbulk' and 'gltex'. (default: detect by GPU type) + + + + + + + Display timing information of the render engines. This should + only be used to debug render engines. (default: off) + + + + + Font Options: + + + + + + Select font-engine. Available engines are 'pango', 'freetype2', + 'unifont' and '8x16'. (default: pango) + + + + + + + Font size in points. (default: 15) + + + + + + + Font name. (default: monospace) + + + + + + + DPI used for font-rendering. Per monitor DPI values overwrite + this global default. (default: 96) + + + + + + + Default Mode + In default mode, kmscon acts as a replacement for + agetty1. + 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. 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 + 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 + login1 + 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. 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 + 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 + option. + + + + Listener Mode + If started in listen-mode () 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. + + CDev sessions provide a way to hook-up external applications as kmscon + sessions. They provide fake virtual terminals on seats that don't have + them so you can switch between multiple graphics applications/servers + without needing VTs. See Virtual Terminals + below. + + + + 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. + + On seats without VTs we need a replacement API. However, a new + API would require modifying every application that uses the VT API to + also support the new replacement if you want to run it on those seats. + Therefore, kmscon provides a backwards-compatible API. It uses the + linux CUSE API to create VTs for all seats that have no VTs. You need + to pass to kmscon to enable this. + kmscon will then create one cdev (character + device) for each seat and calls it + /dev/ttyF{seatname} ('F' for 'fake'). This + character device provides the same API as a VT so your X-Server (or + even kmscon in default-mode) can use it instead of a real VT. + + In contrast to real VTs, each application that opens this fake VT will + get a different VT assigned. So you can use multiple X-Servers all + opening /dev/ttyF{seatname} and they will each + show up as different kmscon session. But note that not all TTY ioctls + are available on fake VTs. kmscon only emulates the API that is + currently used by most VT users. If you want to run an application + that needs more functionality, please open a bug-report. + + Switching VTs is done by signaling the active process to go asleep and + signaling the new VT to wake up. If kmscon emulates VTs, it needs to + be able to send these signals to the processes running on fake VTs. In + most situations this means kmscon must have root priviledges. + + + + See Also + + kmscon.conf5, + console4 + + + -- cgit v1.2.3