[thirdparty/systemd.git] / man / localectl.xml

<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->

<refentry id="localectl" conditional='ENABLE_LOCALED'
    xmlns:xi="http://www.w3.org/2001/XInclude">

  <refentryinfo>
    <title>localectl</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>localectl</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>localectl</refname>
    <refpurpose>Control the system locale and keyboard layout settings</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>localectl</command>
      <arg choice="opt" rep="repeat">OPTIONS</arg>
      <arg choice="req">COMMAND</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para><command>localectl</command> may be used to query and change
    the system locale and keyboard layout settings. It communicates with
    <citerefentry><refentrytitle>systemd-localed</refentrytitle><manvolnum>8</manvolnum></citerefentry>
    to modify files such as <filename>/etc/locale.conf</filename> and
    <filename>/etc/vconsole.conf</filename>.</para>

    <para>The system locale controls the language settings of system
    services and of the UI before the user logs in, such as the
    display manager, as well as the default for users after
    login.</para>

    <para>The keyboard settings control the keyboard layout used on
    the text console and of the graphical UI before the user logs in,
    such as the display manager, as well as the default for users
    after login.</para>

    <para>Note that the changes performed using this tool might require the initrd to be rebuilt to take
    effect during early system boot.  The initrd is not rebuilt automatically by
    <filename>localectl</filename>, this task has to be performed manually, usually by reinstalling the
    distribution's kernel package.</para>

    <para>Note that
    <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
    may be used to initialize the system locale for mounted (but not booted)
    system images.</para>
  </refsect1>

  <refsect1>
    <title>Commands</title>

    <para>The following commands are understood:</para>

    <variablelist>
      <varlistentry>
        <term><command>status</command></term>

        <listitem><para>Show current settings of the system locale and keyboard mapping.
        If no command is specified, this is the implied default.</para>

        <xi:include href="version-info.xml" xpointer="v195"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><command>set-locale LOCALE</command></term>
        <term><command>set-locale VARIABLE=LOCALE…</command></term>

        <listitem><para>Set the system locale. This takes one locale such as <literal>en_US.UTF-8</literal>, or takes one or more
        locale assignments such as <literal>LANG=de_DE.utf8</literal>, <literal>LC_MESSAGES=en_GB.utf8</literal>, and so on. If
        one locale without variable name is provided, then <literal>LANG=</literal> locale variable will be set. See
        <citerefentry project='man-pages'><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>
        for details on the available settings and their meanings. Use
        <command>list-locales</command> for a list of available
        locales (see below). </para>

        <xi:include href="version-info.xml" xpointer="v195"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><command>list-locales</command></term>

        <listitem><para>List available locales useful for
        configuration with
        <command>set-locale</command>.</para>

        <xi:include href="version-info.xml" xpointer="v195"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><command>set-keymap MAP [TOGGLEMAP]</command></term>

        <listitem><para>Set the system keyboard mapping for the
        console and X11. This takes a mapping name (such as "de" or
        "us"), and possibly a second one to define a toggle keyboard
        mapping. Unless <option>--no-convert</option> is passed, the
        selected setting is also applied as the default system
        keyboard mapping of X11, after converting it to the closest
        matching X11 keyboard mapping. Use
        <command>list-keymaps</command> for a list of available
        keyboard mappings (see below).</para>

        <xi:include href="version-info.xml" xpointer="v195"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><command>list-keymaps</command></term>

        <listitem><para>List available keyboard mappings for the
        console, useful for configuration with
        <command>set-keymap</command>.</para>

        <xi:include href="version-info.xml" xpointer="v195"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><command>set-x11-keymap LAYOUT [MODEL [VARIANT [OPTIONS]]]</command></term>

        <listitem><para>Set the system default keyboard mapping for
        X11 and the virtual console. This takes a keyboard mapping
        name (such as <literal>de</literal> or <literal>us</literal>),
        and possibly a model, variant, and options, see
        <citerefentry><refentrytitle>kbd</refentrytitle><manvolnum>4</manvolnum></citerefentry>
        for details. Unless <option>--no-convert</option> is passed,
        the selected setting is also applied as the system console
        keyboard mapping, after converting it to the closest matching
        console keyboard mapping.</para>

        <xi:include href="version-info.xml" xpointer="v195"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><command>list-x11-keymap-models</command></term>
        <term><command>list-x11-keymap-layouts</command></term>
        <term><command>list-x11-keymap-variants [LAYOUT]</command></term>
        <term><command>list-x11-keymap-options</command></term>

        <listitem><para>List available X11 keymap models, layouts,
        variants and options, useful for configuration with
        <command>set-keymap</command>. The command
        <command>list-x11-keymap-variants</command> optionally takes a
        layout parameter to limit the output to the variants suitable
        for the specific layout.</para>

        <xi:include href="version-info.xml" xpointer="v201"/></listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Options</title>

    <para>The following options are understood:</para>

    <variablelist>
      <varlistentry>
        <term><option>--no-ask-password</option></term>

        <listitem><para>Do not query the user for authentication for
        privileged operations.</para>

        <xi:include href="version-info.xml" xpointer="v195"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--no-convert</option></term>

        <listitem><para>If <command>set-keymap</command> or
        <command>set-x11-keymap</command> is invoked and this option
        is passed, then the keymap will not be converted from the
        console to X11, or X11 to console,
        respectively.</para>

        <xi:include href="version-info.xml" xpointer="v195"/></listitem>
      </varlistentry>

      <xi:include href="user-system-options.xml" xpointer="host" />
      <xi:include href="user-system-options.xml" xpointer="machine" />

      <xi:include href="standard-options.xml" xpointer="help" />
      <xi:include href="standard-options.xml" xpointer="version" />
      <xi:include href="standard-options.xml" xpointer="no-pager" />
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Exit status</title>

    <para>On success, 0 is returned, a non-zero failure code
    otherwise.</para>
  </refsect1>

  <xi:include href="common-variables.xml" />

  <refsect1>
    <title>See Also</title>
    <para><simplelist type="inline">
      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
      <member><citerefentry project='man-pages'><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
      <member><citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
      <member><citerefentry project='mankier'><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>kbd</refentrytitle><manvolnum>4</manvolnum></citerefentry></member>
      <member><ulink url="http://www.x.org/releases/current/doc/xorg-docs/input/XKB-Config.html">
        The XKB Configuration Guide
      </ulink></member>
      <member><citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
      <member><citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
    </simplelist></para>
  </refsect1>

