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.5/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>
 110
 111         <xi:include href="version-info.xml" xpointer="v232"/></listitem>
 112       </varlistentry>
 113       <varlistentry>
 114
 115         <term><varname>vconsole.font=</varname></term>
 116         <term><varname>vconsole.font_map=</varname></term>
 117         <term><varname>vconsole.font_unimap=</varname></term>
 118
 119         <listitem><para>Overrides <varname>FONT=</varname>, <varname>FONT_MAP=</varname>, and
 120         <varname>FONT_UNIMAP=</varname>.</para>
 121
 122         <xi:include href="version-info.xml" xpointer="v232"/></listitem>
 123       </varlistentry>
 124     </variablelist>
 125   </refsect1>
 126
 127   <refsect1>
 128     <title>Example</title>
 129
 130     <example>
 131       <title>German keyboard and console</title>
 132
 133       <para><filename>/etc/vconsole.conf</filename>:</para>
 134
 135       <programlisting>KEYMAP=de-latin1
 136 FONT=eurlatgr</programlisting>
 137     </example>
 138
 139   </refsect1>
 140
 141   <refsect1>
 142       <title>See Also</title>
 143       <para><simplelist type="inline">
 144         <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 145         <member><citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 146         <member><citerefentry project='mankier'><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 147         <member><citerefentry project='die-net'><refentrytitle>setfont</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 148         <member><citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 149         <member><citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 150       </simplelist></para>
 151   </refsect1>
 152
 153 </refentry>