diff options
Diffstat (limited to 'upstream/opensuse-tumbleweed/man1/ukify.1')
| -rw-r--r-- | upstream/opensuse-tumbleweed/man1/ukify.1 | 168 |
1 files changed, 138 insertions, 30 deletions
diff --git a/upstream/opensuse-tumbleweed/man1/ukify.1 b/upstream/opensuse-tumbleweed/man1/ukify.1 index 4ca57564..e4377af7 100644 --- a/upstream/opensuse-tumbleweed/man1/ukify.1 +++ b/upstream/opensuse-tumbleweed/man1/ukify.1 @@ -1,5 +1,5 @@ '\" t -.TH "UKIFY" "1" "" "systemd 254" "ukify" +.TH "UKIFY" "1" "" "systemd 255" "ukify" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -22,14 +22,14 @@ .SH "NAME" ukify \- Combine components into a signed Unified Kernel Image for UEFI systems .SH "SYNOPSIS" -.HP \w'\fB/usr/lib/systemd/ukify\fR\ 'u -\fB/usr/lib/systemd/ukify\fR [OPTIONS...] build +.HP \w'\fBukify\fR\ 'u +\fBukify\fR [OPTIONS...] build .HP \w'\fBukify\fR\ 'u \fBukify\fR [OPTIONS...] genkey +.HP \w'\fBukify\fR\ 'u +\fBukify\fR [OPTIONS...] inspect FILE... .SH "DESCRIPTION" .PP -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\&. -.PP \fBukify\fR is a tool whose primary purpose is to combine components (usually a kernel, an initrd, and a UEFI boot stub) to create a \m[blue]\fBUnified Kernel Image (UKI)\fR\m[]\&\s-2\u[1]\d\s+2 @@ -99,7 +99,7 @@ option, the resulting PE binary will be signed as a whole, allowing the resultin If the stub and/or the kernel contain "\&.sbat" sections they will be merged in the UKI so that revocation updates affecting either are considered when the UKI is loaded by Shim\&. For more information on SBAT see -\m[blue]\fBShim\*(Aqs documentation\&.\fR\m[]\&\s-2\u[2]\d\s+2 +\m[blue]\fBShim documentation\fR\m[]\&\s-2\u[2]\d\s+2\&. .SS "genkey" .PP This command creates the keys for PCR signing and the key and certificate used for SecureBoot signing\&. The same configuration options that determine what keys and in which paths will be needed for signing when @@ -111,12 +111,35 @@ is used, here determine which keys will be created\&. See the discussion of below\&. .PP The output files must not exist\&. +.SS "inspect" +.PP +Display information about the sections in a given binary or binaries\&. If +\fB\-\-all\fR +is given, all sections are shown\&. Otherwise, if +\fB\-\-section=\fR +option is specified at least once, only those sections are shown\&. Otherwise, well\-known sections that are typically included in an UKI are shown\&. For each section, its name, size, and sha256\-digest is printed\&. For text sections, the contents are printed\&. +.PP +Also see the description of +\fB\-j\fR/\fB\-\-json=\fR +and +\fB\-\-section=\fR\&. .SH "CONFIGURATION SETTINGS" .PP Settings can appear in configuration files (the syntax with \fISomeSetting=\fR\fI\fIvalue\fR\fR) and on the command line (the syntax with \fB\-\-some\-setting=\fR\fB\fIvalue\fR\fR)\&. 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\&. .PP +If no config file is provided via the option +\fB\-\-config=\fR\fB\fIPATH\fR\fR, +\fBukify\fR +will try to look for a default configuration file in the following paths in this order: +/run/systemd/ukify\&.conf, +/etc/systemd/ukify\&.conf, +/usr/local/lib/systemd/ukify\&.conf, and +/usr/lib/systemd/ukify\&.conf, and then load the first one found\&. +\fBukify\fR +will proceed normally if no configuration file is specified and no default one is found\&. +.PP The \fILINUX\fR and @@ -128,11 +151,13 @@ and 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\&. .PP The following options and settings are understood: -.SS "Commandline\-only options" +.SS "Command line\-only options" .PP \fB\-\-config=\fR\fB\fIPATH\fR\fR .RS 4 -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\&. +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 command line option does not fully override the config file setting are explicitly mentioned in the descriptions of individual options\&. +.sp +Added in version 254\&. .RE .PP \fB\-\-measure\fR, \fB\-\-no\-measure\fR @@ -140,17 +165,32 @@ Load configuration from the given config file\&. In general, settings specified Enable or disable a call to \fBsystemd-measure\fR(1) to print pre\-calculated PCR values\&. Defaults to false\&. +.sp +Added in version 253\&. .RE .PP -\fB\-\-section=\fR\fB\fINAME\fR\fR\fB:\fR\fB\fITEXT\fR\fR\fB|\fR\fB\fI@PATH\fR\fR +\fB\-\-section=\fR\fB\fINAME\fR\fR\fB:\fR\fB\fITEXT\fR\fR\fB|\fR\fB\fI@PATH\fR\fR, \fB\-\-section=\fR\fB\fINAME\fR\fR\fB:\fR\fBtext|binary\fR\fB[@\fIPATH\fR]\fR .RS 4 -Specify an arbitrary additional section -"\fINAME\fR"\&. Note that the name is used as\-is, and if the section name should start with a dot, it must be included in -\fINAME\fR\&. The argument may be a literal string, or +For all verbs except +\fBinspect\fR, the first syntax is used\&. Specify an arbitrary additional section +"\fINAME\fR"\&. The argument may be a literal string, or "@" 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 "\&.linux" section which is always last\&. +.sp +For the +\fBinspect\fR +verb, the second syntax is used\&. The section +\fINAME\fR +will be inspected (if found)\&. If the second argument is +"text", the contents will be printed\&. If the third argument is given, the contents will be saved to file +\fIPATH\fR\&. +.sp +Note that the name is used as\-is, and if the section name should start with a dot, it must be included in +\fINAME\fR\&. +.sp +Added in version 253\&. .RE .PP \fB\-\-tools=\fR\fB\fIDIRS\fR\fR @@ -160,6 +200,8 @@ Specify one or more directories with helper tools\&. will look for helper tools in those directories first, and if not found, try to load them from \fI$PATH\fR in the usual fashion\&. +.sp +Added in version 253\&. .RE .PP \fB\-\-output=\fR\fB\fIFILENAME\fR\fR @@ -171,11 +213,33 @@ argument, with the suffix or "\&.signed\&.efi" will be used, depending on whether signing for SecureBoot was performed\&. +.sp +Added in version 253\&. .RE .PP \fB\-\-summary\fR .RS 4 -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\&. +Print a summary of loaded config and exit\&. This is useful to check how the options from the configuration file and the command line are combined\&. +.sp +Added in version 254\&. +.RE +.PP +\fB\-\-all\fR +.RS 4 +Print all sections (with +\fBinspect\fR +verb)\&. +.sp +Added in version 255\&. +.RE +.PP +\fB\-\-json\fR +.RS 4 +Generate JSON output (with +\fBinspect\fR +verb)\&. +.sp +Added in version 255\&. .RE .PP \fB\-h\fR, \fB\-\-help\fR @@ -192,11 +256,15 @@ Print a short version string and exit\&. \fILinux=\fR\fI\fILINUX\fR\fR, \fB\-\-linux=\fR\fB\fILINUX\fR\fR .RS 4 A path to the kernel binary\&. +.sp +Added in version 254\&. .RE .PP \fIInitrd=\fR\fI\fIINITRD\fR\fR\fI\&.\&.\&.\fR, \fB\-\-initrd=\fR\fB\fILINUX\fR\fR .RS 4 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\&. +.sp +Added in version 254\&. .RE .PP \fICmdline=\fR\fI\fITEXT\fR\fR\fI|\fR\fI\fI@PATH\fR\fR, \fB\-\-cmdline=\fR\fB\fITEXT\fR\fR\fB|\fR\fB\fI@PATH\fR\fR @@ -206,6 +274,8 @@ The kernel command line (the section)\&. The argument may be a literal string, or "@" followed by a path name\&. If not specified, no command line will be embedded\&. +.sp +Added in version 253\&. .RE .PP \fIOSRelease=\fR\fI\fITEXT\fR\fR\fI|\fR\fI\fI@PATH\fR\fR, \fB\-\-os\-release=\fR\fB\fITEXT\fR\fR\fB|\fR\fB\fI@PATH\fR\fR @@ -217,6 +287,8 @@ section)\&. The argument may be a literal string, or followed by a path name\&. If not specified, the \fBos-release\fR(5) file will be picked up from the host system\&. +.sp +Added in version 253\&. .RE .PP \fIDeviceTree=\fR\fI\fIPATH\fR\fR, \fB\-\-devicetree=\fR\fB\fIPATH\fR\fR @@ -224,6 +296,8 @@ file will be picked up from the host system\&. The devicetree description (the "\&.dtb" section)\&. The argument is a path to a compiled binary DeviceTree file\&. If not specified, the section will not be present\&. +.sp +Added in version 253\&. .RE .PP \fISplash=\fR\fI\fIPATH\fR\fR, \fB\-\-splash=\fR\fB\fIPATH\fR\fR @@ -231,6 +305,8 @@ section)\&. The argument is a path to a compiled binary DeviceTree file\&. If no A picture to display during boot (the "\&.splash" section)\&. The argument is a path to a BMP file\&. If not specified, the section will not be present\&. +.sp +Added in version 253\&. .RE .PP \fIPCRPKey=\fR\fI\fIPATH\fR\fR, \fB\-\-pcrpkey=\fR\fB\fIPATH\fR\fR @@ -240,6 +316,8 @@ A path to a public key to embed in the section\&. If not specified, and there\*(Aqs exactly one \fIPCRPublicKey=\fR/\fB\-\-pcr\-public\-key=\fR argument, that key will be used\&. Otherwise, the section will not be present\&. +.sp +Added in version 253\&. .RE .PP \fIUname=\fR\fI\fIVERSION\fR\fR, \fB\-\-uname=\fR\fB\fIVERSION\fR\fR @@ -248,6 +326,8 @@ Specify the kernel version (as in \fBuname \-r\fR, the "\&.uname" 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\&. +.sp +Added in version 253\&. .RE .PP \fIPCRBanks=\fR\fI\fIPATH\fR\fR, \fB\-\-pcr\-banks=\fR\fB\fIPATH\fR\fR @@ -256,6 +336,8 @@ A comma or space\-separated list of PCR banks to sign a policy for\&. If not pre "sha256", "sha384", "sha512"), which will fail if not supported by the system\&. +.sp +Added in version 253\&. .RE .PP \fISecureBootSigningTool=\fR\fI\fISIGNER\fR\fR, \fB\-\-signtool=\fR\fB\fISIGNER\fR\fR @@ -265,6 +347,8 @@ Whether to use or "pesign"\&. Depending on this choice, different parameters are required in order to sign an image\&. Defaults to "sbsign"\&. +.sp +Added in version 254\&. .RE .PP \fISecureBootPrivateKey=\fR\fI\fISB_KEY\fR\fR, \fB\-\-secureboot\-private\-key=\fR\fB\fISB_KEY\fR\fR @@ -273,6 +357,8 @@ A path to a private key to use for signing of the resulting binary\&. If the \fISigningEngine=\fR/\fB\-\-signing\-engine=\fR option is used, this may also be an engine\-specific designation\&. This option is required by \fISecureBootSigningTool=sbsign\fR/\fB\-\-signtool=sbsign\fR\&. +.sp +Added in version 253\&. .RE .PP \fISecureBootCertificate=\fR\fI\fISB_CERT\fR\fR, \fB\-\-secureboot\-certificate=\fR\fB\fISB_CERT\fR\fR @@ -281,6 +367,8 @@ A path to a certificate to use for signing of the resulting binary\&. If the \fISigningEngine=\fR/\fB\-\-signing\-engine=\fR option is used, this may also be an engine\-specific designation\&. This option is required by \fISecureBootSigningTool=sbsign\fR/\fB\-\-signtool=sbsign\fR\&. +.sp +Added in version 253\&. .RE .PP \fISecureBootCertificateDir=\fR\fI\fISB_PATH\fR\fR, \fB\-\-secureboot\-certificate\-dir=\fR\fB\fISB_PATH\fR\fR @@ -289,18 +377,24 @@ A path to a nss certificate database directory to use for signing of the resulti \fISecureBootSigningTool=pesign\fR/\fB\-\-signtool=pesign\fR is used\&. Defaults to /etc/pki/pesign\&. +.sp +Added in version 254\&. .RE .PP \fISecureBootCertificateName=\fR\fI\fISB_CERTNAME\fR\fR, \fB\-\-secureboot\-certificate\-name=\fR\fB\fISB_CERTNAME\fR\fR .RS 4 The name of the nss certificate database entry to use for signing of the resulting binary\&. This option is required by \fISecureBootSigningTool=pesign\fR/\fB\-\-signtool=pesign\fR\&. +.sp +Added in version 254\&. .RE .PP \fISecureBootCertificateValidity=\fR\fI\fIDAYS\fR\fR, \fB\-\-secureboot\-certificate\-validity=\fR\fB\fIDAYS\fR\fR .RS 4 Period of validity (in days) for a certificate created by \fBgenkey\fR\&. Defaults to 3650, i\&.e\&. 10 years\&. +.sp +Added in version 254\&. .RE .PP \fISigningEngine=\fR\fI\fIENGINE\fR\fR, \fB\-\-signing\-engine=\fR\fB\fIENGINE\fR\fR @@ -309,6 +403,8 @@ An "engine" for signing of the resulting binary\&. This option is currently pass \fB\-\-engine=\fR option of \fBsbsign\fR(1)\&. +.sp +Added in version 253\&. .RE .PP \fISignKernel=\fR\fI\fIBOOL\fR\fR, \fB\-\-sign\-kernel\fR, \fB\-\-no\-sign\-kernel\fR @@ -318,33 +414,43 @@ Override the detection of whether to sign the Linux binary itself before it is e option and the binary has not already been signed\&. If \fISignKernel=\fR/\fB\-\-sign\-kernel\fR is true, and the binary has already been signed, the signature will be appended anyway\&. +.sp +Added in version 253\&. .RE .PP \fISBAT=\fR\fI\fITEXT\fR\fR\fI|\fR\fI\fI@PATH\fR\fR, \fB\-\-sbat=\fR\fB\fITEXT\fR\fR\fB|\fR\fB\fI@PATH\fR\fR .RS 4 SBAT metadata associated with the UKI or addon\&. SBAT policies are useful to revoke whole groups of UKIs or 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 -"uki,1,UKI,uki,1,https://www\&.freedesktop\&.org/software/systemd/man/systemd\-stub\&.html" -will be used, to ensure it is always possible to revoke UKIs and addons\&. For more information on SBAT see -\m[blue]\fBShim\*(Aqs documentation\&.\fR\m[]\&\s-2\u[2]\d\s+2 +"uki,1,UKI,uki,1,https://uapi\-group\&.org/specifications/specs/unified_kernel_image/" +for UKIs and +"uki\-addon,1,UKI Addon,addon,1,https://www\&.freedesktop\&.org/software/systemd/man/latest/systemd\-stub\&.html" +for addons will be used, to ensure it is always possible to revoke them\&. For more information on SBAT see +\m[blue]\fBShim documentation\fR\m[]\&\s-2\u[2]\d\s+2\&. +.sp +Added in version 254\&. .RE .SS "[PCRSignature:\fINAME\fR] section" .PP -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\&. +In the config file, those options are grouped by section\&. On the command line, they must be specified in the same order\&. The sections specified in both sources are combined\&. .PP \fIPCRPrivateKey=\fR\fI\fIPATH\fR\fR, \fB\-\-pcr\-private\-key=\fR\fB\fIPATH\fR\fR .RS 4 -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\&. +A private key to use for signing PCR policies\&. On the command line, this option may be specified more than once, in which case multiple signatures will be made\&. +.sp +Added in version 253\&. .RE .PP \fIPCRPublicKey=\fR\fI\fIPATH\fR\fR, \fB\-\-pcr\-public\-key=\fR\fB\fIPATH\fR\fR .RS 4 A public key to use for signing PCR policies\&. .sp -On the commandline, this option may be specified more than once, similarly to the +On the command line, this option may be specified more than once, similarly to the \fB\-\-pcr\-private\-key=\fR -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\&. If not present, the public keys will be extracted from the private keys\&. On the command line, if present, this option must be specified the same number of times as the \fB\-\-pcr\-private\-key=\fR option\&. +.sp +Added in version 253\&. .RE .PP \fIPhases=\fR\fI\fILIST\fR\fR, \fB\-\-phases=\fR\fB\fILIST\fR\fR @@ -353,9 +459,11 @@ A comma or space\-separated list of colon\-separated phase paths to sign a polic \fBsystemd-measure\fR(1) will be used\&. .sp -On the commandline, when this argument is present, it must appear the same number of times as the +On the command line, when this argument is present, it must appear the same number of times as the \fB\-\-pcr\-private\-key=\fR option\&. +.sp +Added in version 253\&. .RE .SH "EXAMPLES" .PP @@ -384,12 +492,12 @@ This creates an unsigned UKI .RS 4 .\} .nf -$ /usr/lib/systemd/ukify build \e +$ ukify build \e \-\-linux=/lib/modules/6\&.0\&.9\-300\&.fc37\&.x86_64/vmlinuz \e \-\-initrd=early_cpio \e \-\-initrd=/some/path/initramfs\-6\&.0\&.9\-300\&.fc37\&.x86_64\&.img \e \-\-sbat=\*(Aqsbat,1,SBAT Version,sbat,1,https://github\&.com/rhboot/shim/blob/main/SBAT\&.md - uki\&.author\&.myimage,1,UKI for System,uki\&.author\&.myimage,1,https://www\&.freedesktop\&.org/software/systemd/man/systemd\-stub\&.html\*(Aq \e + uki\&.author\&.myimage,1,UKI for System,uki\&.author\&.myimage,1,https://uapi\-group\&.org/specifications/specs/unified_kernel_image/\*(Aq \e \-\-pcr\-private\-key=pcr\-private\-initrd\-key\&.pem \e \-\-pcr\-public\-key=pcr\-public\-initrd\-key\&.pem \e \-\-phases=\*(Aqenter\-initrd\*(Aq \e @@ -454,7 +562,7 @@ Phases=enter\-initrd:leave\-initrd enter\-initrd:leave\-initrd:sysinit enter\-initrd:leave\-initrd:sysinit:ready -$ /usr/lib/systemd/ukify \-c ukify\&.conf build \e +$ ukify \-c ukify\&.conf build \e \-\-linux=/lib/modules/6\&.0\&.9\-300\&.fc37\&.x86_64/vmlinuz \e \-\-initrd=/some/path/initramfs\-6\&.0\&.9\-300\&.fc37\&.x86_64\&.img @@ -463,7 +571,7 @@ $ /usr/lib/systemd/ukify \-c ukify\&.conf build \e .RE .\} .PP -One "initrd" (early_cpio) is specified in the config file, and the other initrd (initramfs\-6\&.0\&.9\-300\&.fc37\&.x86_64\&.img) 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\&. +One "initrd" (early_cpio) is specified in the config file, and the other initrd (initramfs\-6\&.0\&.9\-300\&.fc37\&.x86_64\&.img) is specified on the command line\&. 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\&. .PP \fBExample\ \&4.\ \&Kernel command line auxiliary PE\fR .sp @@ -476,7 +584,7 @@ ukify build \e \-\-secureboot\-certificate=sb\&.cert \e \-\-cmdline=\*(Aqdebug\*(Aq \e \-\-sbat=\*(Aqsbat,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\*(Aq + uki\-addon\&.author,1,UKI Addon for System,uki\-addon\&.author,1,https://www\&.freedesktop\&.org/software/systemd/man/systemd\-stub\&.html\*(Aq \-\-output=debug\&.cmdline .fi @@ -523,7 +631,7 @@ Next, we can generate the certificate and keys: .RS 4 .\} .nf -# /usr/lib/systemd/ukify genkey \-\-config=/etc/kernel/uki\&.conf +# ukify genkey \-\-config=/etc/kernel/uki\&.conf Writing SecureBoot private key to /etc/kernel/secure\-boot\&.key\&.pem Writing SecureBoot certificate to /etc/kernel/secure\-boot\&.cert\&.pem Writing private key for PCR signing to /etc/kernel/pcr\-initrd\&.key\&.pem @@ -538,7 +646,7 @@ Writing public key for PCR signing to /etc/kernel/pcr\-system\&.pub\&.pem (Both operations need to be done as root to allow write access to /etc/kernel/\&.) .PP -Subsequent invocations of using the config file (\fB/usr/lib/systemd/ukify build \-\-config=/etc/kernel/uki\&.conf\fR) will use this certificate and key files\&. Note that the +Subsequent invocations using the config file (\fBukify build \-\-config=/etc/kernel/uki\&.conf\fR) will use this certificate and key files\&. Note that the \fBkernel-install\fR(8) plugin 60\-ukify\&.install @@ -546,7 +654,7 @@ uses /etc/kernel/uki\&.conf by default, so after this file has been created, installations of kernels that create a UKI on the local machine using \fBkernel\-install\fR -would perform signing using this config\&. +will perform signing using this config\&. .SH "SEE ALSO" .PP \fBsystemd\fR(1), @@ -561,7 +669,7 @@ Unified Kernel Image (UKI) \%https://uapi-group.org/specifications/specs/unified_kernel_image/ .RE .IP " 2." 4 -Shim's documentation. +Shim documentation .RS 4 \%https://github.com/rhboot/shim/blob/main/SBAT.md .RE |