|
ulp
check
also returns -1 on non-fatal
errors.
EXIT STATUS
ulp check
exits 0 on success, 1 on error,
and -1 on fatal errors. A fatal error is an indication that
the target process should be killed, because it was probably
left in an inconsistent state.
DUMP
|
|
NAME
|
|
ulp dump - Prints metadata
information in human-readable format
|
|
SYNOPSIS
ulp dump
file
DESCRIPTION
ulp dump
parses the metadata
file
that it takes as argument, which is in binary format, then
prints its content to the standard output in human-readable
format.
EXIT STATUS
ulp dump
exits 0 on success and 1 on
error.
PACKER
|
|
NAME
|
|
ulp packer - Create live patch
metadata
|
|
SYNOPSIS
ulp packer
[OPTION]...
file_wildcard
DESCRIPTION
ulp packer
creates a live patch metadata file based on the live patch
description
file
that it takes as argument. After
parsing the description file,
ulp packer
validates
that the target library and live patch objects referred to
exist, then produces the metadata file required by live
patching tools, such as
ulp trigger
(1) and
ulp
check
(1).
The syntax of
the description file is described in
libpulp
(7).
By default, the
output is written to stdout, but it can be optionally
redirected to a specified file. See OPTIONS below.
OPTIONS
-o, --output=FILENAME
Instead of printing the results
to the standard output, write them to FILENAME.
-p,
--process=WILDCARD
Patch any process which name
matches the WILDCARD. A single PID is also supported by
passing WILDCARD=PID of the target process.
-l,
--livepatch=FILENAME
Instead of getting the path to the
live patch object from the description file, use
FILENAME.
-t, --target=FILENAME
Instead of getting the path to
the target library from the description file, use
FILENAME.
-q, --quiet
Do not produce any output.
-v, --verbose
Produce verbose output.
-?, --help
Display a lengthy usage
message.
|
|
-usage
|
|
Display a brief usage message.
|
|
-V --version
Print program version and
exit.
-R --root=PREFIX
Append PREFIX to the path to
the livepatch .so file when it is send to the target
process. This is useful if ulp is running inside a
chroot.
EXIT STATUS
ulp packer
exits 0 on
success and 1 on error.
TRIGGER
|
|
NAME
|
|
ulp trigger - Apply a live
patch
|
|
SYNOPSIS
ulp trigger
[OPTION]...
-p
process_wildcard file_wildcard
DESCRIPTION
ulp trigger
attaches to the target process specified by a set of process
in
process_wildcard
or a single process with pid
equals to
process_wildcard
and applies a set of
livepatches described by the metadata
file_wildcard
that it takes as argument. After parsing the metadata file,
several checks are performed to verify that the target
process can receive the specified live patch:
Target Library
A live patch replaces functions
belonging to a shared library, thus,
ulp trigger
searches the memory space of the target process for its
presence. When the library is not present,
ulp
trigger
exits in error.
Replacement functions
The metadata file contains a
list of replacement functions, which must be present in the
live patch object (DSO). If all functions are present, the
live patching operation can proceed, otherwise
ulp
trigger
exits in error.
Attaching to the Target
Process
Libpulp uses ptrace to attach
to target processes, thus only the owner of a process (or
root) can apply a live patch to it. Moreover, on systems
that have Linux Security Modules (LSM) enabled, some extra
convincing might be required (see Ptrace access mode
checking in
ptrace
(2)). When
ulp trigger
is
unable to attach to the target process, it exits in
error.
Runtime support
Applying a live patch requires
functions from libpulp.so, which must have been loaded into
the address space of the target process. Typically, this is
accomplished with LD_PRELOAD (see
libpulp
(7)).
Forward progress
After attaching to the target
process with ptrace, Libpulp calls functions from
libpulp.so. The execution of these functions happens from
the context of a signal handler, thus
AS-Unsafe
functions are not allowed (see
attributes
(7)).
However, Libpulp requires the use of
malloc
(3),
dlopen
(3) and
dlsym
(3), which are all
AS-Unsafe
. In order to avoid deadlocks, libpulp.so
checks that these functions are not in execution anywhere in
the target process, before starting the live patching
operation.
FATAL ERRORS
If a problem happens after
Libpulp started replacing functions from the target process,
the process might end up in an inconsistent state. When that
happens
ulp trigger
exits with error code
-1
,
and the user is advised to kill the process.
OPTIONS
-r, --retries=N
To guarantee
Forward
Progress
, Libpulp first checks whether trying to apply a
live patch would cause a deadlock in the target process, or
if it would be safe to do so. By default,
ulp trigger
performs this check a single time and exits in error if the
check fails. However, the state of the relevant locks
usually changes very quickly, thus, there is a high chance
that trying again after a brief moment would allow the live
patching operation to succeed without risk of deadlock. This
option tells
ulp trigger
to try again
N
times.
-c, --check-stack
Before applying the live patch
to the target process, unwind the stacks of all threads and
make sure that none of them have library calls in execution.
If any thread is within the target library,
ulp
trigger
aborts the live patching operation; on the other
hand, if no threads are within the target library, the live
patch can be applied with additional consistency
guarantees.
--revert-all=LIB
Before applying the live patch
to the target process, revert all livepatches applied to the
library LIB. If LIB=target, then all patches to the target
library of the livepatch will be removed.
--disable-summarization
Disable output summarization.
This avoids suppression of output ’irrelevant
output’ with regard to skipped livepatches.
--timeout N
Wait N seconds for a reply from
libpulp. Default is 100s. In cases where the system is busy
running multiple tasks it may be worth increasing this
number, once ulp will bail out to not hang a system
update.
--recursive
Look for livepatches
recursively when a wildcard is passed.
-q, --quiet
Do not produce any output.
-v, --verbose
Produce verbose output.
-?, --help
Display a lengthy usage
message.
|
|
-usage
|
|
Display a brief usage message.
|
|
-V --version
Print program version and
exit.
EXIT STATUS
ulp trigger
exits 0 on
success, 1 on error, and -1 on fatal errors. A fatal error
is an indication that the target process should be killed,
because it was probably left in an inconsistent state.
POST
|
|
NAME
|
|
ulp post - Post-process live
patchable libraries
|
|
SYNOPSIS
ulp post
file
DESCRIPTION
ulp post
opens
the library
file
passed as argument and replaces
one-byte nops with multi-byte nop instructions at patchable
function entries (see
gcc
(1)).
EXIT STATUS
ulp post
exits 0 on
success, and 1 on error.
REVERSE
|
|
NAME
|
|
ulp reverse - Create live patch
metadata
|
|
SYNOPSIS
ulp reverse
file
DESCRIPTION
ulp reverse
creates a live patch metadata
used to revert the effects of the metadata
file
that
it takes as argument. Live patch reversal does not require a
live patch object file, because it does not add new
replacement functions; rather, it causes the reverse-patched
process to fallback to the functions that had been
previously replaced. These functions are already present in
the memory space of the target process.
EXIT STATUS
ulp reverse
exits 0 on success and a
positive integer on error.
MESSAGES
|
|
NAME
|
|
ulp messages - Querry internal
messages from libpulp
|
|
SYNOPSIS
ulp messages
-p
pid
DESCRIPTION
ulp messages
print all internal messages
from libpulp message queue in process running with pid =
pid
Those messages are useful to debug any problem
that may happens when a livepatch is applied.
Messages are output to
stdout.
EXIT STATUS
ulp messages
exits 0 on success, anything
else on error.
EXTRACT
|
|
NAME
|
|
ulp extract - Extract the
relevant content from a livepatchable library
|
SYNOPSIS
ulp extract
livepatchable_library
-o
output_file
DESCRIPTION
Extract the relevant content
from
livepatchable_library
such as the library name, buildid, and symbols in the
library; and write those informations into a JSON file
specified by
output_file.
EXIT STATUS
exits 0 on success, anything
else on error.
SET_PATCHABLE
|
|
NAME
|
|
ulp set_patchable -
Enable/disable livepatching on target process
|
SYNOPSIS
ulp set_livepatchable -p
process
enable/disable
DESCRIPTION
Enable or disable the
livepatching capability of process specified by
-p
WILDCARD.
If WILDCARD
is a number, then it is assumed to be the PID of the
process. The program will output which processes were
modified.
EXIT STATUS
Always returns 0.
|