</refentry>
Commit	Line	Data
7cd28a8a	1	<?xml version='1.0'?> <!---nxml--->
3a54a157	2	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
eea10b26	3	"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
db9ecf05	4	<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
7cd28a8a	5
21ac6ff1	6	<refentry id="localectl" conditional='ENABLE_LOCALED'
798d3a52 ZJS	7	xmlns:xi="http://www.w3.org/2001/XInclude">
	8
	9	<refentryinfo>
	10	<title>localectl</title>
	11	<productname>systemd</productname>
798d3a52 ZJS	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
dfc6109f ZJS	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>
798d3a52 ZJS	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
32e27670 LP	51	<para>Note that the changes performed using this tool might require the initrd to be rebuilt to take
32e27670 LP	52	effect during early system boot. The initrd is not rebuilt automatically by
98118c44 DDM	53	<filename>localectl</filename>, this task has to be performed manually, usually by reinstalling the
98118c44 DDM	54	distribution's kernel package.</para>
dfc6109f ZJS	55
dfc6109f ZJS	56	<para>Note that
798d3a52	57	<citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
dfc6109f	58	may be used to initialize the system locale for mounted (but not booted)
798d3a52 ZJS	59	system images.</para>
	60	</refsect1>
	61
d4e0773b YW	62	<refsect1>
d4e0773b YW	63	<title>Commands</title>
798d3a52 ZJS	64
	65	<para>The following commands are understood:</para>
	66
	67	<variablelist>
	68	<varlistentry>
	69	<term><command>status</command></term>
	70
d4e0773b	71	<listitem><para>Show current settings of the system locale and keyboard mapping.
aefdc112 AK	72	If no command is specified, this is the implied default.</para>
	73
	74	<xi:include href="version-info.xml" xpointer="v195"/></listitem>
798d3a52 ZJS	75	</varlistentry>
	76
	77	<varlistentry>
4156e767 YW	78	<term><command>set-locale LOCALE</command></term>
4156e767 YW	79	<term><command>set-locale VARIABLE=LOCALE…</command></term>
798d3a52	80
4156e767 YW	81	<listitem><para>Set the system locale. This takes one locale such as <literal>en_US.UTF-8</literal>, or takes one or more
	82	locale assignments such as <literal>LANG=de_DE.utf8</literal>, <literal>LC_MESSAGES=en_GB.utf8</literal>, and so on. If
	83	one locale without variable name is provided, then <literal>LANG=</literal> locale variable will be set. See
3ba3a79d	84	<citerefentry project='man-pages'><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>
798d3a52 ZJS	85	for details on the available settings and their meanings. Use
798d3a52 ZJS	86	<command>list-locales</command> for a list of available
ec07c3c8 AK	87	locales (see below). </para>
ec07c3c8 AK	88
aefdc112	89	<xi:include href="version-info.xml" xpointer="v195"/></listitem>
798d3a52 ZJS	90	</varlistentry>
	91
	92	<varlistentry>
	93	<term><command>list-locales</command></term>
	94
	95	<listitem><para>List available locales useful for
	96	configuration with
aefdc112 AK	97	<command>set-locale</command>.</para>
	98
	99	<xi:include href="version-info.xml" xpointer="v195"/></listitem>
798d3a52 ZJS	100	</varlistentry>
	101
	102	<varlistentry>
	103	<term><command>set-keymap MAP [TOGGLEMAP]</command></term>
	104
	105	<listitem><para>Set the system keyboard mapping for the
	106	console and X11. This takes a mapping name (such as "de" or
	107	"us"), and possibly a second one to define a toggle keyboard
	108	mapping. Unless <option>--no-convert</option> is passed, the
	109	selected setting is also applied as the default system
	110	keyboard mapping of X11, after converting it to the closest
	111	matching X11 keyboard mapping. Use
	112	<command>list-keymaps</command> for a list of available
