ULP(1)

📦 version 0.3.17, in debian trixie, opensuse-leap 16.0

💖 ULP — the Userspace Livepatching Tool, bestie edition 💖

okay so. you know ulp? no? then sit down, grab a strawberry 🍓, because this is the tool for userspace livepatching and honestly it's giving main character energy. this is the ULP(1) manual page, from the Libpulp Tools collection, and by the end of it you're gonna be obsessed. periodt. 👑

✨ NAME ✨

ulp — the Userspace Livepatching Tool. that's it, that's the name, no notes. 💅

🌸 SYNOPSIS 🌸

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

like, you pick a command, you sprinkle on some [SWITCHES]..., you toss in your [ARGUMENTS], and there's a file at the end. slay. 🦋

🎀 INTRODUCTION 🎀

so ulp isn't just one thing, bestie — it's a whole set of tools used in the userspace livepatching process. the squad handles:

  • querying patch status
  • libpulp messages
  • applying and removing patches
  • checking for livepatch capabilities within a process

so basically it does everything. no cap. 💜

the commands ulp currently supports 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. 👀

yes, the manpage really does spell it "querry" and "livepaching" and "The later". we keep the lore intact. it's part of the charm. 🙈

🦋 PATCHES 🦋

NAME

ulp patches — Show active live patches and libraries. 👑

SYNOPSIS

ulp patches -pwildcard

DESCRIPTION

ulp patches shows which libraries are livepatchable and which livepatches are loaded in process that matches either wildcard as name or with pid = wildcard. it's the vibe check for your running processes. 💖

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. simple as that. ✨

🌈 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. like a detective but for patches. 🔍

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.

💀 no fr, kill the process. it's not okay in there. this is the "do not perceive me" moment of processes.

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. 🙃 iconic of it, honestly.

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. binary in, human out. it's giving translator. 🌸

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). it's the glow-up station for your patches. ✨

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

🌟 and that's part 1, bestie — there's more coming, don't go anywhere, the group chat isn't done yet 🌟

🧐 DESCRIPTION

ulp trigger attaches to the target process — either a whole set of processes matched by process_wildcard, or a single process whose pid equals process_wildcard — and applies the set of livepatches described by the metadata file file_wildcard that you hand it as an argument. 🫶

Once it's done parsing that metadata file, it runs a bunch of checks to make sure your target process can actually receive the live patch you're asking for:

📚 Target Library

A live patch replaces functions that belong to a shared library, so ulp trigger goes hunting through the memory space of the target process to see if that library is even there. If the library isn't present, ulp trigger exits in error. Bye. 💀

🔁 Replacement functions

The metadata file holds a list of replacement functions, and those functions must be present in the live patch object (DSO). If every single one is there, the live patching operation can proceed. If not? ulp trigger exits in error. No exceptions, bestie.

🔗 Attaching to the Target Process

Libpulp uses ptrace to attach to target processes, which means only the owner of a process (or root) can apply a live patch to it. And 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 can't attach to the target process, it exits in error.

🧩 Runtime support

Applying a live patch needs functions from libpulp.so, and those must already 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, so AS-Unsafe functions are not allowed (see attributes(7)). However, Libpulp requires the use of malloc(3), dlopen(3) and dlsym(3) — and all three of those are AS-Unsafe. 😭 So, to avoid deadlocks, libpulp.so checks that these functions are not in execution anywhere in the target process before it starts the live patching operation. Iconic safety-first behavior fr fr.

💀 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. Not a drill, bestie — go get the kill. 🔥

⚙️ 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. But the state of the relevant locks usually changes very quickly, so there's a high chance that trying again after a brief moment would let the live patching operation 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. And a fatal error is basically a giant flashing sign saying the target process should be killed, because it was probably left in an inconsistent state. 💅

📮 POST

NAME — ulp post

ulp post — Post-process live patchable libraries. ✨

SYNOPSIS

ulp post file

DESCRIPTION

ulp post opens the library file you passed as an argument and replaces one-byte nops with multi-byte nop instructions at patchable function entries (see gcc(1)). Little glow-up, huge payoff. 🎀

EXIT STATUS

ulp post exits 0 on success, and 1 on error.

🔙 REVERSE

NAME — ulp reverse

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. Those functions are already present in the memory space of the target process, so no new friends needed. 🌸

EXIT STATUS

ulp reverse exits 0 on success and a positive integer on error.

💌 MESSAGES

NAME — ulp messages

ulp messages — Querry internal messages from libpulp.

SYNOPSIS

ulp messages
       -p pid

DESCRIPTION

ulp messages prints all internal messages from the libpulp message queue in the 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

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

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

🎛️ SET_PATCHABLE

NAME — ulp set_patchable

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 the 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. Always. Immovable. Unbothered. Moisturized. In her lane. 💅

and that's a wrap on this whole thing, bestie!! this was the ULP(1) manual page, top to bottom, and yes the footer really is just that — ULP(1), the classic, the moment, the whole vibe. go forth and livepatch responsibly 🦋💖

📦 where this page comes from