firstboot: clarify that machine-id options are only offline, add missing docs

Let's flat out refuse to configure machine-id on a running system with
systemd-firstboot. It wouldn't work anyway, because by the time firstboot is
started, pid1 has created /etc/machine-id, possibly with "unitialized", so
firstboot wouldn't touch the file. (If --force is specified, it works. So
let's allow that in case people want to do crazy things.)

While at it, add missing descriptions of various things that were added over
time, and group descriptions of similar options together.

diff --git a/man/systemd-firstboot.xml b/man/systemd-firstboot.xml
index 42666c96f8852be81b4ae621d03acd0a4c354354..99846839678e8dac5c3459cb9d7dbde492679876 100644 (file)
--- a/man/systemd-firstboot.xml
+++ b/man/systemd-firstboot.xml
@@ -34,18 +34,18 @@
   <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>
+    <para><command>systemd-firstboot</command> initializes basic system settings interactively during the
+    first boot, or non-interactively on an offline system image. The service is started during boot if
+    <varname>ConditionFirstBoot=yes</varname> is met, which essentially means that <filename>/etc/</filename>
     is empty, see
-    <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-    for details.</para>
+    <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+    details.</para>
 
-    <para>The following settings may be set up:</para>
+    <para>The following settings may be configured:</para>
 
     <itemizedlist>
+      <listitem><para>The machine ID of the system</para></listitem>
+
       <listitem><para>The system locale, more specifically the two
       locale variables <varname>LANG=</varname> and
       <varname>LC_MESSAGES</varname></para></listitem>
@@ -56,9 +56,9 @@
 
       <listitem><para>The system hostname</para></listitem>
 
-      <listitem><para>The machine ID of the system</para></listitem>
+      <listitem><para>The kernel command line used when installing kernel images</para></listitem>
 
-      <listitem><para>The root user's password</para></listitem>
+      <listitem><para>The root user's password and shell</para></listitem>
     </itemizedlist>
 
     <para>Each of the fields may either be queried interactively by
@@ -79,7 +79,7 @@
     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>
+    running system after it has been set up.</para>
   </refsect1>
 
   <refsect1>
@@ -150,13 +150,25 @@
         configuration file.</para></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><option>--setup-machine-id</option></term>
+
+        <listitem><para>Initialize the system's machine ID to a random ID. This controls the
+        <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> file.
+        </para>
+
+        <para>This option only works in combination with <option>--root=</option> or
+        <option>--image=</option>. On a running system, <filename>machine-id</filename> is written by the
+        manager with help from
+        <citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+        </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>
+        <listitem><para>Set the system's machine ID to the specified value. The same restrictions apply
+        as to <option>--setup-machine-id</option>.</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -230,8 +242,8 @@
         <term><option>--copy-root-shell</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>
+        This only works in combination with <option>--root=</option> or <option>--image=</option>.
+        </para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -247,21 +259,14 @@
         </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>
-
       <varlistentry>
         <term><option>--force</option></term>
 
-        <listitem><para>systemd-firstboot doesn't modify existing files unless <option>--force</option>
-        is specified. For modifications to <filename>/etc/passwd</filename> and
-        <filename>/etc/shadow</filename>, systemd-firstboot only modifies the entry of the
-        <literal>root</literal> user instead of overwriting the entire file.</para></listitem>
+        <listitem><para>Write configuration even if the relevant files already exist. Without this option,
+        <filename>systemd-firstboot</filename> doesn't modify or replace existing files. Note that when
+        configuring the root account, even with this option, <filename>systemd-firstboot</filename> only
+        modifies the entry of the <literal>root</literal> user, leaving other entries in
+        <filename>/etc/passwd</filename> and <filename>/etc/shadow</filename> intact.</para></listitem>
       </varlistentry>
 
       <varlistentry>

