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

<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//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>

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