NAME¶
ksplice-create - Create a set of kernel modules for a rebootless kernel update
SYNOPSIS¶
ksplice-create [
OPTIONS]
--patch=PATCH_FILE
KERNEL_SOURCE
ksplice-create [
OPTIONS]
--diffext=EXTENSION
KERNEL_SOURCE
ksplice-create [
OPTIONS]
--git=COMMIT
KERNEL_SOURCE
ksplice-create [
OPTIONS]
--prebuild KERNEL_SOURCE
DESCRIPTION¶
ksplice-create creates a set of Ksplice kernel modules that, when loaded,
will apply a user-specified source code patch to the running binary kernel.
Before you use
ksplice-create on a patch, you should confirm that the
desired source code change does not make any semantic changes to kernel data
structures--that is, changes that would require existing instances of kernel
data structures to be transformed (e.g., a patch that adds a field to a global
data structure would require the existing data structures to change). If you
use Ksplice on a patch that changes data structure semantics, Ksplice will not
detect the problem and you could experience kernel problems as a result.
The to-be-applied source code patch can be specified by providing a
patch(1) file (
--patch=PATCH_FILE) or by providing a
file extension (
--diffext=EXTENSION).
If a file extension is specified, then the desired source code patch will be
determined by comparing all of the files in the
KERNEL_SOURCE directory
tree whose names end with the extra extension
EXTENSION against the
corresponding files without the extra extension. Only the new files containing
the extra extension in their filenames should be modified.
Here is an example of using a file extension to specify a patch:
$ cp KERNEL_SOURCE/kernel/sys.c KERNEL_SOURCE/kernel/sys.c.prctl_fixed
[edit sys.c.prctl_fixed to include the desired changes]
$ ksplice-create --diffext=.prctl_fixed KERNEL_SOURCE
KERNEL_SOURCE must be a directory containing the to-be-updated kernel's original
source code. If your Linux distribution applies patches to the Linux kernel
during the kernel build process, then those patches must be applied to the
KERNEL_SOURCE directory before invoking
ksplice-create on that
directory.
ksplice-create will not modify the source code in the
KERNEL_SOURCE directory tree, but it will perform a kernel build in
that directory tree.
ORIG_CONFIG can be used to specify the directory containing the
to-be-updated kernel's original
.config file and original
System.map file (the files should have exactly those names).
ORIG_CONFIG defaults to
KERNEL_SOURCE/ksplice.
The default
gcc(1) compiler and
as(1) assembler on the system
should be as close to the compiler and assembler originally used to build the
running kernel as possible. If the current compiler and linker are too
different from the original compiler and linker,
ksplice-apply will
abort when applying the update.
ksplice-create outputs a
tar(1) file, compressed with
gzip(1), containing the desired Ksplice update modules. This tarball
will be created in the current directory, and it can be manipulated using the
other Ksplice utilities, such as
ksplice-apply.
The first time that
ksplice-create is invoked on a
KERNEL_SOURCE
directory, it must build that kernel from scratch, which is much slower than
the rest of the update-creation process.
--prebuild can be used to
perform this initial kernel build without providing a source code patch.
In order to patch a function that has previously been patched by Ksplice, the
user needs to ensure that the
KERNEL_SOURCE directory provided to
Ksplice contains the source for the currently running kernel, including any
patches that have previously been applied by Ksplice.
OPTIONS¶
- --patch=PATCH_FILE
- Builds a Ksplice update out of the given patch(1) file
PATCH_FILE.
- --diffext=EXTENSION
- Builds a Ksplice update using the modified source files with names ending
in EXTENSION. The patch will be determined by comparing all of the
files in the KERNEL_SOURCE directory tree whose names end with the
extra extension EXTENSION against the corresponding files without
the extra extension.
- --git=COMMIT
- Builds a Ksplice update using the commit COMMIT in the Git working
tree KERNEL_SOURCE. The original state corresponding to the running
kernel is remembered in the Git ref refs/ksplice/pre, which will be
created from the current HEAD if it does not yet exist (and can be
changed using the --series option). Therefore, the source code
change to be applied corresponds to the output of git diff
ksplice/pre COMMIT.
- --prebuild
- Compiles the original source code that will be needed to build future
Ksplice updates. If any Ksplice updates have previously been built in the
KERNEL_SOURCE tree, the source files in the tree are reverted to
their original state.
- --series
- Specifies that the current state of the KERNEL_SOURCE tree should
be used as the original source that corresponds to the running kernel. If
a Ksplice update has recently been built in the KERNEL_SOURCE tree,
this option specifies that the Ksplice update being built should be
applied after the previous update in series. This option can be used with
--prebuild to forget the previous original state and perform no
other action.
- --build-modules
- For a patch that includes changes to kernel modules, in addition to
building a hot update that can be applied to the running kernel, this
option will cause ksplice-create to generate a set of new modules
based on the updated source code. These modules can be used to replace the
kernel modules stored on disk, where they can later be loaded normally
after part of the hot update has been applied using
ksplice-apply(1) --partial.
- -v, --verbose
- Causes ksplice-create to print debugging messages about its
progress. Using multiple -v options increases the verbosity. The maximum
is 2.
- -j JOBS, --jobs=JOBS
- Specifies the number of jobs to run simultaneously while performing kernel
builds. ksplice-create also honors the environment variable
CONCURRENCY_LEVEL.
- --patch-opt=OPTIONS
- Can be used to pass options to patch(1). If this option is NOT
specified, then -p1 is passed to patch. If this option is
specified, then only the specified options will be passed to patch.
This option can be repeated in order to pass multiple options to
patch. This option is ignored when the to-be-applied source code
patch is specified using --diffext.
- --id=ID
- Specifies the unique value that will be used as the identifier of the
Ksplice update. This identifier will, for example, appear in the name of
the update tarball. By default, a random 8-character ID will be
generated.
SEE ALSO¶
ksplice-apply(8),
ksplice-view(8),
ksplice-undo(8)
BUGS¶
Please report bugs to <devel@ksplice.com>.
AUTHORS¶
Jeff Arnold, Anders Kaseorg, and Tim Abbott
COPYRIGHT¶
Copyright (C) 2007-2009 Ksplice, Inc.
This is free software and documentation. You can redistribute and/or modify it
under the terms of the GNU General Public License, version 2.