aefdc112 AK	113	keyboard mappings (see below).</para>
	114
	115	<xi:include href="version-info.xml" xpointer="v195"/></listitem>
798d3a52 ZJS	116	</varlistentry>
	117
	118	<varlistentry>
	119	<term><command>list-keymaps</command></term>
	120
	121	<listitem><para>List available keyboard mappings for the
	122	console, useful for configuration with
aefdc112 AK	123	<command>set-keymap</command>.</para>
	124
	125	<xi:include href="version-info.xml" xpointer="v195"/></listitem>
798d3a52 ZJS	126	</varlistentry>
	127
	128	<varlistentry>
	129	<term><command>set-x11-keymap LAYOUT [MODEL [VARIANT [OPTIONS]]]</command></term>
	130
	131	<listitem><para>Set the system default keyboard mapping for
	132	X11 and the virtual console. This takes a keyboard mapping
	133	name (such as <literal>de</literal> or <literal>us</literal>),
	134	and possibly a model, variant, and options, see
	135	<citerefentry><refentrytitle>kbd</refentrytitle><manvolnum>4</manvolnum></citerefentry>
	136	for details. Unless <option>--no-convert</option> is passed,
	137	the selected setting is also applied as the system console
	138	keyboard mapping, after converting it to the closest matching
aefdc112 AK	139	console keyboard mapping.</para>
	140
	141	<xi:include href="version-info.xml" xpointer="v195"/></listitem>
798d3a52 ZJS	142	</varlistentry>
	143
	144	<varlistentry>
	145	<term><command>list-x11-keymap-models</command></term>
	146	<term><command>list-x11-keymap-layouts</command></term>
	147	<term><command>list-x11-keymap-variants [LAYOUT]</command></term>
	148	<term><command>list-x11-keymap-options</command></term>
	149
	150	<listitem><para>List available X11 keymap models, layouts,
	151	variants and options, useful for configuration with
	152	<command>set-keymap</command>. The command
	153	<command>list-x11-keymap-variants</command> optionally takes a
	154	layout parameter to limit the output to the variants suitable
aefdc112 AK	155	for the specific layout.</para>
	156
	157	<xi:include href="version-info.xml" xpointer="v201"/></listitem>
798d3a52 ZJS	158	</varlistentry>
	159	</variablelist>
	160
	161	</refsect1>
	162
e1fac8a6 ZJS	163	<refsect1>
	164	<title>Options</title>
	165
	166	<para>The following options are understood:</para>
	167
	168	<variablelist>
	169	<varlistentry>
	170	<term><option>--no-ask-password</option></term>
	171
	172	<listitem><para>Do not query the user for authentication for
ec07c3c8 AK	173	privileged operations.</para>
	174
	175	<xi:include href="version-info.xml" xpointer="v195"/></listitem>
e1fac8a6 ZJS	176	</varlistentry>
	177
	178	<varlistentry>
	179	<term><option>--no-convert</option></term>
	180
	181	<listitem><para>If <command>set-keymap</command> or
	182	<command>set-x11-keymap</command> is invoked and this option
	183	is passed, then the keymap will not be converted from the
	184	console to X11, or X11 to console,
ec07c3c8 AK	185	respectively.</para>
	186
	187	<xi:include href="version-info.xml" xpointer="v195"/></listitem>
e1fac8a6 ZJS	188	</varlistentry>
	189
	190	<xi:include href="user-system-options.xml" xpointer="host" />
	191	<xi:include href="user-system-options.xml" xpointer="machine" />
	192
	193	<xi:include href="standard-options.xml" xpointer="help" />
	194	<xi:include href="standard-options.xml" xpointer="version" />
	195	<xi:include href="standard-options.xml" xpointer="no-pager" />
	196	</variablelist>
	197	</refsect1>
	198
798d3a52 ZJS	199	<refsect1>
	200	<title>Exit status</title>
	201
	202	<para>On success, 0 is returned, a non-zero failure code
	203	otherwise.</para>
	204	</refsect1>
	205
4ef3ca34	206	<xi:include href="common-variables.xml" />
798d3a52 ZJS	207
	208	<refsect1>
	209	<title>See Also</title>
13a69c12 DT	210	<para><simplelist type="inline">
	211	<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
	212	<member><citerefentry project='man-pages'><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
	213	<member><citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
	214	<member><citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
	215	<member><citerefentry project='mankier'><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
	216	<member><citerefentry><refentrytitle>kbd</refentrytitle><manvolnum>4</manvolnum></citerefentry></member>
	217	<member><ulink url="http://www.x.org/releases/current/doc/xorg-docs/input/XKB-Config.html">
798d3a52	218	The XKB Configuration Guide
13a69c12 DT	219	</ulink></member>
	220	<member><citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
	221	<member><citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
	222	<member><citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
13a69c12	223	</simplelist></para>
798d3a52	224	</refsect1>
7cd28a8a LP	225
7cd28a8a LP	226	</refentry>