mirrors/systemd
0
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-11-27 12:13:33 +08:00
Code Issues Packages Projects Releases Wiki Activity
13a29b0efb
systemd/man/ukify.xml

546 lines
28 KiB
XML
Raw Normal View History

man: add man page for ukify
2022-11-25 23:25:23 +08:00
<?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-or-later -->
ukify: don't install ukify man page if ukify is not enabled Checking for gnu-efi is not enough, since ukify can be explicitly disabled. Resolves: #26274
2023-02-01 04:43:53 +08:00
<refentry id="ukify" xmlns:xi="http://www.w3.org/2001/XInclude" conditional='ENABLE_UKIFY'>
man: add man page for ukify
2022-11-25 23:25:23 +08:00
<refentryinfo>
<title>ukify</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>ukify</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv>
<refname>ukify</refname>
ukify: allow building PE addon Make the kernel optional too, so that we can easily build and sign a PE addon, that can be used to carry extra command line options.
2023-04-18 07:40:43 +08:00
<refpurpose>Combine components into a signed Unified Kernel Image for UEFI systems</refpurpose>
man: add man page for ukify
2022-11-25 23:25:23 +08:00
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>/usr/lib/systemd/ukify</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
ukify: add 'build' verb The old syntax with linux + initrds as positional arguments is still accepted, but a warning is emitted. We should remove the support for this after the next release or so. Adding a single verb by itself is not very useful, but opens the door to adding other verbs.
2023-06-06 19:23:49 +08:00
<arg choice="plain">build</arg>
ukify: add 'genkey' verb The idea is to make it easy to generate all the signing key and certs that can be used for local signing. The verb is the modeled after 'mkosi genkey', but there are some important differences: we generate the keys to the paths where they will be read from, both pcr signing keys and the SecureBoot certificate+key. If any of the outputs exist, operation is refused. Maybe we could add a --force option in the future, but this operation should be rare, so I think it's better to refuse to overwrite anything initially. I'm only doing a token man page change here. https://github.com/systemd/systemd/pull/27621 reworks the man page, and the changes done here would conflict heavily with that work. I'll submit a follow-up patch later.
2023-06-07 03:06:20 +08:00
<arg choice="plain">genkey</arg>
man: add man page for ukify
2022-11-25 23:25:23 +08:00
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>Note: this command is experimental for now. While it is intended to become a regular component of
systemd, it might still change in behaviour and interface.</para>
ukify: add 'build' verb The old syntax with linux + initrds as positional arguments is still accepted, but a warning is emitted. We should remove the support for this after the next release or so. Adding a single verb by itself is not very useful, but opens the door to adding other verbs.
2023-06-06 19:23:49 +08:00
<para><command>ukify</command> is a tool that combines components (usually a kernel, an initrd, and a
UEFI boot stub) to create a
man: add man page for ukify
2022-11-25 23:25:23 +08:00
<ulink url="https://uapi-group.org/specifications/specs/unified_kernel_image/">Unified Kernel Image (UKI)</ulink>
— a PE binary that can be executed by the firmware to start the embedded linux kernel.
See <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for details about the stub.</para>
ukify: add 'build' verb The old syntax with linux + initrds as positional arguments is still accepted, but a warning is emitted. We should remove the support for this after the next release or so. Adding a single verb by itself is not very useful, but opens the door to adding other verbs.
2023-06-06 19:23:49 +08:00
<para>The two primary options that should be specified for the <command>build</command> verb are
<varname>Linux=</varname>/<option>--linux=</option>, and
<varname>Initrd=</varname>/<option>--initrd=</option>. <varname>Initrd=</varname> accepts multiple
whitespace-separated paths and <option>--initrd=</option> can be specified multiple times.</para>
man: add man page for ukify
2022-11-25 23:25:23 +08:00
<para>Additional sections will be inserted into the UKI, either automatically or only if a specific
option is provided. See the discussions of
man: describe all the changes to ukify As in mkosi(1), let's describe the config file and commandline options together. This is nice for us, because we don't need to duplicate descriptions and we're less likely to forget to update one place or the other. This is also nice for users, because they can easily figure out what can be configured where. The options are now ordered by config file section. --summary was not described before. More examples are added.
2023-04-24 18:40:08 +08:00
<varname>Cmdline=</varname>/<option>--cmdline=</option>,
<varname>OSRelease=</varname>/<option>--os-release=</option>,
<varname>DeviceTree=</varname>/<option>--devicetree=</option>,
<varname>Splash=</varname>/<option>--splash=</option>,
<varname>PCRPKey=</varname>/<option>--pcrpkey=</option>,
<varname>Uname=</varname>/<option>--uname=</option>,
ukify: add default .sbat section for addons In order to ensure addons can always be revoked via SBAT, and it is not left out by mistake, have a default metadata entry if none is specified by the caller. https://github.com/rhboot/shim/blob/main/SBAT.md
2023-05-21 21:32:39 +08:00
<varname>SBAT=</varname>/<option>--sbat=</option>,
man: add man page for ukify
2022-11-25 23:25:23 +08:00
and <option>--section=</option>
below.</para>
ukify: allow building PE addon Make the kernel optional too, so that we can easily build and sign a PE addon, that can be used to carry extra command line options.
2023-04-18 07:40:43 +08:00
<para><command>ukify</command> can also be used to assemble a PE binary that is not executable but
contains auxiliary data, for example additional kernel command line entries.</para>
man: describe all the changes to ukify As in mkosi(1), let's describe the config file and commandline options together. This is nice for us, because we don't need to duplicate descriptions and we're less likely to forget to update one place or the other. This is also nice for users, because they can easily figure out what can be configured where. The options are now ordered by config file section. --summary was not described before. More examples are added.
2023-04-24 18:40:08 +08:00
<para>If PCR signing keys are provided via the
<varname>PCRPrivateKey=</varname>/<option>--pcr-private-key=</option> and
<varname>PCRPublicKey=</varname>/<option>--pcr-public-key=</option> options, PCR values that will be seen
after booting with the given kernel, initrd, and other sections, will be calculated, signed, and embedded
in the UKI.
man: add man page for ukify
2022-11-25 23:25:23 +08:00
<citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry> is
used to perform this calculation and signing.</para>
<para>The calculation of PCR values is done for specific boot phase paths. Those can be specified with
man: describe all the changes to ukify As in mkosi(1), let's describe the config file and commandline options together. This is nice for us, because we don't need to duplicate descriptions and we're less likely to forget to update one place or the other. This is also nice for users, because they can easily figure out what can be configured where. The options are now ordered by config file section. --summary was not described before. More examples are added.
2023-04-24 18:40:08 +08:00
the <varname>Phases=</varname>/<option>--phases=</option> option. If not specified, the default provided
by <command>systemd-measure</command> is used. It is also possible to specify the
<varname>PCRPrivateKey=</varname>/<option>--pcr-private-key=</option>,
<varname>PCRPublicKey=</varname>/<option>--pcr-public-key=</option>, and
<varname>Phases=</varname>/<option>--phases=</option> arguments more than once. Signatures will then be
performed with each of the specified keys. On the command line, when both <option>--phases=</option> and
<option>--pcr-private-key=</option> are used, they must be specified the same number of times, and then
the n-th boot phase path set will be signed by the n-th key. This can be used to build different trust
policies for different phases of the boot. In the config file, <varname>PCRPrivateKey=</varname>,
<varname>PCRPublicKey=</varname>, and <varname>Phases=</varname> are grouped into separate sections,
describing separate boot phases.</para>
<para>If a SecureBoot signing key is provided via the
<varname>SecureBootPrivateKey=</varname>/<option>--secureboot-private-key=</option> option, the resulting
PE binary will be signed as a whole, allowing the resulting UKI to be trusted by SecureBoot. Also see the
discussion of automatic enrollment in
man: add man page for ukify
2022-11-25 23:25:23 +08:00
<citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para>
</refsect1>
<refsect1>
man: describe all the changes to ukify As in mkosi(1), let's describe the config file and commandline options together. This is nice for us, because we don't need to duplicate descriptions and we're less likely to forget to update one place or the other. This is also nice for users, because they can easily figure out what can be configured where. The options are now ordered by config file section. --summary was not described before. More examples are added.
2023-04-24 18:40:08 +08:00
<title>Configuration settings</title>
<para>Settings can appear in configuration files (the syntax with <varname
index='false'>SomeSetting=<replaceable>value</replaceable></varname>) and on the command line (the syntax
with <option index='false'>--some-setting=<replaceable>value</replaceable></option>). For some command
line parameters, a single-letter shortcut is also allowed. In the configuration files, the setting must
be in the appropriate section, so the descriptions are grouped by section below. When the same setting
appears in the configuration file and on the command line, generally the command line setting has higher
priority and overwrites the config file setting completely. If some setting behaves differently, this is
described below.</para>
<para>The <replaceable>LINUX</replaceable> and <replaceable>INITRD</replaceable> positional arguments, or
the equivalent <varname>Linux=</varname> and <varname>Initrd=</varname> settings, are optional. If more
than one initrd is specified, they will all be combined into a single PE section. This is useful to, for
example, prepend microcode before the actual initrd.</para>
<para>The following options and settings are understood:</para>
<refsect2>
<title>Commandline-only options</title>
<variablelist>
<varlistentry>
<term><option>--config=<replaceable>PATH</replaceable></option></term>
<listitem><para>Load configuration from the given config file. In general, settings specified in
the config file have lower precedence than the settings specified via options. In cases where the
commandline option does not fully override the config file setting are explicitly mentioned in the
descriptions of individual options.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--measure</option></term>
<term><option>--no-measure</option></term>
man: fixes for assorted issues reported by the manpage-l10n project Fixes #26761.
2023-05-17 18:24:04 +08:00
<listitem><para>Enable or disable a call to
<citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>
to print pre-calculated PCR values. Defaults to false.</para></listitem>
man: describe all the changes to ukify As in mkosi(1), let's describe the config file and commandline options together. This is nice for us, because we don't need to duplicate descriptions and we're less likely to forget to update one place or the other. This is also nice for users, because they can easily figure out what can be configured where. The options are now ordered by config file section. --summary was not described before. More examples are added.
2023-04-24 18:40:08 +08:00
</varlistentry>
<varlistentry>
<term><option>--section=<replaceable>NAME</replaceable>:<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term>
<listitem><para>Specify an arbitrary additional section
<literal><replaceable>NAME</replaceable></literal>. Note that the name is used as-is, and if the
section name should start with a dot, it must be included in <replaceable>NAME</replaceable>. The
argument may be a literal string, or <literal>@</literal> followed by a path name. This option may be
specified more than once. Any sections specified in this fashion will be inserted (in order) before
the <literal>.linux</literal> section which is always last.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--tools=<replaceable>DIRS</replaceable></option></term>
<listitem><para>Specify one or more directories with helper tools. <command>ukify</command> will
look for helper tools in those directories first, and if not found, try to load them from
<varname>$PATH</varname> in the usual fashion.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--output=<replaceable>FILENAME</replaceable></option></term>
<listitem><para>The output filename. If not specified, the name of the
<replaceable>LINUX</replaceable> argument, with the suffix <literal>.unsigned.efi</literal> or
<literal>.signed.efi</literal> will be used, depending on whether signing for SecureBoot was
performed.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--summary</option></term>
<listitem><para>Print a summary of loaded config and exit. This is useful to check how the options
form the configuration file and the commandline are combined.</para></listitem>
</varlistentry>
<xi:include href="standard-options.xml" xpointer="help" />
<xi:include href="standard-options.xml" xpointer="version" />
</variablelist>
</refsect2>
<refsect2>
<title>[UKI] section</title>
<variablelist>
<varlistentry>
<term><varname>Linux=<replaceable>LINUX</replaceable></varname></term>
ukify: add 'build' verb The old syntax with linux + initrds as positional arguments is still accepted, but a warning is emitted. We should remove the support for this after the next release or so. Adding a single verb by itself is not very useful, but opens the door to adding other verbs.
2023-06-06 19:23:49 +08:00
<term><option>--linux=<replaceable>LINUX</replaceable></option></term>
man: describe all the changes to ukify As in mkosi(1), let's describe the config file and commandline options together. This is nice for us, because we don't need to duplicate descriptions and we're less likely to forget to update one place or the other. This is also nice for users, because they can easily figure out what can be configured where. The options are now ordered by config file section. --summary was not described before. More examples are added.
2023-04-24 18:40:08 +08:00
<listitem><para>A path to the kernel binary.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>Initrd=<replaceable>INITRD</replaceable>...</varname></term>
ukify: add 'build' verb The old syntax with linux + initrds as positional arguments is still accepted, but a warning is emitted. We should remove the support for this after the next release or so. Adding a single verb by itself is not very useful, but opens the door to adding other verbs.
2023-06-06 19:23:49 +08:00
<term><option>--initrd=<replaceable>LINUX</replaceable></option></term>
man: describe all the changes to ukify As in mkosi(1), let's describe the config file and commandline options together. This is nice for us, because we don't need to duplicate descriptions and we're less likely to forget to update one place or the other. This is also nice for users, because they can easily figure out what can be configured where. The options are now ordered by config file section. --summary was not described before. More examples are added.
2023-04-24 18:40:08 +08:00
<listitem><para>Zero or more initrd paths. In the configuration file, items are separated by
whitespace. The initrds are combined in the order of specification, with the initrds specified in
the config file first.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>Cmdline=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></varname></term>
<term><option>--cmdline=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term>
<listitem><para>The kernel command line (the <literal>.cmdline</literal> section). The argument may
be a literal string, or <literal>@</literal> followed by a path name. If not specified, no command
line will be embedded.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>OSRelease=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></varname></term>
<term><option>--os-release=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term>
<listitem><para>The os-release description (the <literal>.osrel</literal> section). The argument
may be a literal string, or <literal>@</literal> followed by a path name. If not specified, the
<citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file
will be picked up from the host system.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>DeviceTree=<replaceable>PATH</replaceable></varname></term>
<term><option>--devicetree=<replaceable>PATH</replaceable></option></term>
<listitem><para>The devicetree description (the <literal>.dtb</literal> section). The argument is a
path to a compiled binary DeviceTree file. If not specified, the section will not be present.
</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>Splash=<replaceable>PATH</replaceable></varname></term>
<term><option>--splash=<replaceable>PATH</replaceable></option></term>
<listitem><para>A picture to display during boot (the <literal>.splash</literal> section). The
argument is a path to a BMP file. If not specified, the section will not be present.
</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>PCRPKey=<replaceable>PATH</replaceable></varname></term>
<term><option>--pcrpkey=<replaceable>PATH</replaceable></option></term>
<listitem><para>A path to a public key to embed in the <literal>.pcrpkey</literal> section. If not
specified, and there's exactly one
<varname>PCRPublicKey=</varname>/<option>--pcr-public-key=</option> argument, that key will be used.
Otherwise, the section will not be present.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>Uname=<replaceable>VERSION</replaceable></varname></term>
<term><option>--uname=<replaceable>VERSION</replaceable></option></term>
<listitem><para>Specify the kernel version (as in <command>uname -r</command>, the
<literal>.uname</literal> section). If not specified, an attempt will be made to extract the
version string from the kernel image. It is recommended to pass this explicitly if known, because
the extraction is based on heuristics and not very reliable. If not specified and extraction fails,
the section will not be present.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>PCRBanks=<replaceable>PATH</replaceable></varname></term>
<term><option>--pcr-banks=<replaceable>PATH</replaceable></option></term>
<listitem><para>A comma or space-separated list of PCR banks to sign a policy for. If not present,
all known banks will be used (<literal>sha1</literal>, <literal>sha256</literal>,
<literal>sha384</literal>, <literal>sha512</literal>), which will fail if not supported by the
system.</para></listitem>
</varlistentry>
ukify: support pesign as alternative to sbsign sbsign is not available everywhere, for example RHEL does not have it. Add pesign as alternative to it. pesign will use options "--secureboot-certificate-name" (mandatory) and "--secureboot-certificate-dir" (optional), while sbsign will use "--secureboot-private-key" and "--secureboot-certificate". By default, use sbsign. If no key/cert is provided or sbsign is not found, try pesign. Signed-off-by: Emanuele Giuseppe Esposito <eesposit@redhat.com>
2023-05-04 23:48:47 +08:00
<varlistentry>
<term><varname>SecureBootSigningTool=<replaceable>SIGNER</replaceable></varname></term>
<term><option>--signtool=<replaceable>SIGNER</replaceable></option></term>
<listitem><para>Whether to use <literal>sbsign</literal> or <literal>pesign</literal>.
Depending on this choice, different parameters are required in order to sign an image.
Defaults to <literal>sbsign</literal>.</para></listitem>
</varlistentry>
man: describe all the changes to ukify As in mkosi(1), let's describe the config file and commandline options together. This is nice for us, because we don't need to duplicate descriptions and we're less likely to forget to update one place or the other. This is also nice for users, because they can easily figure out what can be configured where. The options are now ordered by config file section. --summary was not described before. More examples are added.
2023-04-24 18:40:08 +08:00
<varlistentry>
<term><varname>SecureBootPrivateKey=<replaceable>SB_KEY</replaceable></varname></term>
<term><option>--secureboot-private-key=<replaceable>SB_KEY</replaceable></option></term>
<listitem><para>A path to a private key to use for signing of the resulting binary. If the
<varname>SigningEngine=</varname>/<option>--signing-engine=</option> option is used, this may also be
ukify: support pesign as alternative to sbsign sbsign is not available everywhere, for example RHEL does not have it. Add pesign as alternative to it. pesign will use options "--secureboot-certificate-name" (mandatory) and "--secureboot-certificate-dir" (optional), while sbsign will use "--secureboot-private-key" and "--secureboot-certificate". By default, use sbsign. If no key/cert is provided or sbsign is not found, try pesign. Signed-off-by: Emanuele Giuseppe Esposito <eesposit@redhat.com>
2023-05-04 23:48:47 +08:00
an engine-specific designation. This option is required by
<varname>SecureBootSigningTool=sbsign</varname>/<option>--signtool=sbsign</option>. </para></listitem>
man: describe all the changes to ukify As in mkosi(1), let's describe the config file and commandline options together. This is nice for us, because we don't need to duplicate descriptions and we're less likely to forget to update one place or the other. This is also nice for users, because they can easily figure out what can be configured where. The options are now ordered by config file section. --summary was not described before. More examples are added.
2023-04-24 18:40:08 +08:00
</varlistentry>
<varlistentry>
<term><varname>SecureBootCertificate=<replaceable>SB_CERT</replaceable></varname></term>
<term><option>--secureboot-certificate=<replaceable>SB_CERT</replaceable></option></term>
<listitem><para>A path to a certificate to use for signing of the resulting binary. If the
<varname>SigningEngine=</varname>/<option>--signing-engine=</option> option is used, this may also
ukify: support pesign as alternative to sbsign sbsign is not available everywhere, for example RHEL does not have it. Add pesign as alternative to it. pesign will use options "--secureboot-certificate-name" (mandatory) and "--secureboot-certificate-dir" (optional), while sbsign will use "--secureboot-private-key" and "--secureboot-certificate". By default, use sbsign. If no key/cert is provided or sbsign is not found, try pesign. Signed-off-by: Emanuele Giuseppe Esposito <eesposit@redhat.com>
2023-05-04 23:48:47 +08:00
be an engine-specific designation. This option is required by
<varname>SecureBootSigningTool=sbsign</varname>/<option>--signtool=sbsign</option>. </para></listitem>
</varlistentry>
<varlistentry>
<term><varname>SecureBootCertificateDir=<replaceable>SB_PATH</replaceable></varname></term>
<term><option>--secureboot-certificate-dir=<replaceable>SB_PATH</replaceable></option></term>
<listitem><para>A path to a nss certificate database directory to use for signing of the resulting binary.
Takes effect when <varname>SecureBootSigningTool=pesign</varname>/<option>--signtool=pesign</option> is used.
Defaults to <filename>/etc/pki/pesign</filename>.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>SecureBootCertificateName=<replaceable>SB_CERTNAME</replaceable></varname></term>
<term><option>--secureboot-certificate-name=<replaceable>SB_CERTNAME</replaceable></option></term>
<listitem><para>The name of the nss certificate database entry to use for signing of the resulting binary.
This option is required by <varname>SecureBootSigningTool=pesign</varname>/<option>--signtool=pesign</option>.</para></listitem>
man: describe all the changes to ukify As in mkosi(1), let's describe the config file and commandline options together. This is nice for us, because we don't need to duplicate descriptions and we're less likely to forget to update one place or the other. This is also nice for users, because they can easily figure out what can be configured where. The options are now ordered by config file section. --summary was not described before. More examples are added.
2023-04-24 18:40:08 +08:00
</varlistentry>
<varlistentry>
<term><varname>SigningEngine=<replaceable>ENGINE</replaceable></varname></term>
<term><option>--signing-engine=<replaceable>ENGINE</replaceable></option></term>
man: fixes for assorted issues reported by the manpage-l10n project Fixes #26761.
2023-05-17 18:24:04 +08:00
<listitem><para>An "engine" for signing of the resulting binary. This option is currently passed
man: describe all the changes to ukify As in mkosi(1), let's describe the config file and commandline options together. This is nice for us, because we don't need to duplicate descriptions and we're less likely to forget to update one place or the other. This is also nice for users, because they can easily figure out what can be configured where. The options are now ordered by config file section. --summary was not described before. More examples are added.
2023-04-24 18:40:08 +08:00
verbatim to the <option>--engine=</option> option of
<citerefentry project='archlinux'><refentrytitle>sbsign</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>SignKernel=<replaceable>BOOL</replaceable></varname></term>
<term><option>--sign-kernel</option></term>
<term><option>--no-sign-kernel</option></term>
<listitem><para>Override the detection of whether to sign the Linux binary itself before it is
embedded in the combined image. If not specified, it will be signed if a SecureBoot signing key is
provided via the
<varname>SecureBootPrivateKey=</varname>/<option>--secureboot-private-key=</option> option and the
binary has not already been signed. If
<varname>SignKernel=</varname>/<option>--sign-kernel</option> is true, and the binary has already
been signed, the signature will be appended anyway.</para></listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>[PCRSignature:<replaceable>NAME</replaceable>] section</title>
<para>In the config file, those options are grouped by section. On the commandline, they
must be specified in the same order. The sections specified in both sources are combined.
</para>
<variablelist>
<varlistentry>
<term><varname>PCRPrivateKey=<replaceable>PATH</replaceable></varname></term>
<term><option>--pcr-private-key=<replaceable>PATH</replaceable></option></term>
<listitem><para>A private key to use for signing PCR policies. On the commandline, this option may
be specified more than once, in which case multiple signatures will be made.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>PCRPublicKey=<replaceable>PATH</replaceable></varname></term>
<term><option>--pcr-public-key=<replaceable>PATH</replaceable></option></term>
<listitem><para>A public key to use for signing PCR policies.</para>
<para>On the commandline, this option may be specified more than once, similarly to the
<option>--pcr-private-key=</option> option. If not present, the public keys will be extracted from
the private keys. On the commandline, if present, the this option must be specified the same number
of times as the <option>--pcr-private-key=</option> option.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>Phases=<replaceable>LIST</replaceable></varname></term>
<term><option>--phases=<replaceable>LIST</replaceable></option></term>
<listitem><para>A comma or space-separated list of colon-separated phase paths to sign a policy
for. Each set of boot phase paths will be signed with the corresponding private key. If not
present, the default of
<citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>
will be used.</para>
<para>On the commandline, when this argument is present, it must appear the same number of times as
the <option>--pcr-private-key=</option> option. </para></listitem>
</varlistentry>
</variablelist>
</refsect2>
ukify: add default .sbat section for addons In order to ensure addons can always be revoked via SBAT, and it is not left out by mistake, have a default metadata entry if none is specified by the caller. https://github.com/rhboot/shim/blob/main/SBAT.md
2023-05-21 21:32:39 +08:00
<refsect2>
<title>[Addon:<replaceable>NAME</replaceable>] section</title>
<para>Currently, these options only apply when building PE addons.</para>
<variablelist>
<varlistentry>
<term><varname>SBAT=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></varname></term>
<term><option>--sbat=<replaceable>TEXT</replaceable>|<replaceable>@PATH</replaceable></option></term>
<listitem><para>SBAT metadata associated with the addon. SBAT policies are useful to revoke whole
groups of addons with a single, static policy update that does not take space in DBX/MOKX. If not
specified manually, a default metadata entry consisting of
<literal>uki.addon.systemd,1,UKI Addon,uki.addon.systemd,1,https://www.freedesktop.org/software/systemd/man/systemd-stub.html</literal>
will be used, to ensure it is always possible to revoke addons. For more information on SBAT see
<ulink url="https://github.com/rhboot/shim/blob/main/SBAT.md">Shim's documentation.</ulink></para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
man: add man page for ukify
2022-11-25 23:25:23 +08:00
</refsect1>
<refsect1>
<title>Examples</title>
<example>
<title>Minimal invocation</title>
ukify: add 'build' verb The old syntax with linux + initrds as positional arguments is still accepted, but a warning is emitted. We should remove the support for this after the next release or so. Adding a single verb by itself is not very useful, but opens the door to adding other verbs.
2023-06-06 19:23:49 +08:00
<programlisting>$ ukify build \
--linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
--initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img \
man: add man page for ukify
2022-11-25 23:25:23 +08:00
--cmdline='quiet rw'
</programlisting>
<para>This creates an unsigned UKI <filename>./vmlinuz.unsigned.efi</filename>.</para>
</example>
<example>
<title>All the bells and whistles</title>
man,test: root or hardware is not needed for ukify
2023-06-07 02:32:33 +08:00
<programlisting>$ /usr/lib/systemd/ukify build \
ukify: add 'build' verb The old syntax with linux + initrds as positional arguments is still accepted, but a warning is emitted. We should remove the support for this after the next release or so. Adding a single verb by itself is not very useful, but opens the door to adding other verbs.
2023-06-06 19:23:49 +08:00
--linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
--initrd=early_cpio \
--initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img \
man: add man page for ukify
2022-11-25 23:25:23 +08:00
--pcr-private-key=pcr-private-initrd-key.pem \
--pcr-public-key=pcr-public-initrd-key.pem \
--phases='enter-initrd' \
--pcr-private-key=pcr-private-system-key.pem \
--pcr-public-key=pcr-public-system-key.pem \
--phases='enter-initrd:leave-initrd enter-initrd:leave-initrd:sysinit \
enter-initrd:leave-initrd:sysinit:ready' \
--pcr-banks=sha384,sha512 \
--secureboot-private-key=sb.key \
--secureboot-certificate=sb.cert \
--sign-kernel \
--cmdline='quiet rw rhgb'
</programlisting>
<para>This creates a signed UKI <filename index='false'>./vmlinuz.signed.efi</filename>.
ukify: allow multiple initrds If given, multiple initrds are concatenated into a temporary file which then becomes the .initrd section. It is also possible to give no initrd. After all, some machines boot without an initrd, and it should be possible to use the stub without requiring an initrd. (The stub might not like this, but this is something to fix there.)
2022-11-26 21:31:57 +08:00
The initrd section contains two concatenated parts, <filename index='false'>early_cpio</filename>
and <filename index='false'>initramfs-6.0.9-300.fc37.x86_64.img</filename>.
man: add man page for ukify
2022-11-25 23:25:23 +08:00
The policy embedded in the <literal>.pcrsig</literal> section will be signed for the initrd (the
<constant>enter-initrd</constant> phase) with the key
<filename index='false'>pcr-private-initrd-key.pem</filename>, and for the main system (phases
<constant>leave-initrd</constant>, <constant>sysinit</constant>, <constant>ready</constant>) with the
key <filename index='false'>pcr-private-system-key.pem</filename>. The Linux binary and the resulting
combined image will be signed with the SecureBoot key <filename index='false'>sb.key</filename>.</para>
</example>
ukify: allow building PE addon Make the kernel optional too, so that we can easily build and sign a PE addon, that can be used to carry extra command line options.
2023-04-18 07:40:43 +08:00
man: describe all the changes to ukify As in mkosi(1), let's describe the config file and commandline options together. This is nice for us, because we don't need to duplicate descriptions and we're less likely to forget to update one place or the other. This is also nice for users, because they can easily figure out what can be configured where. The options are now ordered by config file section. --summary was not described before. More examples are added.
2023-04-24 18:40:08 +08:00
<example>
<title>All the bells and whistles, via a config file</title>
<para>This is the same as the previous example, but this time the configuration is stored in a
file:</para>
<programlisting>$ cat ukify.conf
[UKI]
Initrd=early_cpio
Cmdline=quiet rw rhgb
SecureBootPrivateKey=sb.key
SecureBootCerificate=sb.cert
SignKernel=yes
PCRBanks=sha384,sha512
[PCRSignature:initrd]
PCRPrivateKey=pcr-private-initrd-key.pem
PCRPublicKey=pcr-public-initrd-key.pem
Phases=enter-initrd
[PCRSignature:system]
PCRPrivateKey=pcr-private-system-key.pem
PCRPublicKey=pcr-public-system-key.pem
Phases=enter-initrd:leave-initrd
enter-initrd:leave-initrd:sysinit
enter-initrd:leave-initrd:sysinit:ready
man,test: root or hardware is not needed for ukify
2023-06-07 02:32:33 +08:00
$ /usr/lib/systemd/ukify -c ukify.conf build \
ukify: add 'build' verb The old syntax with linux + initrds as positional arguments is still accepted, but a warning is emitted. We should remove the support for this after the next release or so. Adding a single verb by itself is not very useful, but opens the door to adding other verbs.
2023-06-06 19:23:49 +08:00
--linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
--initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img
man: describe all the changes to ukify As in mkosi(1), let's describe the config file and commandline options together. This is nice for us, because we don't need to duplicate descriptions and we're less likely to forget to update one place or the other. This is also nice for users, because they can easily figure out what can be configured where. The options are now ordered by config file section. --summary was not described before. More examples are added.
2023-04-24 18:40:08 +08:00
</programlisting>
<para>One "initrd" (<filename index='false'>early_cpio</filename>) is specified in the config file, and
the other initrd (<filename index='false'>initramfs-6.0.9-300.fc37.x86_64.img</filename>) is specified
on the commandline. This may be useful for example when the first initrd contains microcode for the CPU
and does not need to be updated when the kernel version changes, unlike the actual initrd.</para>
</example>
ukify: allow building PE addon Make the kernel optional too, so that we can easily build and sign a PE addon, that can be used to carry extra command line options.
2023-04-18 07:40:43 +08:00
<example>
<title>Kernel command line auxiliary PE</title>
ukify: add 'build' verb The old syntax with linux + initrds as positional arguments is still accepted, but a warning is emitted. We should remove the support for this after the next release or so. Adding a single verb by itself is not very useful, but opens the door to adding other verbs.
2023-06-06 19:23:49 +08:00
<programlisting>ukify build \
ukify: allow building PE addon Make the kernel optional too, so that we can easily build and sign a PE addon, that can be used to carry extra command line options.
2023-04-18 07:40:43 +08:00
--secureboot-private-key=sb.key \
--secureboot-certificate=sb.cert \
--cmdline='debug' \
ukify: add default .sbat section for addons In order to ensure addons can always be revoked via SBAT, and it is not left out by mistake, have a default metadata entry if none is specified by the caller. https://github.com/rhboot/shim/blob/main/SBAT.md
2023-05-21 21:32:39 +08:00
--sbat='sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
uki.addon.author,1,UKI Addon for System,uki.addon.author,1,https://www.freedesktop.org/software/systemd/man/systemd-stub.html'
ukify: typo in doc and print when package is missing If a package is missing, a subprocess is started with None as command argument. Error raised by subprocess is therefore not helpful at all to understand what needs to be done to fix that error. Also fix doc since systemd-stub will look for .cmdline files, and not .cmdline.efi files. Signed-off-by: Emanuele Giuseppe Esposito <eesposit@redhat.com>
2023-05-05 18:22:57 +08:00
--output=debug.cmdline
ukify: allow building PE addon Make the kernel optional too, so that we can easily build and sign a PE addon, that can be used to carry extra command line options.
2023-04-18 07:40:43 +08:00
</programlisting>
man: describe all the changes to ukify As in mkosi(1), let's describe the config file and commandline options together. This is nice for us, because we don't need to duplicate descriptions and we're less likely to forget to update one place or the other. This is also nice for users, because they can easily figure out what can be configured where. The options are now ordered by config file section. --summary was not described before. More examples are added.
2023-04-24 18:40:08 +08:00
<para>This creates a signed PE binary that contains the additional kernel command line parameter
ukify: add default .sbat section for addons In order to ensure addons can always be revoked via SBAT, and it is not left out by mistake, have a default metadata entry if none is specified by the caller. https://github.com/rhboot/shim/blob/main/SBAT.md
2023-05-21 21:32:39 +08:00
<literal>debug</literal> with SBAT metadata referring to the owner of the addon.</para>
ukify: allow building PE addon Make the kernel optional too, so that we can easily build and sign a PE addon, that can be used to carry extra command line options.
2023-04-18 07:40:43 +08:00
</example>
man: add example how to configure automatic signing Fixes #978.
2023-06-07 03:31:17 +08:00
<example>
<title>Decide signing policy and create certificate and keys</title>
<para>First, let's create an config file that specifies what signatures shall be made:</para>
<programlisting># cat >/etc/kernel/uki.conf &lt;&lt;EOF
<xi:include href="uki.conf.example" parse="text" />EOF</programlisting>
<para>Next, we can generate the certificate and keys:</para>
<programlisting># /usr/lib/systemd/ukify genkey --config=/etc/kernel/uki.conf
Writing SecureBoot private key to /etc/kernel/secure-boot.key.pem
Writing SecureBoot certicate to /etc/kernel/secure-boot.cert.pem
Writing private key for PCR signing to /etc/kernel/pcr-initrd.key.pem
Writing public key for PCR signing to /etc/kernel/pcr-initrd.pub.pem
Writing private key for PCR signing to /etc/kernel/pcr-system.key.pem
Writing public key for PCR signing to /etc/kernel/pcr-system.pub.pem
</programlisting>
<para>(Both operations need to be done as root to allow write access
to <filename>/etc/kernel/</filename>.)</para>
<para>Subsequent invocations of using the config file
(<command>/usr/lib/systemd/ukify build --config=/etc/kernel/uki.conf</command>)
will use this certificate and key files. Note that the
<citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>
plugin <filename>60-ukify.install</filename> uses <filename>/etc/kernel/uki.conf</filename>
by default, so after this file has been created, installations of kernels that create a UKI on the
local machine using <command>kernel-install</command> would perform signing using this config.</para>
</example>
man: add man page for ukify
2022-11-25 23:25:23 +08:00
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
man: describe all the changes to ukify As in mkosi(1), let's describe the config file and commandline options together. This is nice for us, because we don't need to duplicate descriptions and we're less likely to forget to update one place or the other. This is also nice for users, because they can easily figure out what can be configured where. The options are now ordered by config file section. --summary was not described before. More examples are added.
2023-04-24 18:40:08 +08:00
<citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
man: Fix pcrphase.service manvolnum from 1 to 8
2023-03-11 03:29:56 +08:00
<citerefentry><refentrytitle>systemd-pcrphase.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
man: add man page for ukify
2022-11-25 23:25:23 +08:00
</para>
</refsect1>
</refentry>
Reference in New Issue Copy Permalink