-
Notifications
You must be signed in to change notification settings - Fork 5
/
klp-build.1
237 lines (236 loc) · 6.2 KB
/
klp-build.1
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
.\" SPDX-License-Identifier: GPL-2.0-only
.\"
.\" Copyright (C) 2021-2024 SUSE
.\" Author: Fernando Gonzalez <[email protected]>
.\"
.TH klp-build 1
.SH NAME
klp-build \- the kernel livepatching creation tool
.SH SYNOPSIS
.B klp-build
<command> [-h] [-n NAME] [--filter FILTER]
.SH DESCRIPTION
.B klp-build
is a tool meant for automating the whole process of creating and testing
livepatches for the Linux kernel (SLE edition).
To reduce the burden of livepatch developement,
.B klp-build
is also capable of checking which codestreams are vulnerable, batching multiple
codestreams in parallel, and remotely building and running tests.
.SH OPTIONS
Generic options available for all commands:
.TP
.B "-h, --help"
Show command's help message and exit.
.TP
.BI "-n, --name" " NAME"
The livepatch name. This will be the directory name of the resulting
livepatches.
.TP
.BI --filter " FILTER"
List of accepted codestreams. Must be specified in regex format.
Example: "15\.3u[0-9]+|15\.6u0"
.SH COMMANDS
.TP
.B scan
In the scan,
.B klp-build
does a shallow analysis of the given CVE, searching for already patched codestreams
and reporting those that most likley are still affected by the bug.
This subcommand does not store any data, as it is mainly targeted for automation
and not for livepatch development. For the latter see the
.B setup
subcommand.
.RS 7
.TP
.BI --cve " CVE"
The CVE to be analyzed.
.RE
.TP
.B setup
During the setup,
.B klp-build
analysis each codestream in order to identify those affected by
the indicated CVE. Note that in this phase a lot of per-codestream
data is generated and stored for future use.
.RS 7
.TP
.BI --cve " CVE"
The CVE assigned to this livepatch.
.TP
.BI --conf " CONF"
The kernel CONFIG used to build the object to be livepatched.
.TP
.B --no-check
Do not check for already patched codestreams, do the setup for
all non filtered codestreams.
.TP
.BI --codestreams " CODESTREAMS"
Codestreams affected by the CVE. Can be used as a regex, like,
"15.u[34]".
.TP
.BI --file-funcs " [FILE_FUNCS ...]"
File and functions to be livepatched. Can be set multiple times. The format is:
.BI --file-funcs " file/path.c func1 func2..."
.BI --file-funcs " file/patch2.c func1 func2..."
.TP
.BI --mod-file-funcs " [MOD_FILE_FUNCS ...]"
Module, file and functions to be livepatched. Can be set multiple times. The
format is:
.BI --mod-file-funcs " module1 file/path.c func1 func2..."
.BI --mod-file-funcs " module2 file/patch2.c func1 func2..."
.TP
.BI --conf-mod-file-funcs " [CONF_MOD_FILE_FUNCS ...]"
Conf, module, file and functions to be livepatched. Can be set multiple times.
The format is:
.BI --conf-mod-file-funcs " conf1 module1 file/path.c func1 func2..."
.BI --conf-mod-file-funcs " conf2 module2 file/patch2.c func1 func2..."
.TP
.BI --module " MODULE"
The module that will be livepatched for all files. If empty,
.I vmlinux
will be livepatched instead.
.TP
.BI --archs " {ppc64le,s390x,x86_64} [{ppc64le,s390x,x86_64} ...]"
Supported architectures for this livepatch.
.TP
.BI --skips " SKIPS"
List of excluded codestreams. Must be specified in regex format.
Example: "15\.3u[0-9]+|15\.6u0"
.RE
.B check-inline
.RS 7
.TP
.BI --codestreams " CODESTREAMS"
Codestream to check the inlined symbol.
.TP
.BI --file " FILE"
File to be checked.
.TP
.BI --symbol " SYMBOL"
Symbol to be found.
.RE
.TP
.B extract
In this phase
.B klp-build
creates the livepatch for each affected codestream based on the data generated
during the
.BR setup "."
Results may differ greatly depending on the back-end tool selected for the
livepatch creation.
.RS 7
.TP
.BI --avoid-ext " AVOID_EXT [AVOID_EXT ...]"
Functions to be copied into the livepatch instead of externalizing them.
Useful to make sure to include symbols that are optimized in
different architectures.
.TP
.B --apply-patches
Apply patches found by
.B get-patches
command, if they exist.
.TP
.BI --codestreams " CODESTREAMS CODESTREAMS"
Apply diff on two different codestreams.
.RE
.TP
.B format-patches
Extract patches from kgraft-patches (see the
.BR "SEE ALSO" " section)."
.RS 7
.TP
.BI "-v , --version" " VERSION"
Version to be added, like vX.
.RE
.TP
.B get-patches
Find and list the kernel versions with a backported fix to the indicated CVE.
.RS 7
.TP
.BI --cve " CVE"
CVE number to search for related backported patches.
.RE
.TP
.B cleanup
Remove livepatch packages from SUSE's Build Service.
.TP
.B prepare-tests
Generates a tar archive per supported architecture containing
scripts and files that can later be used to run tests in the desired test benchs.
.TP
.B push
Push the generated livetpatch packages to SUSE's Build Service.
By doing so,
.B klp-build
can automate the building phase for each codestream and architecture.
.RS 7
.TP
.B --wait
Wait until all codestreams builds are finished.
.RE
.TP
.B status
Check the status of the livepatch building phase initiated by the
.B push
command.
.RS 7
.TP
.B --wait
Wait until all codestreams builds are finished.
.RE
.TP
.B log
Get build logs from SUSE'S Build Service.
.RS 7
.TP
.BI --cs " CS"
The codestream to get the log from.
.TP
.BI --arch " {ppc64le,s390x,x86_64}"
Build architecture.
.RE
.SH FILES
.TP
.I ~/.config/klp-build/config
Personal configuration file
.TP
.I ~/klp/livepatches
Default directory where the livepatch data will be
placed, including the data generated by the different stages of the livepatch
creation
.TP
.I ~/klp/data
Default directory where the dowloaded source code will be placed
.SH EXAMPLES
Check if the codestreams for SLE 15.5 x86_64 and ppc64le are affected by
CVE-2022-1048. This CVE affects
.I snd_pcm_attach_substream()
and
.I snd_pcm_detach_substream()
functions, located in the
kernel module
.IR snd-pcm .
.IP
$
.B klp-build
setup --name bsc1197597 --cve 2022-1048 --mod snd-pcm --conf
CONFIG_SND_PCM --file-funcs sound/core/pcm.c snd_pcm_attach_substream
snd_pcm_detach_substream --codestreams '15.5' --archs x86_64 ppc64le
.PP
.SH SEE ALSO
SUSE's kgraft-patches public repository:
.I https://github.com/SUSE/kernel-livepatch
.PP
SUSE's kernel-source public repository:
.I https://github.com/SUSE/kernel-source
.PP
.BR klp-ccp "(1) "
.SH AUTHOR
Contributors to the
.B klp-build
project. See the project’s GIT history for the complete list.
.SH DISTRIBUTION
The latest version of
.B klp-build
may be downloaded from https://github.com/SUSE/klp-build