[thirdparty/systemd.git] / man / systemd-firstboot.xml

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

<refentry id="systemd-firstboot" conditional='ENABLE_FIRSTBOOT'
    xmlns:xi="http://www.w3.org/2001/XInclude">

  <refentryinfo>
    <title>systemd-firstboot</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>systemd-firstboot</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>systemd-firstboot</refname>
    <refname>systemd-firstboot.service</refname>
    <refpurpose>Initialize basic system settings on or before the first boot-up of a system</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>systemd-firstboot</command>
      <arg choice="opt" rep="repeat">OPTIONS</arg>
    </cmdsynopsis>

    <para><filename>systemd-firstboot.service</filename></para>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para><command>systemd-firstboot</command> initializes the most
    basic system settings interactively on the first boot, or
    optionally non-interactively when a system image is created.
    The service is started if <varname>ConditionFirstBoot=yes</varname>
    is satisfied. This essentially means that <filename>/etc</filename>
    is empty, see
    <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
    for details.</para>

    <para>The following settings may be set up:</para>

    <itemizedlist>
      <listitem><para>The system locale, more specifically the two
      locale variables <varname>LANG=</varname> and
      <varname>LC_MESSAGES</varname></para></listitem>

      <listitem><para>The system keyboard map</para></listitem>

      <listitem><para>The system time zone</para></listitem>

      <listitem><para>The system host name</para></listitem>

      <listitem><para>The machine ID of the system</para></listitem>

      <listitem><para>The root user's password</para></listitem>
    </itemizedlist>

    <para>Each of the fields may either be queried interactively by
    users, set non-interactively on the tool's command line, or be
    copied from a host system that is used to set up the system
    image.</para>

    <para>If a setting is already initialized, it will not be
    overwritten and the user will not be prompted for the
    setting.</para>

    <para>Note that this tool operates directly on the file system and
    does not involve any running system services, unlike
    <citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
    <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
    or
    <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
    This allows <command>systemd-firstboot</command> to operate on
    mounted but not booted disk images and in early boot. It is not
    recommended to use <command>systemd-firstboot</command> on the
    running system while it is up.</para>
  </refsect1>

  <refsect1>
    <title>Options</title>

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

    <variablelist>
      <varlistentry>
        <term><option>--root=<replaceable>root</replaceable></option></term>
        <listitem><para>Takes a directory path as an argument. All
        paths will be prefixed with the given alternate
        <replaceable>root</replaceable> path, including config search
        paths. This is useful to operate on a system image mounted to
        the specified directory instead of the host system itself.
        </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--locale=<replaceable>LOCALE</replaceable></option></term>
        <term><option>--locale-messages=<replaceable>LOCALE</replaceable></option></term>

        <listitem><para>Sets the system locale, more specifically the
        <varname>LANG=</varname> and <varname>LC_MESSAGES</varname>
        settings. The argument should be a valid locale identifier,
        such as <literal>de_DE.UTF-8</literal>. This controls the
        <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
        configuration file.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--keymap=<replaceable>KEYMAP</replaceable></option></term>

        <listitem><para>Sets the system keyboard layout. The argument should be a valid keyboard map,
        such as <literal>de-latin1</literal>. This controls the <literal>KEYMAP</literal> entry in the
        <citerefentry project='man-pages'><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
        configuration file.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--timezone=<replaceable>TIMEZONE</replaceable></option></term>

        <listitem><para>Sets the system time zone. The argument should
        be a valid time zone identifier, such as
        <literal>Europe/Berlin</literal>. This controls the
        <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>
        symlink.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--hostname=<replaceable>HOSTNAME</replaceable></option></term>

        <listitem><para>Sets the system hostname. The argument should
        be a host name, compatible with DNS. This controls the
        <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
        configuration file.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--machine-id=<replaceable>ID</replaceable></option></term>

        <listitem><para>Sets the system's machine ID. This controls
        the
        <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
        file.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--root-password=<replaceable>PASSWORD</replaceable></option></term>
        <term><option>--root-password-file=<replaceable>PATH</replaceable></option></term>

        <listitem><para>Sets the password of the system's root user.
        This creates a
        <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>
        file. This setting exists in two forms:
        <option>--root-password=</option> accepts the password to set
        directly on the command line, and
        <option>--root-password-file=</option> reads it from a file.
        Note that it is not recommended to specify passwords on the
        command line, as other users might be able to see them simply
        by invoking
        <citerefentry project='die-net'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--prompt-locale</option></term>
        <term><option>--prompt-keymap</option></term>
        <term><option>--prompt-timezone</option></term>
        <term><option>--prompt-hostname</option></term>
        <term><option>--prompt-root-password</option></term>

        <listitem><para>Prompt the user interactively for a specific
        basic setting. Note that any explicit configuration settings
        specified on the command line take precedence, and the user is
        not prompted for it.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--prompt</option></term>

        <listitem><para>Query the user for locale, keymap, timezone, hostname
        and root password. This is equivalent to specifying
        <option>--prompt-locale</option>,
        <option>--prompt-keymap</option>,
        <option>--prompt-timezone</option>,
        <option>--prompt-hostname</option>,
        <option>--prompt-root-password</option> in combination.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--copy-locale</option></term>
        <term><option>--copy-keymap</option></term>
        <term><option>--copy-timezone</option></term>
        <term><option>--copy-root-password</option></term>

        <listitem><para>Copy a specific basic setting from the host.
        This only works in combination with <option>--root=</option>
        (see above).</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--copy</option></term>

        <listitem><para>Copy locale, keymap, time zone and root password from
        the host. This is equivalent to specifying
        <option>--copy-locale</option>,
        <option>--copy-keymap</option>,
        <option>--copy-timezone</option>,
        <option>--copy-root-password</option> in combination.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--setup-machine-id</option></term>

        <listitem><para>Initialize the system's machine ID to a random
        ID. This only works in combination with
        <option>--root=</option>.</para></listitem>
      </varlistentry>

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

  </refsect1>

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

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

  <refsect1>
    <title>Kernel Command Line</title>

    <variablelist class='kernel-commandline-options'>
      <varlistentry>
        <term><varname>systemd.firstboot=</varname></term>

        <listitem><para>Takes a boolean argument, defaults to on. If off, <filename>systemd-firstboot.service</filename>
        won't interactively query the user for basic settings at first boot, even if those settings are not
        initialized yet.</para></listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
      <citerefentry project='man-pages'><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
      <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
    </para>
  </refsect1>

