ULP(1)

NAME
ulp - Userspace Livepatching Tool

SYNOPSIS
ulp command [SWITCHES]... [ARGUMENTS] file

INTRODUCTION
ulp consists of a set of tools used in the userspace livepatching process. Those include querying patch status, libpulp messages, applying and removing patches, and checking for livepatch capabilities within a process.

Commands currently supported by ulp are:

patches:
    list running programs that have livepatching capabilities loaded, as well the libraries that are livepatchable and the list of loaded patches.

check:
    check if a certain livepatch (.so) is applied to a running process.

dump:
    print the content of a livepatch (.so) in human-readable form.

packer:
    compile the livepatch descriptor (.dsc file) into a livepatch (.ulp file). The later can be used to apply a livepatch to a running process using trigger.

trigger:
    apply or remove a list of livepatches to a list of running processes.

post:
    apply any post-processing needed to livepatch containers (.so files).

messages:
    querry the libpulp internal message queue in a running process. This can be used to diagnose livepaching errors that occured internally in the target process.

Detailed descriptions about how these commands work are provided in the next
    sections.

PATCHES

NAME
ulp patches - Show active live patches and libraries

SYNOPSIS
ulp patches
    -pwildcard

DESCRIPTION
ulp patches show which libraries are livepatchable and which livepatches
    are loaded in process that matches either wildcard as name or with pid = wildcard.

OPTIONS

-p  wildcard Show processes which name matches the wildcard, or with pid = wildcard.

EXIT STATUS

ulp patches
    exits 0 on success, anything else on error.

CHECK

NAME
ulp check - Apply a live patch

SYNOPSIS
ulp check
    [OPTION]... -ppid file

DESCRIPTION
ulp check
    attaches to the target process specified by pid and checks whether the live patch described by the metadata file that it takes as argument has already been applied or not.

Only relevant processes can be inspected with ulpcheck. More specifically, the following conditions must be met:

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 check 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)).

FATAL ERRORS
If a problem happens during the execution of functions from libpulp.so, the
    target process might end up in an inconsistent state. When that happens ulp check exits with error code -1, and the user is advised to kill the process.

OPTIONS

-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.

BUGS

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.