source: chapter07/console.xml@ d22a5031

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../general.ent">
  %general-entities;
]>

<sect1 id="ch-scripts-console">
  <?dbhtml filename="console.html"?>

  <title>Configuring the Linux Console</title>

  <indexterm zone="ch-scripts-console">
    <primary sortas="d-console">console</primary>
    <secondary>configuring</secondary>
  </indexterm>

  <indexterm zone="ch-scripts-console">
    <primary sortas="d-consolelog">consolelog</primary>
    <secondary>configuring</secondary>
  </indexterm>

  <para>This section discusses how to configure the <command>console</command>
  bootscript that sets up the keyboard map and the console font. If non-ASCII
  characters (e.g., the copyright sign, the British pound sign and Euro symbol)
  will not be used and the keyboard is a U.S. one, skip this section. Without
  the configuration file, the <command>console</command> bootscript will do
  nothing.</para>

  <para>The <command>console</command> script reads the
  <filename>/etc/sysconfig/console</filename> file for configuration information.
  Decide which keymap and screen font will be used. Various language-specific
  HOWTOs can also help with this, see <ulink
  url="http://www.tldp.org/HOWTO/HOWTO-INDEX/other-lang.html"/>. If still in
  doubt, look in the <filename class="directory">/lib/kbd</filename>
  directory for valid keymaps and screen fonts. Read
  <filename>loadkeys(1)</filename> and <filename>setfont(8)</filename> manual
  pages to determine the correct arguments for these programs.</para>

  <para>The <filename>/etc/sysconfig/console</filename> file should contain lines
  of the form: VARIABLE="value". The following variables are recognized:</para>

  <variablelist>

    <varlistentry>
      <term>KEYMAP</term>
      <listitem>
        <para>This variable specifies the arguments for the
        <command>loadkeys</command> program, typically, the name of keymap
        to load, e.g., <quote>es</quote>. If this variable is not set, the
        bootscript will not run the <command>loadkeys</command> program,
        and the default kernel keymap will be used.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>KEYMAP_CORRECTIONS</term>
      <listitem>
        <para>This (rarely used) variable
        specifies the arguments for the second call to the
        <command>loadkeys</command> program. This is useful if the stock keymap
        is not completely satisfactory and a small adjustment has to be made. E.g.,
        to include the Euro sign into a keymap that normally doesn't have it,
        set this variable to <quote>euro2</quote>.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>FONT</term>
      <listitem>
        <para>This variable specifies the arguments for the
        <command>setfont</command> program. Typically, this includes the font
        name, <quote>-m</quote>, and the name of the application character
        map to load. E.g., in order to load the <quote>lat1-16</quote> font
        together with the <quote>8859-1</quote> application character map
        (as it is appropriate in the USA), <!-- because of the copyright sign -->
        set this variable to <quote>lat1-16 -m 8859-1</quote>.
        If this variable is not set, the bootscript will not run the
        <command>setfont</command> program, and the default VGA font will be
        used together with the default application character map.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>UNICODE</term>
      <listitem>
        <para>Set this variable to <quote>1</quote>, <quote>yes</quote> or
        <quote>true</quote> in order to put the
        console into UTF-8 mode. This is useful in UTF-8 based locales and
        harmful otherwise.</para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>LEGACY_CHARSET</term>
      <listitem>
        <para>For many keyboard layouts, there is no stock Unicode keymap in
        the Kbd package. The <command>console</command> bootscript will
        convert an available keymap to UTF-8 on the fly if this variable is
        set to the encoding of the available non-UTF-8 keymap.</para>
      </listitem>
    </varlistentry>

  </variablelist>

  <para>Some examples:</para>

  <itemizedlist>

    <listitem>
      <para>For a non-Unicode setup, only the KEYMAP and FONT variables are
      generally needed. E.g., for a Polish setup, one would use:</para>

<screen role="nodump"><userinput>cat &gt; /etc/sysconfig/console &lt;&lt; "EOF"
<literal># Begin /etc/sysconfig/console

