Overview

File README.demo of Package ulp-demo

Welcome to the Userspace Live Paching demo!
===========================================

Userspace Live Patching (ULP) is a low-level technology, and we will guide you
through the basic steps. This package (ulp-demo) contains a simple application
that uses OpenSSL libcrypto library and a live patch for libcrypto. The live
patch may alter the operation of a critical system component when misused.
You'd better try this demo on a test system or use a non-critical user account.
Let's get started!

The first step in live patching is to build system libraries with unique
options that enable live patching. In SLE 15 SP4, it was done for Glibc and
OpenSSL. Second, you got to start the user process with libpulp0 preloaded into
the address space. This is routinely done with LD_PRELOAD. Now start the
ulp-test app:

------------------------
$ LD_PRELOAD=/usr/lib64/libpulp.so.0 /opt/ulp-demo/bin/ulp-test
------------------------

This app merely reads lines from standard input and writes out the SHA1 crypto
hash value of the content. So you can try entering some content and see how is
the hash value changing.

------------------------
$  LD_PRELOAD=/usr/lib64/libpulp.so.0 /opt/ulp-demo/bin/ulp-test
Every entered line will be checksummed. Terminate with an interrupt (Ctrl-C) or
an end of transmission (Ctrl-D).
Hello world!
fd5108b213e2d666f0e9b14b64671f1b77e258ee
------------------------

Now, we are ready to apply the live patch. Next, start a new login session for
the same user in another terminal and check that we have live patchable
processes using the ulp tool.

------------------------
$  ulp patches
PID: 2995, name: ulp-test
  Livepatchable libraries:
    in /lib64/ld-linux-x86-64.so.2:
    in /lib64/libpthread.so.0:
    in /lib64/libdl.so.2:
    in /lib64/libc.so.6:
    in /usr/lib64/libcrypto.so.1.1:
    in /usr/lib64/libpulp.so.0:
------------------------

The `ulp patches` command shows running processes with live patchable libraries
and applied patches. We can see that Glibc and OpenSSL components are live
patchable, but there are no live patches in the listing. Let's use a live
patch, then!

------------------------
$ ulp trigger '/opt/ulp-demo/livepatches/libopenssl1_1/*.so'
ulp: pid = 2995, name = ulp-test: livepatch buildid mismatch for
    libcrypto.so.1.1 (3d992408a50b86b9fece9b8c4f628ea85047d371)
    expected buildid: 838b67cdc0af56c13675918c0e81ab8c34328b5c

ulp: live patching succeeded.
ulp: pid = 2995, name = ulp-test: livepatch buildid mismatch for
    libcrypto.so.1.1 (3d992408a50b86b9fece9b8c4f628ea85047d371)
    expected buildid: a32f7f483f48270507bce771870ab8761bc56902

ulp: pid = 2995, name = ulp-test: livepatch buildid mismatch for
    libcrypto.so.1.1 (3d992408a50b86b9fece9b8c4f628ea85047d371)
    expected buildid: 1c57fc36b3ba156f9f1504f235f8812557c6fc28

ulp: Succesfully applied 1 patches
------------------------

This command attempts to match the ready-made patches with the running library.
There are multiple versions of the patch for different builds of the library.
At most one patch succeeds here, or none if there is no corresponding live
patch for the running library. In our example, one patch fits the running
libcrypto and replaces the SHA1 routine. See how the behavior of ulp-test
changed.

------------------------
$  LD_PRELOAD=/usr/lib64/libpulp.so.0 /opt/ulp-demo/bin/ulp-test
...
Hello world!
SHA1 disabled by live patch.
deadbeefdeadbeefdeadbeefdeadbeefdeadbeef
------------------------

For the same input, ulp-test writes out a bogus hash value, and there is an
additional message in standard output. This is the effect of patching libcrypto
at run time. The ulp patches command will show us the live patch now.

------------------------
$ ulp patches
PID: 2995, name: ulp-test
  Livepatchable libraries:
    in /lib64/ld-linux-x86-64.so.2:
    in /lib64/libpthread.so.0:
    in /lib64/libdl.so.2:
    in /lib64/libc.so.6:
    in /usr/lib64/libcrypto.so.1.1:
      livepatch: libcrypto_livepatch1-1.1.1l-150400.3.11.so
    in /usr/lib64/libpulp.so.0:
------------------------

This is the core of the Userspace Live Patching operation. In production
deployments, the live patches are applied automatically upon the update of the
package with live patches. No manual intervention is required.

If you are interested in further study of the Userspace Live Patching
technology, please read the libpulp(7) and ulp(1) manual pages. The code is at
https://github.com/SUSE/libpulp, this demo source code is at
https://build.opensuse.org/package/show/home:ULP/ulp-demo. Apart from the usual
Github issues tracker, a developer mailing list at ulp-devel@lists.opensuse.org
if you want to enhance ULP.

Thanks for spending quality time with our demo!

P.S. If you want to undo the effects of the live patch and restore the original
SHA1 behavior, issue `ulp trigger --revert '/opt/ulp-demo/livepatches/libopenssl1_1/*.so'`.
openSUSE Build Service is sponsored by
Places