</refentry>
Commit	Line	Data
30f10abf	1	<?xml version='1.0'?> <!---nxml--->
3a54a157	2	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
12b42c76	3	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
0307f791	4	<!-- SPDX-License-Identifier: LGPL-2.1+ -->
30f10abf	5
efd51554	6	<refentry id="systemd-firstboot" conditional='ENABLE_FIRSTBOOT'
798d3a52 ZJS	7	xmlns:xi="http://www.w3.org/2001/XInclude">
	8
	9	<refentryinfo>
	10	<title>systemd-firstboot</title>
	11	<productname>systemd</productname>
798d3a52 ZJS	12	</refentryinfo>
	13
	14	<refmeta>
	15	<refentrytitle>systemd-firstboot</refentrytitle>
	16	<manvolnum>1</manvolnum>
	17	</refmeta>
	18
	19	<refnamediv>
	20	<refname>systemd-firstboot</refname>
	21	<refname>systemd-firstboot.service</refname>
	22	<refpurpose>Initialize basic system settings on or before the first boot-up of a system</refpurpose>
	23	</refnamediv>
	24
	25	<refsynopsisdiv>
	26	<cmdsynopsis>
	27	<command>systemd-firstboot</command>
	28	<arg choice="opt" rep="repeat">OPTIONS</arg>
	29	</cmdsynopsis>
	30
	31	<para><filename>systemd-firstboot.service</filename></para>
	32	</refsynopsisdiv>
	33
	34	<refsect1>
	35	<title>Description</title>
	36
	37	<para><command>systemd-firstboot</command> initializes the most
	38	basic system settings interactively on the first boot, or
c954f332 ZJS	39	optionally non-interactively when a system image is created.
	40	The service is started if <varname>ConditionFirstBoot=yes</varname>
	41	is satisfied. This essentially means that <filename>/etc</filename>
	42	is empty, see
	43	<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	44	for details.</para>
	45
	46	<para>The following settings may be set up:</para>
798d3a52 ZJS	47
	48	<itemizedlist>
	49	<listitem><para>The system locale, more specifically the two
	50	locale variables <varname>LANG=</varname> and
	51	<varname>LC_MESSAGES</varname></para></listitem>
	52
