man/localectl.xml

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