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
52    the initramfs to be rebuilt to take effect during early system boot.
53    The initramfs is not rebuilt automatically by <filename>localectl</filename>.
54    </para>
55
56    <para>Note that
57    <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
58    may be used to initialize the system locale for mounted (but not booted)
59    system images.</para>
60  </refsect1>
61
62  <refsect1>
63    <title>Commands</title>
64
65    <para>The following commands are understood:</para>
66
67    <variablelist>
68      <varlistentry>
69        <term><command>status</command></term>
70
71        <listitem><para>Show current settings of the system locale and keyboard mapping.
72        If no command is specified, this is the implied default.</para></listitem>
73      </varlistentry>
74
75      <varlistentry>
76        <term><command>set-locale LOCALE</command></term>
77        <term><command>set-locale VARIABLE=LOCALE…</command></term>
78
79        <listitem><para>Set the system locale. This takes one locale such as <literal>en_US.UTF-8</literal>, or takes one or more
80        locale assignments such as <literal>LANG=de_DE.utf8</literal>, <literal>LC_MESSAGES=en_GB.utf8</literal>, and so on. If
81        one locale without variable name is provided, then <literal>LANG=</literal> locale variable will be set. See
82        <citerefentry project='man-pages'><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>
83        for details on the available settings and their meanings. Use
84        <command>list-locales</command> for a list of available
85        locales (see below). </para></listitem>
86      </varlistentry>
87
88      <varlistentry>
89        <term><command>list-locales</command></term>
90
91        <listitem><para>List available locales useful for
92        configuration with
93        <command>set-locale</command>.</para></listitem>
94      </varlistentry>
95
96      <varlistentry>
97        <term><command>set-keymap MAP [TOGGLEMAP]</command></term>
98
99        <listitem><para>Set the system keyboard mapping for the
100        console and X11. This takes a mapping name (such as "de" or
101        "us"), and possibly a second one to define a toggle keyboard
102        mapping. Unless <option>--no-convert</option> is passed, the
103        selected setting is also applied as the default system
104        keyboard mapping of X11, after converting it to the closest
105        matching X11 keyboard mapping. Use
106        <command>list-keymaps</command> for a list of available
107        keyboard mappings (see below).</para></listitem>
108      </varlistentry>
109
110      <varlistentry>
111        <term><command>list-keymaps</command></term>
112
113        <listitem><para>List available keyboard mappings for the
114        console, useful for configuration with
115        <command>set-keymap</command>.</para></listitem>
116      </varlistentry>
117
118      <varlistentry>
119        <term><command>set-x11-keymap LAYOUT [MODEL [VARIANT [OPTIONS]]]</command></term>
120
121        <listitem><para>Set the system default keyboard mapping for
122        X11 and the virtual console. This takes a keyboard mapping
123        name (such as <literal>de</literal> or <literal>us</literal>),
124        and possibly a model, variant, and options, see
125        <citerefentry><refentrytitle>kbd</refentrytitle><manvolnum>4</manvolnum></citerefentry>
126        for details. Unless <option>--no-convert</option> is passed,
127        the selected setting is also applied as the system console
128        keyboard mapping, after converting it to the closest matching
129        console keyboard mapping.</para></listitem>
130      </varlistentry>
131
132      <varlistentry>
133        <term><command>list-x11-keymap-models</command></term>
134        <term><command>list-x11-keymap-layouts</command></term>
135        <term><command>list-x11-keymap-variants [LAYOUT]</command></term>
136        <term><command>list-x11-keymap-options</command></term>
137
138        <listitem><para>List available X11 keymap models, layouts,
139        variants and options, useful for configuration with
140        <command>set-keymap</command>. The command
141        <command>list-x11-keymap-variants</command> optionally takes a
142        layout parameter to limit the output to the variants suitable
143        for the specific layout.</para></listitem>
144      </varlistentry>
145    </variablelist>
146
147  </refsect1>
148
149  <refsect1>
150    <title>Options</title>
151
152    <para>The following options are understood:</para>
153
154    <variablelist>
155      <varlistentry>
156        <term><option>--no-ask-password</option></term>
157
158        <listitem><para>Do not query the user for authentication for
159        privileged operations.</para></listitem>
160      </varlistentry>
161
162      <varlistentry>
163        <term><option>--no-convert</option></term>
164
165        <listitem><para>If <command>set-keymap</command> or
166        <command>set-x11-keymap</command> is invoked and this option
167        is passed, then the keymap will not be converted from the
168        console to X11, or X11 to console,
169        respectively.</para></listitem>
170      </varlistentry>
171
172      <xi:include href="user-system-options.xml" xpointer="host" />
173      <xi:include href="user-system-options.xml" xpointer="machine" />
174
175      <xi:include href="standard-options.xml" xpointer="help" />
176      <xi:include href="standard-options.xml" xpointer="version" />
177      <xi:include href="standard-options.xml" xpointer="no-pager" />
178    </variablelist>
179  </refsect1>
180
181  <refsect1>
182    <title>Exit status</title>
183
184    <para>On success, 0 is returned, a non-zero failure code
185    otherwise.</para>
186  </refsect1>
187
188  <xi:include href="common-variables.xml" />
189
190  <refsect1>
191    <title>See Also</title>
192    <para>
193      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
194      <citerefentry project='man-pages'><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
195      <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
196      <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
197      <citerefentry project='mankier'><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
198      <citerefentry><refentrytitle>kbd</refentrytitle><manvolnum>4</manvolnum></citerefentry>,
199      <ulink url="http://www.x.org/releases/current/doc/xorg-docs/input/XKB-Config.html">
200        The XKB Configuration Guide
201      </ulink>,
202      <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
203      <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
204      <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
205      <citerefentry project='die-net'><refentrytitle>mkinitrd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
206    </para>
207  </refsect1>
208
209</refentry>
210