From 843a42298b8cd83f735bbe655988b6d14df4dd7a Mon Sep 17 00:00:00 2001 From: Josh Poimboeuf Date: Tue, 18 Feb 2014 10:15:13 -0600 Subject: [PATCH] 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 --- README.md | 152 +++++++++++++++++++++++++++++------------------------- 1 file changed, 81 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index f3d4b4f..038ef09 100644 --- a/README.md +++ b/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).