KEYMAP="pl2"
FONT="lat2a-16 -m 8859-2"

# End /etc/sysconfig/console</literal>
EOF</userinput></screen>
    </listitem>

    <listitem>
      <para>As mentioned above, it is sometimes necessary to adjust a
      stock keymap slightly. The following example adds the Euro symbol to the
      German keymap:</para>

<screen role="nodump"><userinput>cat &gt; /etc/sysconfig/console &lt;&lt; "EOF"
<literal># Begin /etc/sysconfig/console

KEYMAP="de-latin1"
KEYMAP_CORRECTIONS="euro2"
FONT="lat0-16 -m 8859-15"

# End /etc/sysconfig/console</literal>
EOF</userinput></screen>
    </listitem>

    <listitem>
      <para>The following is a Unicode-enabled example for Bulgarian, where a
      stock UTF-8 keymap exists:</para>

<screen role="nodump"><userinput>cat &gt; /etc/sysconfig/console &lt;&lt; "EOF"
<literal># Begin /etc/sysconfig/console

UNICODE="1"
KEYMAP="bg_bds-utf8"
FONT="LatArCyrHeb-16"

# End /etc/sysconfig/console</literal>
EOF</userinput></screen>
    </listitem>

    <listitem>
      <para>Due to the use of a 512-glyph LatArCyrHeb-16 font in the previous
      example, bright colors are no longer available on the Linux console unless
      a framebuffer is used. If one wants to have bright colors without
      framebuffer and can live without characters not belonging to his language,
      it is still possible to use a language-specific 256-glyph font, as
      illustrated below:</para>

<screen role="nodump"><userinput>cat &gt; /etc/sysconfig/console &lt;&lt; "EOF"
<literal># Begin /etc/sysconfig/console

UNICODE="1"
KEYMAP="bg_bds-utf8"
FONT="cyr-sun16"

# End /etc/sysconfig/console</literal>
EOF</userinput></screen>
    </listitem>

    <listitem>
      <para>There is no pre-made UTF-8 Russian keyamp, therefore it has to be
      produced by converting the existing KOI8-R keymap as illustrated
      below:</para>

<screen role="nodump"><userinput>cat &gt; /etc/sysconfig/console &lt;&lt; "EOF"
<literal># Begin /etc/sysconfig/console

UNICODE="1"
KEYMAP="ru_ms"
LEGACY_CHARSET="koi8-r"
FONT="LatArCyrHeb-16"

# End /etc/sysconfig/console</literal>
EOF</userinput></screen>
    </listitem>

    <listitem>
      <para>Some keymaps have dead keys (i.e., keys that don't produce a
      character by themselves, but put an accent on the character produced
      by the next key) or define composition rules (such as: <quote>press
      Ctrl+. A E to get &AElig;</quote> in the default keymap).
      Linux-&linux-version; in UTF-8 keyboard mode assumes that accented
      characters produced via dead keys or composing are in the Latin-1 range
      of Unicode, and it is impossible to change this assumption. Thus,
      accented characters needed for, e.g., the Czech language, can't be typed
      on Linux console in UTF-8 mode (but files containing these characters can
      be displayed correctly). The solution is either to avoid the use of
      UTF-8, or to install the X window system that doesn't have this
      limitation in its input handling.</para>
    </listitem>

    <listitem>
      <para>For Chinese, Japanese, Korean and some other languages, the Linux
      console cannot be configured to display the needed characters. Users
      who need such languages should install the X Window System, fonts that
      cover the necessary character ranges, and the proper input method (e.g.,
      SCIM, it supports a wide variety of languages).</para>
    </listitem>

  </itemizedlist>

  <!-- Added because folks keep posting their console file with X questions
  to blfs-support list -->
  <note>
    <para>The <filename>/etc/sysconfig/console</filename> file only controls the    Linux text console localization. It has nothing to do with setting the
    proper keyboard layout and terminal fonts in the X Window System, with ssh
    sessions or with a serial console. In such situations, limitations mentioned
    in the last two list items above do not apply.</para>
  </note>

</sect1>