| 1 | =========
|
| 2 | Livepatch
|
| 3 | =========
|
| 4 |
|
| 5 | This document outlines basic information about kernel livepatching.
|
| 6 |
|
| 7 | |
| 8 |
|
| 9 | .. contents:: :local:
|
| 10 |
|
| 11 |
|
| 12 | 1. Motivation
|
| 13 | =============
|
| 14 |
|
| 15 | There are many situations where users are reluctant to reboot a system. It may
|
| 16 | be because their system is performing complex scientific computations or under
|
| 17 | heavy load during peak usage. In addition to keeping systems up and running,
|
| 18 | users want to also have a stable and secure system. Livepatching gives users
|
| 19 | both by allowing for function calls to be redirected; thus, fixing critical
|
| 20 | functions without a system reboot.
|
| 21 |
|
| 22 |
|
| 23 | 2. Kprobes, Ftrace, Livepatching
|
| 24 | ================================
|
| 25 |
|
| 26 | There are multiple mechanisms in the Linux kernel that are directly related
|
| 27 | to redirection of code execution; namely: kernel probes, function tracing,
|
| 28 | and livepatching:
|
| 29 |
|
| 30 | - The kernel probes are the most generic. The code can be redirected by
|
| 31 | putting a breakpoint instruction instead of any instruction.
|
| 32 |
|
| 33 | - The function tracer calls the code from a predefined location that is
|
| 34 | close to the function entry point. This location is generated by the
|
| 35 | compiler using the '-pg' gcc option.
|
| 36 |
|
| 37 | - Livepatching typically needs to redirect the code at the very beginning
|
| 38 | of the function entry before the function parameters or the stack
|
| 39 | are in any way modified.
|
| 40 |
|
| 41 | All three approaches need to modify the existing code at runtime. Therefore
|
| 42 | they need to be aware of each other and not step over each other's toes.
|
| 43 | Most of these problems are solved by using the dynamic ftrace framework as
|
| 44 | a base. A Kprobe is registered as a ftrace handler when the function entry
|
| 45 | is probed, see CONFIG_KPROBES_ON_FTRACE. Also an alternative function from
|
| 46 | a live patch is called with the help of a custom ftrace handler. But there are
|
| 47 | some limitations, see below.
|
| 48 |
|
| 49 |
|
| 50 | 3. Consistency model
|
| 51 | ====================
|
| 52 |
|
| 53 | Functions are there for a reason. They take some input parameters, acquire or
|
| 54 | release locks, read, process, and even write some data in a defined way,
|
| 55 | have return values. In other words, each function has a defined semantic.
|
| 56 |
|
| 57 | Many fixes do not change the semantic of the modified functions. For
|
| 58 | example, they add a NULL pointer or a boundary check, fix a race by adding
|
| 59 | a missing memory barrier, or add some locking around a critical section.
|
| 60 | Most of these changes are self contained and the function presents itself
|
| 61 | the same way to the rest of the system. In this case, the functions might
|
| 62 | be updated independently one by one.
|
| 63 |
|
| 64 | But there are more complex fixes. For example, a patch might change
|
| 65 | ordering of locking in multiple functions at the same time. Or a patch
|
| 66 | might exchange meaning of some temporary structures and update
|
| 67 | all the relevant functions. In this case, the affected unit
|
| 68 | (thread, whole kernel) need to start using all new versions of
|
| 69 | the functions at the same time. Also the switch must happen only
|
| 70 | when it is safe to do so, e.g. when the affected locks are released
|
| 71 | or no data are stored in the modified structures at the moment.
|
| 72 |
|
| 73 | The theory about how to apply functions a safe way is rather complex.
|
| 74 | The aim is to define a so-called consistency model. It attempts to define
|
| 75 | conditions when the new implementation could be used so that the system
|
| 76 | stays consistent.
|
| 77 |
|
| 78 | Livepatch has a consistency model which is a hybrid of kGraft and
|
| 79 | kpatch: it uses kGraft's per-task consistency and syscall barrier
|
| 80 | switching combined with kpatch's stack trace switching. There are also
|
| 81 | a number of fallback options which make it quite flexible.
|
| 82 |
|
| 83 | Patches are applied on a per-task basis, when the task is deemed safe to
|
| 84 | switch over. When a patch is enabled, livepatch enters into a
|
| 85 | transition state where tasks are converging to the patched state.
|
| 86 | Usually this transition state can complete in a few seconds. The same
|
| 87 | sequence occurs when a patch is disabled, except the tasks converge from
|
| 88 | the patched state to the unpatched state.
|
| 89 |
|
| 90 | An interrupt handler inherits the patched state of the task it
|
| 91 | interrupts. The same is true for forked tasks: the child inherits the
|
| 92 | patched state of the parent.
|
| 93 |
|
| 94 | Livepatch uses several complementary approaches to determine when it's
|
| 95 | safe to patch tasks:
|
| 96 |
|
| 97 | 1. The first and most effective approach is stack checking of sleeping
|
| 98 | tasks. If no affected functions are on the stack of a given task,
|
| 99 | the task is patched. In most cases this will patch most or all of
|
| 100 | the tasks on the first try. Otherwise it'll keep trying
|
| 101 | periodically. This option is only available if the architecture has
|
| 102 | reliable stacks (HAVE_RELIABLE_STACKTRACE).
|
| 103 |
|
| 104 | 2. The second approach, if needed, is kernel exit switching. A
|
| 105 | task is switched when it returns to user space from a system call, a
|
| 106 | user space IRQ, or a signal. It's useful in the following cases:
|
| 107 |
|
| 108 | a) Patching I/O-bound user tasks which are sleeping on an affected
|
| 109 | function. In this case you have to send SIGSTOP and SIGCONT to
|
| 110 | force it to exit the kernel and be patched.
|
| 111 | b) Patching CPU-bound user tasks. If the task is highly CPU-bound
|
| 112 | then it will get patched the next time it gets interrupted by an
|
| 113 | IRQ.
|
| 114 |
|
| 115 | 3. For idle "swapper" tasks, since they don't ever exit the kernel, they
|
| 116 | instead have a klp_update_patch_state() call in the idle loop which
|
| 117 | allows them to be patched before the CPU enters the idle state.
|
| 118 |
|
| 119 | (Note there's not yet such an approach for kthreads.)
|
| 120 |
|
| 121 | Architectures which don't have HAVE_RELIABLE_STACKTRACE solely rely on
|
| 122 | the second approach. It's highly likely that some tasks may still be
|
| 123 | running with an old version of the function, until that function
|
| 124 | returns. In this case you would have to signal the tasks. This
|
| 125 | especially applies to kthreads. They may not be woken up and would need
|
| 126 | to be forced. See below for more information.
|
| 127 |
|
| 128 | Unless we can come up with another way to patch kthreads, architectures
|
| 129 | without HAVE_RELIABLE_STACKTRACE are not considered fully supported by
|
| 130 | the kernel livepatching.
|
| 131 |
|
| 132 | The /sys/kernel/livepatch/<patch>/transition file shows whether a patch
|
| 133 | is in transition. Only a single patch can be in transition at a given
|
| 134 | time. A patch can remain in transition indefinitely, if any of the tasks
|
| 135 | are stuck in the initial patch state.
|
| 136 |
|
| 137 | A transition can be reversed and effectively canceled by writing the
|
| 138 | opposite value to the /sys/kernel/livepatch/<patch>/enabled file while
|
| 139 | the transition is in progress. Then all the tasks will attempt to
|
| 140 | converge back to the original patch state.
|
| 141 |
|
| 142 | There's also a /proc/<pid>/patch_state file which can be used to
|
| 143 | determine which tasks are blocking completion of a patching operation.
|
| 144 | If a patch is in transition, this file shows 0 to indicate the task is
|
| 145 | unpatched and 1 to indicate it's patched. Otherwise, if no patch is in
|
| 146 | transition, it shows -1. Any tasks which are blocking the transition
|
| 147 | can be signaled with SIGSTOP and SIGCONT to force them to change their
|
| 148 | patched state. This may be harmful to the system though. Sending a fake signal
|
| 149 | to all remaining blocking tasks is a better alternative. No proper signal is
|
| 150 | actually delivered (there is no data in signal pending structures). Tasks are
|
| 151 | interrupted or woken up, and forced to change their patched state. The fake
|
| 152 | signal is automatically sent every 15 seconds.
|
| 153 |
|
| 154 | Administrator can also affect a transition through
|
| 155 | /sys/kernel/livepatch/<patch>/force attribute. Writing 1 there clears
|
| 156 | TIF_PATCH_PENDING flag of all tasks and thus forces the tasks to the patched
|
| 157 | state. Important note! The force attribute is intended for cases when the
|
| 158 | transition gets stuck for a long time because of a blocking task. Administrator
|
| 159 | is expected to collect all necessary data (namely stack traces of such blocking
|
| 160 | tasks) and request a clearance from a patch distributor to force the transition.
|
| 161 | Unauthorized usage may cause harm to the system. It depends on the nature of the
|
| 162 | patch, which functions are (un)patched, and which functions the blocking tasks
|
| 163 | are sleeping in (/proc/<pid>/stack may help here). Removal (rmmod) of patch
|
| 164 | modules is permanently disabled when the force feature is used. It cannot be
|
| 165 | guaranteed there is no task sleeping in such module. It implies unbounded
|
| 166 | reference count if a patch module is disabled and enabled in a loop.
|
| 167 |
|
| 168 | Moreover, the usage of force may also affect future applications of live
|
| 169 | patches and cause even more harm to the system. Administrator should first
|
| 170 | consider to simply cancel a transition (see above). If force is used, reboot
|
| 171 | should be planned and no more live patches applied.
|
| 172 |
|
| 173 | 3.1 Adding consistency model support to new architectures
|
| 174 | ---------------------------------------------------------
|
| 175 |
|
| 176 | For adding consistency model support to new architectures, there are a
|
| 177 | few options:
|
| 178 |
|
| 179 | 1) Add CONFIG_HAVE_RELIABLE_STACKTRACE. This means porting objtool, and
|
| 180 | for non-DWARF unwinders, also making sure there's a way for the stack
|
| 181 | tracing code to detect interrupts on the stack.
|
| 182 |
|
| 183 | 2) Alternatively, ensure that every kthread has a call to
|
| 184 | klp_update_patch_state() in a safe location. Kthreads are typically
|
| 185 | in an infinite loop which does some action repeatedly. The safe
|
| 186 | location to switch the kthread's patch state would be at a designated
|
| 187 | point in the loop where there are no locks taken and all data
|
| 188 | structures are in a well-defined state.
|
| 189 |
|
| 190 | The location is clear when using workqueues or the kthread worker
|
| 191 | API. These kthreads process independent actions in a generic loop.
|
| 192 |
|
| 193 | It's much more complicated with kthreads which have a custom loop.
|
| 194 | There the safe location must be carefully selected on a case-by-case
|
| 195 | basis.
|
| 196 |
|
| 197 | In that case, arches without HAVE_RELIABLE_STACKTRACE would still be
|
| 198 | able to use the non-stack-checking parts of the consistency model:
|
| 199 |
|
| 200 | a) patching user tasks when they cross the kernel/user space
|
| 201 | boundary; and
|
| 202 |
|
| 203 | b) patching kthreads and idle tasks at their designated patch points.
|
| 204 |
|
| 205 | This option isn't as good as option 1 because it requires signaling
|
| 206 | user tasks and waking kthreads to patch them. But it could still be
|
| 207 | a good backup option for those architectures which don't have
|
| 208 | reliable stack traces yet.
|
| 209 |
|
| 210 |
|
| 211 | 4. Livepatch module
|
| 212 | ===================
|
| 213 |
|
| 214 | Livepatches are distributed using kernel modules, see
|
| 215 | samples/livepatch/livepatch-sample.c.
|
| 216 |
|
| 217 | The module includes a new implementation of functions that we want
|
| 218 | to replace. In addition, it defines some structures describing the
|
| 219 | relation between the original and the new implementation. Then there
|
| 220 | is code that makes the kernel start using the new code when the livepatch
|
| 221 | module is loaded. Also there is code that cleans up before the
|
| 222 | livepatch module is removed. All this is explained in more details in
|
| 223 | the next sections.
|
| 224 |
|
| 225 |
|
| 226 | 4.1. New functions
|
| 227 | ------------------
|
| 228 |
|
| 229 | New versions of functions are typically just copied from the original
|
| 230 | sources. A good practice is to add a prefix to the names so that they
|
| 231 | can be distinguished from the original ones, e.g. in a backtrace. Also
|
| 232 | they can be declared as static because they are not called directly
|
| 233 | and do not need the global visibility.
|
| 234 |
|
| 235 | The patch contains only functions that are really modified. But they
|
| 236 | might want to access functions or data from the original source file
|
| 237 | that may only be locally accessible. This can be solved by a special
|
| 238 | relocation section in the generated livepatch module, see
|
| 239 | Documentation/livepatch/module-elf-format.rst for more details.
|
| 240 |
|
| 241 |
|
| 242 | 4.2. Metadata
|
| 243 | -------------
|
| 244 |
|
| 245 | The patch is described by several structures that split the information
|
| 246 | into three levels:
|
| 247 |
|
| 248 | - struct klp_func is defined for each patched function. It describes
|
| 249 | the relation between the original and the new implementation of a
|
| 250 | particular function.
|
| 251 |
|
| 252 | The structure includes the name, as a string, of the original function.
|
| 253 | The function address is found via kallsyms at runtime.
|
| 254 |
|
| 255 | Then it includes the address of the new function. It is defined
|
| 256 | directly by assigning the function pointer. Note that the new
|
| 257 | function is typically defined in the same source file.
|
| 258 |
|
| 259 | As an optional parameter, the symbol position in the kallsyms database can
|
| 260 | be used to disambiguate functions of the same name. This is not the
|
| 261 | absolute position in the database, but rather the order it has been found
|
| 262 | only for a particular object ( vmlinux or a kernel module ). Note that
|
| 263 | kallsyms allows for searching symbols according to the object name.
|
| 264 |
|
| 265 | - struct klp_object defines an array of patched functions (struct
|
| 266 | klp_func) in the same object. Where the object is either vmlinux
|
| 267 | (NULL) or a module name.
|
| 268 |
|
| 269 | The structure helps to group and handle functions for each object
|
| 270 | together. Note that patched modules might be loaded later than
|
| 271 | the patch itself and the relevant functions might be patched
|
| 272 | only when they are available.
|
| 273 |
|
| 274 |
|
| 275 | - struct klp_patch defines an array of patched objects (struct
|
| 276 | klp_object).
|
| 277 |
|
| 278 | This structure handles all patched functions consistently and eventually,
|
| 279 | synchronously. The whole patch is applied only when all patched
|
| 280 | symbols are found. The only exception are symbols from objects
|
| 281 | (kernel modules) that have not been loaded yet.
|
| 282 |
|
| 283 | For more details on how the patch is applied on a per-task basis,
|
| 284 | see the "Consistency model" section.
|
| 285 |
|
| 286 |
|
| 287 | 5. Livepatch life-cycle
|
| 288 | =======================
|
| 289 |
|
| 290 | Livepatching can be described by five basic operations:
|
| 291 | loading, enabling, replacing, disabling, removing.
|
| 292 |
|
| 293 | Where the replacing and the disabling operations are mutually
|
| 294 | exclusive. They have the same result for the given patch but
|
| 295 | not for the system.
|
| 296 |
|
| 297 |
|
| 298 | 5.1. Loading
|
| 299 | ------------
|
| 300 |
|
| 301 | The only reasonable way is to enable the patch when the livepatch kernel
|
| 302 | module is being loaded. For this, klp_enable_patch() has to be called
|
| 303 | in the module_init() callback. There are two main reasons:
|
| 304 |
|
| 305 | First, only the module has an easy access to the related struct klp_patch.
|
| 306 |
|
| 307 | Second, the error code might be used to refuse loading the module when
|
| 308 | the patch cannot get enabled.
|
| 309 |
|
| 310 |
|
| 311 | 5.2. Enabling
|
| 312 | -------------
|
| 313 |
|
| 314 | The livepatch gets enabled by calling klp_enable_patch() from
|
| 315 | the module_init() callback. The system will start using the new
|
| 316 | implementation of the patched functions at this stage.
|
| 317 |
|
| 318 | First, the addresses of the patched functions are found according to their
|
| 319 | names. The special relocations, mentioned in the section "New functions",
|
| 320 | are applied. The relevant entries are created under
|
| 321 | /sys/kernel/livepatch/<name>. The patch is rejected when any above
|
| 322 | operation fails.
|
| 323 |
|
| 324 | Second, livepatch enters into a transition state where tasks are converging
|
| 325 | to the patched state. If an original function is patched for the first
|
| 326 | time, a function specific struct klp_ops is created and an universal
|
| 327 | ftrace handler is registered\ . This stage is indicated by a value of '1'
|
| 328 | in /sys/kernel/livepatch/<name>/transition. For more information about
|
| 329 | this process, see the "Consistency model" section.
|
| 330 |
|
| 331 | Finally, once all tasks have been patched, the 'transition' value changes
|
| 332 | to '0'.
|
| 333 |
|
| 334 | |
| 335 |
|
| 336 | Note that functions might be patched multiple times. The ftrace handler
|
| 337 | is registered only once for a given function. Further patches just add
|
| 338 | an entry to the list (see field `func_stack`) of the struct klp_ops.
|
| 339 | The right implementation is selected by the ftrace handler, see
|
| 340 | the "Consistency model" section.
|
| 341 |
|
| 342 | That said, it is highly recommended to use cumulative livepatches
|
| 343 | because they help keeping the consistency of all changes. In this case,
|
| 344 | functions might be patched two times only during the transition period.
|
| 345 |
|
| 346 |
|
| 347 | 5.3. Replacing
|
| 348 | --------------
|
| 349 |
|
| 350 | All enabled patches might get replaced by a cumulative patch that
|
| 351 | has the .replace flag set.
|
| 352 |
|
| 353 | Once the new patch is enabled and the 'transition' finishes then
|
| 354 | all the functions (struct klp_func) associated with the replaced
|
| 355 | patches are removed from the corresponding struct klp_ops. Also
|
| 356 | the ftrace handler is unregistered and the struct klp_ops is
|
| 357 | freed when the related function is not modified by the new patch
|
| 358 | and func_stack list becomes empty.
|
| 359 |
|
| 360 | See Documentation/livepatch/cumulative-patches.rst for more details.
|
| 361 |
|
| 362 |
|
| 363 | 5.4. Disabling
|
| 364 | --------------
|
| 365 |
|
| 366 | Enabled patches might get disabled by writing '0' to
|
| 367 | /sys/kernel/livepatch/<name>/enabled.
|
| 368 |
|
| 369 | First, livepatch enters into a transition state where tasks are converging
|
| 370 | to the unpatched state. The system starts using either the code from
|
| 371 | the previously enabled patch or even the original one. This stage is
|
| 372 | indicated by a value of '1' in /sys/kernel/livepatch/<name>/transition.
|
| 373 | For more information about this process, see the "Consistency model"
|
| 374 | section.
|
| 375 |
|
| 376 | Second, once all tasks have been unpatched, the 'transition' value changes
|
| 377 | to '0'. All the functions (struct klp_func) associated with the to-be-disabled
|
| 378 | patch are removed from the corresponding struct klp_ops. The ftrace handler
|
| 379 | is unregistered and the struct klp_ops is freed when the func_stack list
|
| 380 | becomes empty.
|
| 381 |
|
| 382 | Third, the sysfs interface is destroyed.
|
| 383 |
|
| 384 |
|
| 385 | 5.5. Removing
|
| 386 | -------------
|
| 387 |
|
| 388 | Module removal is only safe when there are no users of functions provided
|
| 389 | by the module. This is the reason why the force feature permanently
|
| 390 | disables the removal. Only when the system is successfully transitioned
|
| 391 | to a new patch state (patched/unpatched) without being forced it is
|
| 392 | guaranteed that no task sleeps or runs in the old code.
|
| 393 |
|
| 394 |
|
| 395 | 6. Sysfs
|
| 396 | ========
|
| 397 |
|
| 398 | Information about the registered patches can be found under
|
| 399 | /sys/kernel/livepatch. The patches could be enabled and disabled
|
| 400 | by writing there.
|
| 401 |
|
| 402 | /sys/kernel/livepatch/<patch>/force attributes allow administrator to affect a
|
| 403 | patching operation.
|
| 404 |
|
| 405 | See Documentation/ABI/testing/sysfs-kernel-livepatch for more details.
|
| 406 |
|
| 407 |
|
| 408 | 7. Limitations
|
| 409 | ==============
|
| 410 |
|
| 411 | The current Livepatch implementation has several limitations:
|
| 412 |
|
| 413 | - Only functions that can be traced could be patched.
|
| 414 |
|
| 415 | Livepatch is based on the dynamic ftrace. In particular, functions
|
| 416 | implementing ftrace or the livepatch ftrace handler could not be
|
| 417 | patched. Otherwise, the code would end up in an infinite loop. A
|
| 418 | potential mistake is prevented by marking the problematic functions
|
| 419 | by "notrace".
|
| 420 |
|
| 421 |
|
| 422 |
|
| 423 | - Livepatch works reliably only when the dynamic ftrace is located at
|
| 424 | the very beginning of the function.
|
| 425 |
|
| 426 | The function need to be redirected before the stack or the function
|
| 427 | parameters are modified in any way. For example, livepatch requires
|
| 428 | using -fentry gcc compiler option on x86_64.
|
| 429 |
|
| 430 | One exception is the PPC port. It uses relative addressing and TOC.
|
| 431 | Each function has to handle TOC and save LR before it could call
|
| 432 | the ftrace handler. This operation has to be reverted on return.
|
| 433 | Fortunately, the generic ftrace code has the same problem and all
|
| 434 | this is handled on the ftrace level.
|
| 435 |
|
| 436 |
|
| 437 | - Kretprobes using the ftrace framework conflict with the patched
|
| 438 | functions.
|
| 439 |
|
| 440 | Both kretprobes and livepatches use a ftrace handler that modifies
|
| 441 | the return address. The first user wins. Either the probe or the patch
|
| 442 | is rejected when the handler is already in use by the other.
|
| 443 |
|
| 444 |
|
| 445 | - Kprobes in the original function are ignored when the code is
|
| 446 | redirected to the new implementation.
|
| 447 |
|
| 448 | There is a work in progress to add warnings about this situation.
|