diff --git a/src/firstboot/firstboot.c b/src/firstboot/firstboot.c
index 6d50054baf8d42ea29211c6574e217eab7c536a2..19d5568854e11d5102295467d8438ee034e23ecc 100644 (file)
--- a/src/firstboot/firstboot.c
+++ b/src/firstboot/firstboot.c
@@ -1172,7 +1172,8 @@ static int help(void) {
                "     --keymap=KEYMAP              Set keymap\n"
                "     --timezone=TIMEZONE          Set timezone\n"
                "     --hostname=NAME              Set hostname\n"
-               "     --machine-ID=ID              Set machine ID\n"
+               "     --setup-machine-id           Set a random machine ID\n"
+               "     --machine-ID=ID              Set specified machine ID\n"
                "     --root-password=PASSWORD     Set root password from plaintext password\n"
                "     --root-password-file=FILE    Set root password from file\n"
                "     --root-password-hashed=HASH  Set root password from hashed password\n"
@@ -1190,7 +1191,6 @@ static int help(void) {
                "     --copy-root-password         Copy root password from host\n"
                "     --copy-root-shell            Copy root shell from host\n"
                "     --copy                       Copy locale, keymap, timezone, root password\n"
-               "     --setup-machine-id           Generate a new random machine ID\n"
                "     --force                      Overwrite existing files\n"
                "     --delete-root-password       Delete root password\n"
                "     --welcome=no                 Disable the welcome text\n"
@@ -1214,6 +1214,7 @@ static int parse_argv(int argc, char *argv[]) {
                 ARG_KEYMAP,
                 ARG_TIMEZONE,
                 ARG_HOSTNAME,
+                ARG_SETUP_MACHINE_ID,
                 ARG_MACHINE_ID,
                 ARG_ROOT_PASSWORD,
                 ARG_ROOT_PASSWORD_FILE,
@@ -1233,7 +1234,6 @@ static int parse_argv(int argc, char *argv[]) {
                 ARG_COPY_TIMEZONE,
                 ARG_COPY_ROOT_PASSWORD,
                 ARG_COPY_ROOT_SHELL,
-                ARG_SETUP_MACHINE_ID,
                 ARG_FORCE,
                 ARG_DELETE_ROOT_PASSWORD,
                 ARG_WELCOME,
@@ -1251,6 +1251,7 @@ static int parse_argv(int argc, char *argv[]) {
                 { "keymap",                  required_argument, NULL, ARG_KEYMAP                  },
                 { "timezone",                required_argument, NULL, ARG_TIMEZONE                },
                 { "hostname",                required_argument, NULL, ARG_HOSTNAME                },
+                { "setup-machine-id",        no_argument,       NULL, ARG_SETUP_MACHINE_ID        },
                 { "machine-id",              required_argument, NULL, ARG_MACHINE_ID              },
                 { "root-password",           required_argument, NULL, ARG_ROOT_PASSWORD           },
                 { "root-password-file",      required_argument, NULL, ARG_ROOT_PASSWORD_FILE      },
@@ -1270,7 +1271,6 @@ static int parse_argv(int argc, char *argv[]) {
                 { "copy-timezone",           no_argument,       NULL, ARG_COPY_TIMEZONE           },
                 { "copy-root-password",      no_argument,       NULL, ARG_COPY_ROOT_PASSWORD      },
                 { "copy-root-shell",         no_argument,       NULL, ARG_COPY_ROOT_SHELL         },
-                { "setup-machine-id",        no_argument,       NULL, ARG_SETUP_MACHINE_ID        },
                 { "force",                   no_argument,       NULL, ARG_FORCE                   },
                 { "delete-root-password",    no_argument,       NULL, ARG_DELETE_ROOT_PASSWORD    },
                 { "welcome",                 required_argument, NULL, ARG_WELCOME                 },
@@ -1392,6 +1392,13 @@ static int parse_argv(int argc, char *argv[]) {
                         hostname_cleanup(arg_hostname);
                         break;
 
+                case ARG_SETUP_MACHINE_ID:
+                        r = sd_id128_randomize(&arg_machine_id);
+                        if (r < 0)
+                                return log_error_errno(r, "Failed to generate randomized machine ID: %m");
+
+                        break;
+
                 case ARG_MACHINE_ID:
                         r = sd_id128_from_string(optarg, &arg_machine_id);
                         if (r < 0)
@@ -1460,13 +1467,6 @@ static int parse_argv(int argc, char *argv[]) {
                         arg_copy_root_shell = true;
                         break;
 
-                case ARG_SETUP_MACHINE_ID:
-                        r = sd_id128_randomize(&arg_machine_id);
-                        if (r < 0)
-                                return log_error_errno(r, "Failed to generate randomized machine ID: %m");
-
-                        break;
-
                 case ARG_FORCE:
                         arg_force = true;
                         break;
@@ -1496,10 +1496,15 @@ static int parse_argv(int argc, char *argv[]) {
 
         if (arg_delete_root_password && (arg_copy_root_password || arg_root_password || arg_prompt_root_password))
                 return log_error_errno(SYNTHETIC_ERRNO(EINVAL),
-                                       "--delete-root-password cannot be combined with other root password options");
+                                       "--delete-root-password cannot be combined with other root password options.");
 
         if (arg_image && arg_root)
-                return log_error_errno(SYNTHETIC_ERRNO(EINVAL), "Please specify either --root= or --image=, the combination of both is not supported.");
+                return log_error_errno(SYNTHETIC_ERRNO(EINVAL),
+                                       "--root= and --image= cannot be used together.");
+
+        if (!sd_id128_is_null(arg_machine_id) && !(arg_image || arg_root) && !arg_force)
+                return log_error_errno(SYNTHETIC_ERRNO(EINVAL),
+                                       "--machine-id=/--setup-machine-id only works with --root= or --image=.");
 
         return 1;
 }