ed457f13 TB	53	<listitem><para>The system keyboard map</para></listitem>
ed457f13 TB	54
798d3a52 ZJS	55	<listitem><para>The system time zone</para></listitem>
	56
	57	<listitem><para>The system host name</para></listitem>
	58
	59	<listitem><para>The machine ID of the system</para></listitem>
	60
	61	<listitem><para>The root user's password</para></listitem>
	62	</itemizedlist>
	63
a8eaaee7 JE	64	<para>Each of the fields may either be queried interactively by
a8eaaee7 JE	65	users, set non-interactively on the tool's command line, or be
798d3a52 ZJS	66	copied from a host system that is used to set up the system
	67	image.</para>
	68
b938cb90	69	<para>If a setting is already initialized, it will not be
798d3a52 ZJS	70	overwritten and the user will not be prompted for the
	71	setting.</para>
	72
	73	<para>Note that this tool operates directly on the file system and
	74	does not involve any running system services, unlike
3ba3a79d	75	<citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a52 ZJS	76	<citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
	77	or
	78	<citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
	79	This allows <command>systemd-firstboot</command> to operate on
	80	mounted but not booted disk images and in early boot. It is not
	81	recommended to use <command>systemd-firstboot</command> on the
	82	running system while it is up.</para>
	83	</refsect1>
	84
	85	<refsect1>
	86	<title>Options</title>
	87
	88	<para>The following options are understood:</para>
	89
	90	<variablelist>
	91	<varlistentry>
	92	<term><option>--root=<replaceable>root</replaceable></option></term>
	93	<listitem><para>Takes a directory path as an argument. All
	94	paths will be prefixed with the given alternate
	95	<replaceable>root</replaceable> path, including config search
	96	paths. This is useful to operate on a system image mounted to
	97	the specified directory instead of the host system itself.
	98	</para></listitem>
	99	</varlistentry>
	100
	101	<varlistentry>
	102	<term><option>--locale=<replaceable>LOCALE</replaceable></option></term>
	103	<term><option>--locale-messages=<replaceable>LOCALE</replaceable></option></term>
	104
	105	<listitem><para>Sets the system locale, more specifically the
	106	<varname>LANG=</varname> and <varname>LC_MESSAGES</varname>
	107	settings. The argument should be a valid locale identifier,
	108	such as <literal>de_DE.UTF-8</literal>. This controls the
3ba3a79d	109	<citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
798d3a52 ZJS	110	configuration file.</para></listitem>
	111	</varlistentry>
	112
ed457f13 TB	113	<varlistentry>
	114	<term><option>--keymap=<replaceable>KEYMAP</replaceable></option></term>
	115
	116	<listitem><para>Sets the system keyboard layout. The argument should be a valid keyboard map,
	117	such as <literal>de-latin1</literal>. This controls the <literal>KEYMAP</literal> entry in the
	118	<citerefentry project='man-pages'><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	119	configuration file.</para></listitem>
	120	</varlistentry>
	121
798d3a52 ZJS	122	<varlistentry>
	123	<term><option>--timezone=<replaceable>TIMEZONE</replaceable></option></term>
	124
	125	<listitem><para>Sets the system time zone. The argument should
	126	be a valid time zone identifier, such as
	127	<literal>Europe/Berlin</literal>. This controls the
	128	<citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	129	symlink.</para></listitem>
	130	</varlistentry>
	131
	132	<varlistentry>
	133	<term><option>--hostname=<replaceable>HOSTNAME</replaceable></option></term>
	134
	135	<listitem><para>Sets the system hostname. The argument should
	136	be a host name, compatible with DNS. This controls the
	137	<citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	138	configuration file.</para></listitem>
	139	</varlistentry>
	140
	141	<varlistentry>
	142	<term><option>--machine-id=<replaceable>ID</replaceable></option></term>
	143
	144	<listitem><para>Sets the system's machine ID. This controls
	145	the
	146	<citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	147	file.</para></listitem>
	148	</varlistentry>
	149
	150	<varlistentry>
	151	<term><option>--root-password=<replaceable>PASSWORD</replaceable></option></term>
	152	<term><option>--root-password-file=<replaceable>PATH</replaceable></option></term>
	153
	154	<listitem><para>Sets the password of the system's root user.
	155	This creates a
