mirror of https://github.com/dynup/kpatch
rearrange README and add some more content
- move license to bottom - clarify dependencies and installation procedure - move gotchas section to installation section - move status section to intro - add more information about how it works
This commit is contained in:
Josh Poimboeuf
parent
06ed1bdcc0
commit
843a42298b
152
README.md
152
README.md
|
|
@ -9,17 +9,38 @@ scale-out, run on a single machine and are very downtime
|
|||
sensitive or require a heavyweight approval process and
|
||||
notification of workload users in the event of downtime.
|
||||
|
||||
kpatch is currently is early development. For now, it should _not_ be used
|
||||
in production environments until significantly more testing on various
|
||||
patches and environments is conducted.
|
||||
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
The default install prefix is in /usr/local.
|
||||
*NOTE: These installation instructions are currently Fedora-specific. Support
|
||||
for other distributions is planned soon.*
|
||||
|
||||
Install the dependencies for compiling kpatch:
|
||||
|
||||
sudo yum install gcc kernel-devel elfutils elfutils-devel
|
||||
|
||||
*NOTE: Ensure you have elfutils-0.158 or newer.*
|
||||
|
||||
Install the dependencies for the "kpatch build" command:
|
||||
|
||||
sudo yum install rpmdevtools pesign
|
||||
sudo yum-builddep kernel
|
||||
|
||||
Compile kpatch:
|
||||
|
||||
make
|
||||
|
||||
Install kpatch to /usr/local:
|
||||
|
||||
sudo make install
|
||||
|
||||
|
||||
Quick Start
|
||||
Quick start
|
||||
-----------
|
||||
|
||||
*NOTE: While kpatch is designed to work with any recent Linux
|
||||
|
|
@ -47,6 +68,64 @@ directory. Now apply it to the running kernel:
|
|||
Done! The kernel is now patched.
|
||||
|
||||
|
||||
How it works
|
||||
------------
|
||||
|
||||
### kpatch build
|
||||
|
||||
The "kpatch build" command converts a source-level diff patch file to a hot
|
||||
patch kernel module. Most of its work is performed by the kpatch-build script
|
||||
which uses a collection of utilities: `create-diff-object`,
|
||||
`add-patch-section`, and `link-vmlinux-syms`.
|
||||
|
||||
The primary steps in kpatch-build are:
|
||||
- Build the unstripped vmlinux for the kernel
|
||||
- Patch the source tree
|
||||
- Rebuild vmlinux and monitor which objects are being rebuilt.
|
||||
These are the "changed objects".
|
||||
- Recompile each changed object with `-ffunction-sections -fdata-sections`,
|
||||
resulting in the changed patched objects
|
||||
- Unpatch the source tree
|
||||
- Recompile each changed object with `-ffunction-sections -fdata-sections`,
|
||||
resulting in the changed original objects
|
||||
- Use `create-diff-object` to analyze each original/patched object pair
|
||||
for patchability and generate an output object containing modified
|
||||
sections
|
||||
- Link all the output objects into a cumulative object
|
||||
- Use `add-patches-section` to add the .patches section that the
|
||||
core kpatch module uses to determine the list of functions that need
|
||||
to be redirected using ftrace
|
||||
- Generate the patch kernel module
|
||||
- Use `link-vmlinux-syms` to hardcode non-exported kernel symbols
|
||||
into the symbol table of the patch kernel module
|
||||
|
||||
### Patching
|
||||
|
||||
The hot patch kernel modules register with the core module (`kpatch.ko`).
|
||||
They provide information about original functions that need to be replaced, and
|
||||
corresponding function pointers to the replacement functions.
|
||||
|
||||
The kpatch core module registers a trampoline function with ftrace. The
|
||||
trampoline function is called by ftrace immediately before the original
|
||||
function begins executing. This occurs with the help of the reserved mcount
|
||||
call at the beginning of every function, created by the gcc `-mfentry` flag.
|
||||
The trampoline function then modifies the return instruction pointer (IP)
|
||||
address on the stack and returns to ftrace, which then restores the original
|
||||
function's arguments and stack, and "returns" to the new function.
|
||||
|
||||
|
||||
Demonstration
|
||||
-------------
|
||||
|
||||
A low-level demonstration of kpatch is available on Youtube:
|
||||
|
||||
http://www.youtube.com/watch?v=WeSmG-XirC4
|
||||
|
||||
This demonstration completes each step in the previous section in a manual
|
||||
fashion. However, from a end-user perspective, most of these steps are hidden
|
||||
by the "kpatch build" command.
|
||||
|
||||
|
||||
License
|
||||
-------
|
||||
|
||||
|
|
@ -65,72 +144,3 @@ GNU General Public License for more details.
|
|||
You should have received a copy of the GNU General Public License
|
||||
along with this program; if not, write to the Free Software
|
||||
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
||||
|
||||
|
||||
Status
|
||||
------
|
||||
|
||||
kpatch is currently is early development. For now, it should _not_ be used
|
||||
in production environments until significantly more testing on various
|
||||
patches and environments is conducted.
|
||||
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
|
||||
kpatch-build tools require libelf library and development headers to be installed.
|
||||
See Gotchas section below.
|
||||
|
||||
|
||||
Gotchas
|
||||
-------
|
||||
|
||||
The version of elfutils (namely libelf) that ship with most distros as of
|
||||
the time of this writing, have a bug in libelf that is exposed by kpatch.
|
||||
|
||||
elfutils-0.158 or higher contains the fix.
|
||||
|
||||
The specific commit is 88ad5ddb71bd1fa8ed043a840157ebf23c0057b3.
|
||||
|
||||
git://git.fedorahosted.org/git/elfutils.git
|
||||
|
||||
|
||||
Patch module generation algorithm
|
||||
---------------------------------
|
||||
|
||||
An example script for automating the patch module generation is
|
||||
kpatch-build/kpatch-build. The script is written for Fedora but should
|
||||
be adaptable to other distributions with limited changes.
|
||||
|
||||
The primary steps in the patch module generation process are:
|
||||
- Building the unstripped vmlinux for the kernel
|
||||
- Patching the source tree
|
||||
- Rebuilding vmlinux and monitoring which objects are building rebuilt.
|
||||
These are the "changed objects".
|
||||
- Recompile each changed object with -ffunction-sections -fdata-sections
|
||||
resulting in the changed patched objects
|
||||
- Unpatch the source tree
|
||||
- Recompile each changed object with -ffunction-sections -fdata-sections
|
||||
resulting in the changed original objects
|
||||
- Use create-diff-object to analyze each original/patched object pair
|
||||
for patchability and generate an output object containing modified
|
||||
sections
|
||||
- Link all the output objects in a into a cumulative object
|
||||
- Use add-patches-section to add the .patches section that the
|
||||
core kpatch module uses to determine the list of functions that need
|
||||
to be redirected using ftrace
|
||||
- Generate the patch kernel module
|
||||
- Use link-vmlinux-syms to hardcode non-exported kernel symbols
|
||||
into the symbol table of the patch kernel module
|
||||
|
||||
|
||||
Demonstration
|
||||
-------------
|
||||
|
||||
A low-level demonstration of kpatch is available on Youtube:
|
||||
|
||||
http://www.youtube.com/watch?v=WeSmG-XirC4
|
||||
|
||||
This demonstration completes each step in the previous section in a manual
|
||||
fashion. However, from a end-user perspective, most of these steps will
|
||||
be hidden away in scripts (eventually).
|
||||
|
|
|
|||
Loading…
Reference in New Issue