man/vconsole.conf.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   8
   9 <refentry id="vconsole.conf" conditional='ENABLE_VCONSOLE'
  10           xmlns:xi="http://www.w3.org/2001/XInclude">
  11   <refentryinfo>
  12     <title>vconsole.conf</title>
  13     <productname>systemd</productname>
  14   </refentryinfo>
  15
  16   <refmeta>
  17     <refentrytitle>vconsole.conf</refentrytitle>
  18     <manvolnum>5</manvolnum>
  19   </refmeta>
  20
  21   <refnamediv>
  22     <refname>vconsole.conf</refname>
  23     <refpurpose>Configuration file for the virtual console</refpurpose>
  24   </refnamediv>
  25
  26   <refsynopsisdiv>
  27     <para><filename>/etc/vconsole.conf</filename></para>
  28   </refsynopsisdiv>
  29
  30   <refsect1>
  31     <title>Description</title>
  32
  33     <para>The <filename>/etc/vconsole.conf</filename> file configures
  34     the virtual console, i.e. keyboard mapping and console font. It is
  35     applied at boot by udev using <filename>90-vconsole.rules</filename> file.
  36     You can safely mask this file if you want to avoid this kind of initialization.
  37     </para>
  38
  39     <para>The format of <filename>vconsole.conf</filename> is a newline-separated list of environment-like
  40     shell-compatible variable assignments, ignoring comments and empty lines. It is possible to source the
  41     configuration from shell scripts, however, beyond mere variable assignments no shell features are
  42     supported, allowing applications to read the file without implementing a shell compatible execution
  43     engine. See
  44     <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> for a
  45     detailed description of the format.</para>
  46
  47     <para>Note that the kernel command line options
  48     <varname>vconsole.keymap=</varname>,
  49     <varname>vconsole.keymap_toggle=</varname>,
  50     <varname>vconsole.font=</varname>,
  51     <varname>vconsole.font_map=</varname>,
  52     <varname>vconsole.font_unimap=</varname> may be used
  53     to override the console settings at boot.</para>
  54
  55     <para>Depending on the operating system other configuration files
  56     might be checked for configuration of the virtual console as well,
  57     however only as fallback.</para>
  58
  59     <para><filename>/etc/vconsole.conf</filename> is usually created and updated
  60     using
  61     <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
  62     <citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  63     may be used to instruct <command>systemd-localed.service</command> to
  64     query or update configuration.</para>
  65   </refsect1>
  66
  67   <refsect1>
  68     <title>Options</title>
  69
  70     <para>The following options are understood:</para>
  71
  72     <variablelist class='environment-variables'>
  73
  74       <varlistentry>
  75         <term><varname>KEYMAP=</varname></term>
  76         <term><varname>KEYMAP_TOGGLE=</varname></term>
  77
  78         <listitem><para>Configures the key mapping table for the keyboard.  <varname>KEYMAP=</varname>
  79         defaults to <literal>&DEFAULT_KEYMAP;</literal> if not set. Specially, if <literal>@kernel</literal>
  80         is specified, no keymap will be loaded, i.e. the kernel's default keymap is used.  The
  81         <varname>KEYMAP_TOGGLE=</varname> can be used to configure a second toggle keymap and is by default
  82         unset.</para></listitem>
  83       </varlistentry>
  84
  85       <varlistentry>
  86         <term><varname>FONT=</varname></term>
  87         <term><varname>FONT_MAP=</varname></term>
  88         <term><varname>FONT_UNIMAP=</varname></term>
  89
  90         <listitem><para>Configures the console font, the console map
  91         and the unicode font map.</para></listitem>
  92       </varlistentry>
  93
  94     </variablelist>
  95   </refsect1>
  96
  97   <refsect1>
  98     <title>Kernel Command Line</title>
  99
 100     <para>A few configuration parameters from <filename>vconsole.conf</filename> may be overridden
 101     on the kernel command line:</para>
 102
 103     <variablelist class='kernel-commandline-options'>
 104       <varlistentry>
 105         <term><varname>vconsole.keymap=</varname></term>
 106         <term><varname>vconsole.keymap_toggle=</varname></term>
 107
 108         <listitem><para>Overrides <varname>KEYMAP=</varname> and <varname>KEYMAP_TOGGLE=</varname>.
 109         </para></listitem>
 110       </varlistentry>
 111       <varlistentry>
 112
 113         <term><varname>vconsole.font=</varname></term>
 114         <term><varname>vconsole.font_map=</varname></term>
 115         <term><varname>vconsole.font_unimap=</varname></term>
 116
 117         <listitem><para>Overrides <varname>FONT=</varname>, <varname>FONT_MAP=</varname>, and
 118         <varname>FONT_UNIMAP=</varname>.</para></listitem>
 119       </varlistentry>
 120     </variablelist>
 121   </refsect1>
 122
 123   <refsect1>
 124     <title>Example</title>
 125
 126     <example>
 127       <title>German keyboard and console</title>
 128
 129       <para><filename>/etc/vconsole.conf</filename>:</para>
 130
 131       <programlisting>KEYMAP=de-latin1
 132 FONT=eurlatgr</programlisting>
 133     </example>
 134
 135   </refsect1>
 136
 137   <refsect1>
 138       <title>See Also</title>
 139       <para>
 140         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 141         <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 142         <citerefentry project='mankier'><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 143         <citerefentry project='die-net'><refentrytitle>setfont</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 144         <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 145         <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 146       </para>
 147   </refsect1>
 148
 149 </refentry>