3ba3a79d	156	<citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>
798d3a52 ZJS	157	file. This setting exists in two forms:
798d3a52 ZJS	158	<option>--root-password=</option> accepts the password to set
a8eaaee7	159	directly on the command line, and
798d3a52	160	<option>--root-password-file=</option> reads it from a file.
a8eaaee7	161	Note that it is not recommended to specify passwords on the
b938cb90	162	command line, as other users might be able to see them simply
798d3a52	163	by invoking
3ba3a79d	164	<citerefentry project='die-net'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
798d3a52 ZJS	165	</varlistentry>
	166
	167	<varlistentry>
	168	<term><option>--prompt-locale</option></term>
ed457f13	169	<term><option>--prompt-keymap</option></term>
798d3a52 ZJS	170	<term><option>--prompt-timezone</option></term>
	171	<term><option>--prompt-hostname</option></term>
	172	<term><option>--prompt-root-password</option></term>
	173
	174	<listitem><para>Prompt the user interactively for a specific
	175	basic setting. Note that any explicit configuration settings
	176	specified on the command line take precedence, and the user is
	177	not prompted for it.</para></listitem>
	178	</varlistentry>
	179
	180	<varlistentry>
	181	<term><option>--prompt</option></term>
	182
ed457f13	183	<listitem><para>Query the user for locale, keymap, timezone, hostname
798d3a52 ZJS	184	and root password. This is equivalent to specifying
798d3a52 ZJS	185	<option>--prompt-locale</option>,
ed457f13	186	<option>--prompt-keymap</option>,
798d3a52 ZJS	187	<option>--prompt-timezone</option>,
	188	<option>--prompt-hostname</option>,
	189	<option>--prompt-root-password</option> in combination.</para>
	190	</listitem>
	191	</varlistentry>
	192
	193	<varlistentry>
	194	<term><option>--copy-locale</option></term>
ed457f13	195	<term><option>--copy-keymap</option></term>
798d3a52 ZJS	196	<term><option>--copy-timezone</option></term>
	197	<term><option>--copy-root-password</option></term>
	198
	199	<listitem><para>Copy a specific basic setting from the host.
	200	This only works in combination with <option>--root=</option>
	201	(see above).</para></listitem>
	202	</varlistentry>
	203
	204	<varlistentry>
	205	<term><option>--copy</option></term>
	206
ed457f13	207	<listitem><para>Copy locale, keymap, time zone and root password from
798d3a52 ZJS	208	the host. This is equivalent to specifying
798d3a52 ZJS	209	<option>--copy-locale</option>,
ed457f13	210	<option>--copy-keymap</option>,
798d3a52 ZJS	211	<option>--copy-timezone</option>,
	212	<option>--copy-root-password</option> in combination.</para>
	213	</listitem>
	214	</varlistentry>
	215
	216	<varlistentry>
	217	<term><option>--setup-machine-id</option></term>
	218
	219	<listitem><para>Initialize the system's machine ID to a random
	220	ID. This only works in combination with
	221	<option>--root=</option>.</para></listitem>
	222	</varlistentry>
	223
	224	<xi:include href="standard-options.xml" xpointer="help" />
	225	<xi:include href="standard-options.xml" xpointer="version" />
	226	</variablelist>
	227
	228	</refsect1>
	229
	230	<refsect1>
	231	<title>Exit status</title>
	232
	233	<para>On success, 0 is returned, a non-zero failure code
	234	otherwise.</para>
	235	</refsect1>
	236
f582cbca LP	237	<refsect1>
	238	<title>Kernel Command Line</title>
	239
	240	<variablelist class='kernel-commandline-options'>
	241	<varlistentry>
	242	<term><varname>systemd.firstboot=</varname></term>
	243
6b3d3783 ZJS	244	<listitem><para>Takes a boolean argument, defaults to on. If off, <filename>systemd-firstboot.service</filename>
6b3d3783 ZJS	245	won't interactively query the user for basic settings at first boot, even if those settings are not
f582cbca LP	246	initialized yet.</para></listitem>
	247	</varlistentry>
	248	</variablelist>
	249	</refsect1>
	250
798d3a52 ZJS	251	<refsect1>
	252	<title>See Also</title>
	253	<para>
	254	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
3ba3a79d	255	<citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
ed457f13	256	<citerefentry project='man-pages'><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
798d3a52 ZJS	257	<citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	258	<citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	259	<citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
3ba3a79d	260	<citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
798d3a52	261	<citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
3ba3a79d	262	<citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a52 ZJS	263	<citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	264	<citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
	265	</para>
	266	</refsect1>
30f10abf LP	267
30f10abf LP	268	</refentry>