~nabijaczleweli/klapki

ref: f1a7e2ddac90258ac2aed28ca07ec1a914966f3d klapki/klapki.8 -rw-r--r-- 13.0 KiB
f1a7e2dd — наб autouploader Manpage update by job 308699 6 months ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
.\" generated with Ronn-NG/v0.9.1
.\" http://github.com/apjanke/ronn-ng/tree/0.9.1
.TH "KLAPKI" "8" "September 2020" ""
.SH "NAME"
\fBklapki\fR \- EFI boot manager; or, well, an EFI bootorder compiler\.
.SH "SYNOPSIS"
\fBklapki\fR [\fB\-nvVEh\fR]… [\fBop\fR [\fBarg\fR…]]…
.SH "DESCRIPTION"
klapki(8) generates and manages EFI boot entries on platforms compatible therewith\.
.P
This command\-line interface is based on running a set of operations (see \fIOPS\fR) which modify the state and context, then settling the new set\-up, then committing it; this means that, barring I/O errors, \fB{dump}\fRing after the last operation with \fB\-n\fR is an accurate representation of what would be committed without it\.
.P
Care is taken to only write what is needed and only when it\'s needed – files and wanted entries are hashed with SHA1(3ssl) and only updated on mismatch; foreign entries are never touched, and klapki(8) prefers to abandon entries it doesn\'t understand than to accidentally mangle them\.
.P
Minimal state is stored, and it\'s only supplementary\. This means that removing all instances of a kernel boot entry with tools such as efibootmgr(8), efivar(1), or the platform UI will make klapki(8) forget about the kernel entirely, after minor complaints\.
.P
klapki(8)\'s entries \fIcan\fR be moved across \fBBootNNNN\fR entries, however, so long as they are kept identical\.
.P
The entry description and kernel cmdline are controlled via small executable files, see \fIWISDOM\fR\.
.SH "OPTIONS"
.TP
\fB\-n\fR
Don\'t commit – nothing will be written to the filesystem or the firmware\.
.TP
\fB\-v\fR
Verbose operation\.
.TP
\fB\-V\fR
Very verbose – adds a \fB{dump}\fR op in\-between each specified op\.
.TP
\fB\-E\fR
Increase libefivar verbosity level\.
.IP
At time of writing, libefivar supports \fBLOG_VERBOSE\fR and \fBLOG_DEBUG\fR, which require \fB\-E\fR to be specified one and two times, respectively\.
.IP
See the \fISEE ALSO\fR sexion for details\.
.TP
\fB\-h\fR
Show a help message with these flags, recognised environment variables (see \fIENVIRONMENT\fR) and ops (see \fIOPS\fR)\.
.TP
\fBop\fR [\fBarg\fR…]
Specify an operation to run and arguments to pass to it\.
.IP
See \fIOPS\fR for more detail\.
.SH "ENVIRONMENT"
.TP
\fBKLAPKI_HOST\fR=
By default, klapki(8) uses the value found in \fB/etc/machine\-id\fR (or, failing that, the current hostname, as obtained with gethostname(2)) as the identifier for the host\.
.IP
If this environment variable is present, it will be used instead; note, that the host identifier is used verbatim as an EFI variable name under klapki\'s GUID (a8a9ad3a\-f831\-11ea\-946d\-674ccd7415cc)\.
.TP
\fBKLAPKI_WISDOM\fR=
To obtain the description and cmdline, klapki(8) invokes respectively\-named files under the wisdom root via execl(3), which is \fB/etc/klapki\fR by default\. This value overrides that path\. If not empty, a \'/\' is additionally appended before the executable name\.
.IP
See also \fIWISDOM\fR below\.
.TP
\fBKLAPKI_EFI_ROOT\fR=
By default, klapki(8) puts newly\-installed files in \fB\eklapki\e{host}\e{version}\fR under the ESP\.
.IP
If present, this overrides the constant prefix\. Par exemple, setting \fBKLAPKI_EFI_ROOT\fR= when adding a kernel will put it and the initrds directly under \fB\e{host}\e{version}\fR (note that by default this collides with kernel\-install(8))\.
.SH "OPS"
.TP
\fBdump\fR
Write some state (boot order, total boot entries, boot position, each wanted entry, boot variants) and context (our kernels, fresh kernels, deleted files) to the standard output\.
.TP
\fBbootpos\fR <\fBposition\fR>
Change the boot position to 0\-based <\fBposition\fR>\.
.IP
The cluster of entries for the current host can be placed at any point in the boot order; it\'s 0 (i\.e\. at the beginning) by default, but if you have another operating system or boot\-loader and wish to have it be the default, you can simply move klapki(8) down the required amount of entries\.
.IP
See description of addvariant below for sorting inside the cluster\.
.TP
\fBaddkernel\fR <\fBversion\fR> <\fBimage\fR> [\fBinitrd\fR…] <\fB""\fR>
Allocate entries for the kernel with version <\fBversion\fR> whose image resides at <\fBimage\fR> and initrds at [\fBinitrd\fR]…\. The list of initrds is terminated with an empty argument\.
.IP
This directive is ignored if a kernel with version <\fBversion\fR> is already known\. See delkernel below\.
.IP
The kernel image and initrds will be copied to the ESP (see \fBKLAPKI_EFI_ROOT\fR= in \fIENVIRONMENT\fR) during context commit\.
.TP
\fBdelkernel\fR <\fBversion\fR>
Purge all entries for which the version is <\fBversion\fR>\.
.IP
The kernel image, initrds and containing folder will, if not used, be removed from the ESP during context commit\.
.TP
\fBaddvariant\fR <\fBvariant\fR>
Add an explicit variant <\fBvariant\fR> to the end, if not already known\. Accompanying boot entries will be allocated in the derivation phase as needed\.
.IP
Variants are a global property, and a boot entry is generated for each variant (that is: for the implicit variant, represented by the empty string, in addition to any configured explicit variants)\.
.IP
The order of explicit variants is preserved within each version group, which are sorted highest\-to\-lowest\. For example: a host with two kernels (\fI5\.8\.0\-[12]\-amd64\fR) and two explicit variants (\fIdebug\fR, \fIsilent\fR) will produce the following entries (assume \fB$KLAPKI_WISDOM/description\fR linked to \fB/bin/echo\fR); note how the highest kernel version is at the top:
.br
\~\~5\.8\.0\-2\-amd64
.br
\~\~5\.8\.0\-2\-amd64 debug
.br
\~\~5\.8\.0\-2\-amd64 silent
.br
\~\~5\.8\.0\-1\-amd64
.br
\~\~5\.8\.0\-1\-amd64 debug
.br
\~\~5\.8\.0\-1\-amd64 silent
.IP
After running klapki(8) with "\fIdelvariant debug addvariant debug\fR", the two explicit variants are now ordered differently (\fIsilent\fR, \fIdebug\fR), and this is reflected in the boot order; note also how the implicit variant always sorts earlier than any explicit ones:
.br
\~\~5\.8\.0\-2\-amd64
.br
\~\~5\.8\.0\-2\-amd64 silent
.br
\~\~5\.8\.0\-2\-amd64 debug
.br
\~\~5\.8\.0\-1\-amd64
.br
\~\~5\.8\.0\-1\-amd64 silent
.br
\~\~5\.8\.0\-1\-amd64 debug
.TP
\fBdelvariant\fR <\fBvariant\fR>
Remove explicit variant <\fBvariant\fR>, if any; accompanying boot entries will purged in the derivation phase as needed\.
.SH "WISDOM"
The entry description and kernel cmdline are acquired by executing \fBdescription\fR and \fBcmdline\fR in \fB/etc/klapki\fR (or \fBKLAPKI_WISDOM=\fR, see \fIENVIRONMENT\fR) with the following arguments:
.br
0: "description" or "cmdline"
.br
1: kernel version
.br
2: boot variant
.P
And the standard output tied to a memfd (see memfd_create(2)), which is then trimmed, and all newlines are replaced with a single space\.
.P
klapki(8) stops processing if the child exits with a non\-zero status or is killed by a signal\. The special exit value 0x6B (107, ASCII \'k\') is used to signal an error in execl(3)ing the wisdom binary\.
.P
Additional \fBinitrd=\fR statements \fIshould\fR work (with warnings, since the should\. Please report on the bug tracker/mailing list (see \fIREPORTING BUGS\fR) if you use them successfully!) and will not be managed by klapki(8),
.P
The simplest \fB/etc/klapki/description\fR would be a link to \fB/bin/echo\fR\. A simple \fBcmdline\fR is a \fB/bin/sh\fR shebang + \fBecho\fR command\. A cursed \fBcmdline\fR would be a \fB/bin/sh\fR shebang and an \fBawk \'{gsub(/initrd=[^ ]+ ?/, ""); print}\' /proc/cmdline\fR command\.
.SH "EXIT VALUES"
.nf
1 \- error reading configuration,
2 \- error loading state,
3 \- error resolving state,
4 \- error running an op,
5 \- error in propagation phase,
6 \- error in aging phase,
7 \- error in wisening phase,
8 \- error in saving phase,
9 \- error committing context,
10 \- error committing state\.
.fi
.SH "EXAMPLES"
A simple set\-up:
.IP "" 4
.nf
root@zoot:~# ls \-l description cmdline
\-rwxr\-xr\-x 1 root root 79 Sep 21 03:30 cmdline
lrwxrwxrwx 1 root root  9 Sep 20 04:30 description \-> /bin/echo
root@zoot:~# cat cmdline
#!/bin/sh
echo root=ZFS=zoot/root console=ttyS0
.fi
.IP "" 0
.P
Add a kernel with a single initrd and a variant:
.IP "" 4
.nf
root@zoot:~# KLAPKI_HOST=zoot klapki addkernel 5\.8\.0\-2\-amd64 /boot/vmlinuz\-5\.8\.0\-2\-amd64 /boot/initrd\.img\-5\.8\.0\-2\-amd64 "" addvariant debug
EFI load: no config for this host (zoot) found; going to the top
Entry 000B changed
Entry 000D changed
Entry 000B: copied vmlinuz\-5\.8\.0\-2\-amd64 from /boot to \eklapki\ezoot\e5\.8\.0\-2\-amd64\e
Entry 000B: copied initrd\.img\-5\.8\.0\-2\-amd64 from /boot to \eklapki\ezoot\e5\.8\.0\-2\-amd64\e
Updating state config
Updating boot order
Writing entry 000B
Writing entry 000D
.fi
.IP "" 0
.P
Success! But the new "debug" entry doesn\'t really do much:
.IP "" 4
.nf
root@zoot:~# efibootmgr
BootCurrent: 000D
Timeout: 0 seconds
BootOrder: 000B,000D,000C,000A,0000,0001,0002,0003,0004,0005,0006,0007,0008,0009
Boot0000 through Boot0008 omitted
Boot0009* EFI Internal Shell    FvVol(7cb8bdc9\-f8eb\-4f34\-aaea\-3ee4af6516a1)/FvFile(7c04a583\-9e3e\-4f1c\-ad65\-e05268d0b4d1)
Boot000A* Linux Boot Manager    HD(1,GPT,0655a4fb\-e2e9\-4fa6\-b37b\-a52633aed855,0x800,0x76800)/File(\eEFI\esystemd\esystemd\-bootx64\.efi)
Boot000B* 5\.8\.0\-2\-amd64 HD(1,GPT,0655a4fb\-e2e9\-4fa6\-b37b\-a52633aed855,0x800,0x76800)/File(\eklapki\ezoot\e5\.8\.0\-2\-amd64\evmlinuz\-5\.8\.0\-2\-amd64)i\.n\.i\.t\.r\.d\.=\.\e\.k\.l\.a\.p\.k\.i\.\e\.z\.o\.o\.t\.\e\.5\|\.\|\.\|\.8\|\.\|\.\|\.0\.\-\.2\.\-\.a\.m\.d\.6\.4\.\e\.i\.n\.i\.t\.r\.d\|\.\|\.\|\.i\.m\.g\.\-\.5\|\.\|\.\|\.8\|\.\|\.\|\.0\.\-\.2\.\-\.a\.m\.d\.6\.4\. \.r\.o\.o\.t\.=\.Z\.F\.S\.=\.z\.o\.o\.t\./\.r\.o\.o\.t\. \.c\.o\.n\.s\.o\.l\.e\.=\.t\.t\.y\.S\.0\.
Boot000C* zoot 5\.8\.0\-1\-amd64    HD(1,GPT,0655a4fb\-e2e9\-4fa6\-b37b\-a52633aed855,0x800,0x76800)/File(\e62dd03a4928c412180b3024ac6c03a90\e5\.8\.0\-1\-amd64\elinux)i\.n\.i\.t\.r\.d\.=\.\e\.6\.2\.d\.d\.0\.3\.a\.4\.9\.2\.8\.c\.4\.1\.2\.1\.8\.0\.b\.3\.0\.2\.4\.a\.c\.6\.c\.0\.3\.a\.9\.0\.\e\.5\|\.\|\.\|\.8\|\.\|\.\|\.0\.\-\.1\.\-\.a\.m\.d\.6\.4\.\e\.i\.n\.i\.t\.r\.d\|\.\|\.\|\.i\.m\.g\.\-\.5\|\.\|\.\|\.8\|\.\|\.\|\.0\.\-\.1\.\-\.a\.m\.d\.6\.4\. \.r\.o\.o\.t\.=\.Z\.F\.S\.=\.z\.o\.o\.t\./\.r\.o\.o\.t\. \.c\.o\.n\.s\.o\.l\.e\.=\.t\.t\.y\.S\.0\.
Boot000D* 5\.8\.0\-2\-amd64 debug   HD(1,GPT,0655a4fb\-e2e9\-4fa6\-b37b\-a52633aed855,0x800,0x76800)/File(\eklapki\ezoot\e5\.8\.0\-2\-amd64\evmlinuz\-5\.8\.0\-2\-amd64)i\.n\.i\.t\.r\.d\.=\.\e\.k\.l\.a\.p\.k\.i\.\e\.z\.o\.o\.t\.\e\.5\|\.\|\.\|\.8\|\.\|\.\|\.0\.\-\.2\.\-\.a\.m\.d\.6\.4\.\e\.i\.n\.i\.t\.r\.d\|\.\|\.\|\.i\.m\.g\.\-\.5\|\.\|\.\|\.8\|\.\|\.\|\.0\.\-\.2\.\-\.a\.m\.d\.6\.4\. \.r\.o\.o\.t\.=\.Z\.F\.S\.=\.z\.o\.o\.t\./\.r\.o\.o\.t\. \.c\.o\.n\.s\.o\.l\.e\.=\.t\.t\.y\.S\.0\.
.fi
.IP "" 0
.P
Uncontrivedly, adding a conditional with another argument to enable debugging in the Intel PRO/100 driver and re\-running klapki(8) will work:
.IP "" 4
.nf
root@zoot:~# cat cmdline
#!/bin/sh
echo root=ZFS=zoot/root console=ttyS0
[ "$2" = "debug" ] && echo e100\.debug=16 || :

root@zoot:~# KLAPKI_WISDOM=\. KLAPKI_HOST=zoot klapki
Entry 000D changed
Updating state config
Updating entry 000D
.fi
.IP "" 0
.P
Note, that, as expected, only the state configuration (which stores the hash of the wanted entry) and the debug entry itself was updated:
.IP "" 4
.nf
root@zoot:~# efibootmgr \-v
BootCurrent: 000D
Timeout: 0 seconds
BootOrder: 000B,000D,000C,000A,0000,0001,0002,0003,0004,0005,0006,0007,0008,0009
Boot0000 through Boot000A and Boot000C omitted
Boot000B* 5\.8\.0\-2\-amd64 HD(1,GPT,0655a4fb\-e2e9\-4fa6\-b37b\-a52633aed855,0x800,0x76800)/File(\eklapki\ezoot\e5\.8\.0\-2\-amd64\evmlinuz\-5\.8\.0\-2\-amd64)i\.n\.i\.t\.r\.d\.=\.\e\.k\.l\.a\.p\.k\.i\.\e\.z\.o\.o\.t\.\e\.5\|\.\|\.\|\.8\|\.\|\.\|\.0\.\-\.2\.\-\.a\.m\.d\.6\.4\.\e\.i\.n\.i\.t\.r\.d\|\.\|\.\|\.i\.m\.g\.\-\.5\|\.\|\.\|\.8\|\.\|\.\|\.0\.\-\.2\.\-\.a\.m\.d\.6\.4\. \.r\.o\.o\.t\.=\.Z\.F\.S\.=\.z\.o\.o\.t\./\.r\.o\.o\.t\. \.c\.o\.n\.s\.o\.l\.e\.=\.t\.t\.y\.S\.0\.
Boot000D* 5\.8\.0\-2\-amd64 debug   HD(1,GPT,0655a4fb\-e2e9\-4fa6\-b37b\-a52633aed855,0x800,0x76800)/File(\eklapki\ezoot\e5\.8\.0\-2\-amd64\evmlinuz\-5\.8\.0\-2\-amd64)i\.n\.i\.t\.r\.d\.=\.\e\.k\.l\.a\.p\.k\.i\.\e\.z\.o\.o\.t\.\e\.5\|\.\|\.\|\.8\|\.\|\.\|\.0\.\-\.2\.\-\.a\.m\.d\.6\.4\.\e\.i\.n\.i\.t\.r\.d\|\.\|\.\|\.i\.m\.g\.\-\.5\|\.\|\.\|\.8\|\.\|\.\|\.0\.\-\.2\.\-\.a\.m\.d\.6\.4\. \.r\.o\.o\.t\.=\.Z\.F\.S\.=\.z\.o\.o\.t\./\.r\.o\.o\.t\. \.c\.o\.n\.s\.o\.l\.e\.=\.t\.t\.y\.S\.0\. \.e\.1\.0\.0\|\.\|\.\|\.d\.e\.b\.u\.g\.=\.1\.6\.
.fi
.IP "" 0
.SH "AUTHOR"
Written by наб <\fInabijaczleweli@nabijaczleweli\.xyz\fR>
.SH "SPECIAL THANKS"
To all who support further development, in particular:
.IP "\[ci]" 4
ThePhD
.IP "\[ci]" 4
Embark Studios
.IP "" 0
.SH "REPORTING BUGS"
<\fIhttps://todo\.sr\.ht/~nabijaczleweli/klapki\fR>
.P
<\fI~nabijaczleweli/klapki@lists\.sr\.ht\fR>, archived at <\fIhttps://lists\.sr\.ht/~nabijaczleweli/klapki\fR>
.SH "SEE ALSO"
<\fIhttps://git\.sr\.ht/~nabijaczleweli/klapki\fR>
.P
UEFI specification, Sexion 3\.1\.3 Load Options and related: <\fIhttps://uefi\.org/sites/default/files/resources/UEFI_Spec_2_8_final\.pdf\fR>
.P
libefivar verbosity levels: <\fIhttps://github\.com/rhboot/efivar/blob/36297adcb266f07bb06e725a0da377bc6e6aedd0/src/util\.h#L328\fR>