man/localectl.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 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="localectl" conditional='ENABLE_LOCALED'
   7     xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>localectl</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>localectl</refentrytitle>
  16     <manvolnum>1</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>localectl</refname>
  21     <refpurpose>Control the system locale and keyboard layout settings</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <cmdsynopsis>
  26       <command>localectl</command>
  27       <arg choice="opt" rep="repeat">OPTIONS</arg>
  28       <arg choice="req">COMMAND</arg>
  29     </cmdsynopsis>
  30   </refsynopsisdiv>
  31
  32   <refsect1>
  33     <title>Description</title>
  34
  35     <para><command>localectl</command> may be used to query and change
  36     the system locale and keyboard layout settings. It communicates with
  37     <citerefentry><refentrytitle>systemd-localed</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  38     to modify files such as <filename>/etc/locale.conf</filename> and
  39     <filename>/etc/vconsole.conf</filename>.</para>
  40
  41     <para>The system locale controls the language settings of system
  42     services and of the UI before the user logs in, such as the
  43     display manager, as well as the default for users after
  44     login.</para>
  45
  46     <para>The keyboard settings control the keyboard layout used on
  47     the text console and of the graphical UI before the user logs in,
  48     such as the display manager, as well as the default for users
  49     after login.</para>
  50
  51     <para>Note that the changes performed using this tool might require the initrd to be rebuilt to take
  52     effect during early system boot.  The initrd is not rebuilt automatically by
  53     <filename>localectl</filename>, this task has to be performed manually, usually using a tool like
  54     <citerefentry
  55     project='man-pages'><refentrytitle>dracut</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
  56     </para>
  57
  58     <para>Note that
  59     <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  60     may be used to initialize the system locale for mounted (but not booted)
  61     system images.</para>
  62   </refsect1>
  63
  64   <refsect1>
  65     <title>Commands</title>
  66
  67     <para>The following commands are understood:</para>
  68
  69     <variablelist>
  70       <varlistentry>
  71         <term><command>status</command></term>
  72
  73         <listitem><para>Show current settings of the system locale and keyboard mapping.
  74         If no command is specified, this is the implied default.</para>
  75
  76         <xi:include href="version-info.xml" xpointer="v195"/></listitem>
  77       </varlistentry>
  78
  79       <varlistentry>
  80         <term><command>set-locale LOCALE</command></term>
  81         <term><command>set-locale VARIABLE=LOCALE…</command></term>
  82
  83         <listitem><para>Set the system locale. This takes one locale such as <literal>en_US.UTF-8</literal>, or takes one or more
  84         locale assignments such as <literal>LANG=de_DE.utf8</literal>, <literal>LC_MESSAGES=en_GB.utf8</literal>, and so on. If
  85         one locale without variable name is provided, then <literal>LANG=</literal> locale variable will be set. See
  86         <citerefentry project='man-pages'><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>
  87         for details on the available settings and their meanings. Use
  88         <command>list-locales</command> for a list of available
  89         locales (see below). </para>
  90
  91         <xi:include href="version-info.xml" xpointer="v195"/></listitem>
  92       </varlistentry>
  93
  94       <varlistentry>
  95         <term><command>list-locales</command></term>
  96
  97         <listitem><para>List available locales useful for
  98         configuration with
  99         <command>set-locale</command>.</para>
 100
 101         <xi:include href="version-info.xml" xpointer="v195"/></listitem>
 102       </varlistentry>
 103
 104       <varlistentry>
 105         <term><command>set-keymap MAP [TOGGLEMAP]</command></term>
 106
 107         <listitem><para>Set the system keyboard mapping for the
 108         console and X11. This takes a mapping name (such as "de" or
 109         "us"), and possibly a second one to define a toggle keyboard
 110         mapping. Unless <option>--no-convert</option> is passed, the
 111         selected setting is also applied as the default system
 112         keyboard mapping of X11, after converting it to the closest
 113         matching X11 keyboard mapping. Use
 114         <command>list-keymaps</command> for a list of available
 115         keyboard mappings (see below).</para>
 116
 117         <xi:include href="version-info.xml" xpointer="v195"/></listitem>
 118       </varlistentry>
 119
 120       <varlistentry>
 121         <term><command>list-keymaps</command></term>
 122
 123         <listitem><para>List available keyboard mappings for the
 124         console, useful for configuration with
 125         <command>set-keymap</command>.</para>
 126
 127         <xi:include href="version-info.xml" xpointer="v195"/></listitem>
 128       </varlistentry>
 129
 130       <varlistentry>
 131         <term><command>set-x11-keymap LAYOUT [MODEL [VARIANT [OPTIONS]]]</command></term>
 132
 133         <listitem><para>Set the system default keyboard mapping for
 134         X11 and the virtual console. This takes a keyboard mapping
 135         name (such as <literal>de</literal> or <literal>us</literal>),
 136         and possibly a model, variant, and options, see
 137         <citerefentry><refentrytitle>kbd</refentrytitle><manvolnum>4</manvolnum></citerefentry>
 138         for details. Unless <option>--no-convert</option> is passed,
 139         the selected setting is also applied as the system console
 140         keyboard mapping, after converting it to the closest matching
 141         console keyboard mapping.</para>
 142
 143         <xi:include href="version-info.xml" xpointer="v195"/></listitem>
 144       </varlistentry>
 145
 146       <varlistentry>
 147         <term><command>list-x11-keymap-models</command></term>
 148         <term><command>list-x11-keymap-layouts</command></term>
 149         <term><command>list-x11-keymap-variants [LAYOUT]</command></term>
 150         <term><command>list-x11-keymap-options</command></term>
 151
 152         <listitem><para>List available X11 keymap models, layouts,
 153         variants and options, useful for configuration with
 154         <command>set-keymap</command>. The command
 155         <command>list-x11-keymap-variants</command> optionally takes a
 156         layout parameter to limit the output to the variants suitable
 157         for the specific layout.</para>
 158
 159         <xi:include href="version-info.xml" xpointer="v201"/></listitem>
 160       </varlistentry>
 161     </variablelist>
 162
 163   </refsect1>
 164
 165   <refsect1>
 166     <title>Options</title>
 167
 168     <para>The following options are understood:</para>
 169
 170     <variablelist>
 171       <varlistentry>
 172         <term><option>--no-ask-password</option></term>
 173
 174         <listitem><para>Do not query the user for authentication for
 175         privileged operations.</para>
 176
 177         <xi:include href="version-info.xml" xpointer="v195"/></listitem>
 178       </varlistentry>
 179
 180       <varlistentry>
 181         <term><option>--no-convert</option></term>
 182
 183         <listitem><para>If <command>set-keymap</command> or
 184         <command>set-x11-keymap</command> is invoked and this option
 185         is passed, then the keymap will not be converted from the
 186         console to X11, or X11 to console,
 187         respectively.</para>
 188
 189         <xi:include href="version-info.xml" xpointer="v195"/></listitem>
 190       </varlistentry>
 191
 192       <xi:include href="user-system-options.xml" xpointer="host" />
 193       <xi:include href="user-system-options.xml" xpointer="machine" />
 194
 195       <xi:include href="standard-options.xml" xpointer="help" />
 196       <xi:include href="standard-options.xml" xpointer="version" />
 197       <xi:include href="standard-options.xml" xpointer="no-pager" />
 198     </variablelist>
 199   </refsect1>
 200
 201   <refsect1>
 202     <title>Exit status</title>
 203
 204     <para>On success, 0 is returned, a non-zero failure code
 205     otherwise.</para>
 206   </refsect1>
 207
 208   <xi:include href="common-variables.xml" />
 209
 210   <refsect1>
 211     <title>See Also</title>
 212     <para>
 213       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 214       <citerefentry project='man-pages'><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 215       <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 216       <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 217       <citerefentry project='mankier'><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 218       <citerefentry><refentrytitle>kbd</refentrytitle><manvolnum>4</manvolnum></citerefentry>,
 219       <ulink url="http://www.x.org/releases/current/doc/xorg-docs/input/XKB-Config.html">
 220         The XKB Configuration Guide
 221       </ulink>,
 222       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 223       <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 224       <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 225       <citerefentry project='man-pages'><refentrytitle>dracut</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 226     </para>
 227   </refsect1>
 228
 229 </refentry>