+ <refsect1>
+ <title>Multi-Profile UKIs</title>
+
+ <para>In many contexts it is useful to allow invocation of a single UKI in multiple different modes (or
+ "profiles") without compromising the cryptographic integrity, measurements and so on of the boot
+ process. For example, a single UKI might provide three distinct profiles: a regular boot one, one that
+ invokes a "factory reset" operation, and one that boots into a storage target mode (as in
+ <citerefentry><refentrytitle>systemd-storagetm.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>). Each
+ profile would then use the same <literal>.linux</literal> and <literal>.initrd</literal> sections, but would
+ have a separate <literal>.cmdline</literal> section. For example the latter two profiles would extend the
+ regular kernel command line with <literal>systemd.unit=factory-reset.target</literal> or
+ <literal>rd.systemd.unit=storagetm.target</literal>.</para>
+
+ <para>A single UKI may support multiple profiles by means of the special <literal>.profile</literal> PE
+ section. This section acts as separator between the PE sections of the individual
+ profiles. <literal>.profile</literal> PE sections hence may appear multiple times in a single UKI, and
+ the other PE sections listed above may appear multiple times too, if <literal>.profile</literal> are
+ used, but only once before the first <literal>.profile</literal> section, once between each subsequent
+ pair, and once after the last appearance of <literal>.profile</literal>. The sections listed before the
+ first <literal>.profile</literal> are considered the "base" profile of the UKI. Each
+ <literal>.profile</literal> section then introduces a new profile, which are numbered starting from
+ zero. The PE sections following each <literal>.profile</literal> are specific to that profile. When
+ booting into a specific profile the base section's profiles are used in combination with the specific
+ profile's sections: if the same section is defined in both, the per-profile section overrides the base
+ profile's version, otherwise the per-profile sections is used together with the base profile
+ sections.</para> <para>A UKI that contains no <literal>.profile</literal> is consider equivalent to one
+ that just contains a single <literal>.profile</literal>, as having only a single profile @0.</para>
+
+ <para>Here's a simple example for a multi-profile UKI's sections, inspired by the setup suggested above:</para>
+
+ <table>
+ <title>Multi-Profile UKI Example</title>
+
+ <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+ <colspec colname="section" />
+ <colspec colname="profile" />
+
+ <thead>
+ <row>
+ <entry>Section</entry>
+ <entry>Profile</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><literal>.linux</literal></entry>
+ <entry morerows="3" valign="middle">Base profile</entry>
+ </row>
+ <row>
+ <entry><literal>.osrel</literal></entry>
+ </row>
+ <row>
+ <entry><literal>.cmdline</literal></entry>
+ </row>
+ <row>
+ <entry><literal>.initrd</literal></entry>
+ </row>
+ <row>
+ <entry><literal>.profile</literal></entry>
+ <entry>Profile @0</entry>
+ </row>
+ <row>
+ <entry><literal>.profile</literal></entry>
+ <entry morerows="1" valign="middle">Profile @1</entry>
+ </row>
+ <row>
+ <entry><literal>.cmdline</literal></entry>
+ </row>
+ <row>
+ <entry><literal>.profile</literal></entry>
+ <entry morerows="1" valign="middle">Profile @2</entry>
+ </row>
+ <row>
+ <entry><literal>.cmdline</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>The section list above would define three profiles. The first four sections make up the base
+ profile. A <literal>.profile</literal> section then introduces profile @0. It doesn't override any
+ sections (or add any) from the base section, hence it is immediately followed by another
+ <literal>.profile</literal> section that then introduces section @1. This profile overrides the kernel
+ command line. Finally, the last two sections define section @2, again overriding the command line. (Note
+ that in this example the first <literal>.cmdline</literal> could also moved behind the first
+ <literal>.profile</literal> with equivalent effect. To keep things nicely extensible, it's probably a
+ good idea to keep the generic command line in the base section instead of profile 0, in case later added
+ profiles might want to reuse it.)</para>
+
+ <para>The profile to boot may be controlled via the UKI's own command line: if the first argument starts
+ with <literal>@</literal>, followed by a positive integer number in decimal, it selects the profile to
+ boot into. If the first argument is not specified like that, the UKI will automatically boot into profile
+ 0.</para>
+
+ <para>A <literal>.profile</literal> section may contain meta-information about the profile. It follows a
+ similar format as <literal>.osrel</literal> (i.e. an environment-variable-assignment-block-like list of
+ newline separated strings). Currently two fields are defined: <literal>ID=</literal> is supposed to carry
+ a short identifying string that identifies the profile
+ (e.g. <literal>ID=factory-reset</literal>). <literal>TITLE=</literal> should contain a human readable
+ string that may appear in the boot menu entry for this profile (e.g. <literal>TITLE='Factory Reset this
+ Device'</literal>).</para>
+ </refsect1>
+