Kernel Live Patching

DC-klp

@@ -0,0 +1,15 @@
+# This file originates from the project https://github.com/openSUSE/doc-kit
+# This file can be edited downstream.
+
+MAIN="klp.asm.xml"
+SRC_DIR="articles"
+IMG_SRC_DIR="images"
+
+PROFOS="sles"
+#PROFCONDITION="suse-product"
+#PROFCONDITION="suse-product;beta"
+#PROFCONDITION="community-project"
+
+STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns"
+FALLBACK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns"
+DOCBOOK5_RNG_URI="urn:x-suse:rng:v2:geekodoc-flat"

articles/klp.asm.xml

@@ -0,0 +1,214 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- This file originates from the project https://github.com/openSUSE/doc-kit -->
+<!-- This file can be edited downstream. -->
+<!DOCTYPE assembly
+[
+    <!ENTITY % entities SYSTEM "../common/generic-entities.ent">
+    %entities;
+]>
+<!-- refers to legacy doc: <add github link to legacy doc piece, if applicable> -->
+<!-- point back to this document with a similar comment added to your legacy doc piece -->
+<!-- refer to README.md for file and id naming conventions -->
+<assembly version="5.2" xml:lang="en"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:trans="http://docbook.org/ns/transclusion"
+          xmlns:its="http://www.w3.org/2005/11/its"
+          xmlns="http://docbook.org/ns/docbook">
+  <!-- resources section references all topic chunks used in the final article
+    -->
+  <!-- R E S O U R C E S -->
+  <!-- Concept files -->
+  <resources>
+    <resource xml:id="_klp-intro" href="../concepts/klp-intro.xml"></resource>
+    <resource xml:id="_klp-patches" href="../concepts/klp-patches.xml"></resource>
+    <resource xml:id="_klp-activate-yast" href="../tasks/klp-activate-yast.xml"></resource>
+    <resource xml:id="_klp-activate-cli" href="../tasks/klp-activate-cli.xml"></resource>
+    <resource xml:id="_klp-perform" href="../tasks/klp-perform.xml"></resource>
+  <resource xml:id="_klp-troubleshoot" href="../tasks/klp-troubleshoot.xml"></resource>
+  </resources>
+  <!-- Legal -->
+  <resources>
+    <resource href="../common/legal.xml" xml:id="_legal">
+      <description>Legal Notice</description>
+    </resource>
+    <resource href="../common/license_gfdl1.2.xml" xml:id="_gfdl">
+      <description>GNU Free Documentation License</description>
+    </resource>
+  </resources>
+  <!-- S T R U C T U R E -->
+  <structure renderas="article" xml:id="klp" xml:lang="en">
+    <merge>
+      <title>&klp; on &sles;</title>
+      <!-- Create revision history to enable versioning; add most recent entries at the top. -->
+      <!-- Check https://documentation.suse.com/style/current/single-html/docu_styleguide/#sec-revhistory for detailed instructions-->
+      <revhistory xml:id="rh-klp">
+        <revision><date>2024-02-21</date>
+          <revdescription>
+            <itemizedlist>
+              <!-- Group by type of change (added/removed/changed)-->
+              <listitem>
+                <para>
+                  Added sections:
+                </para>
+                <itemizedlist>
+                  <!-- Reference, but don't link to tracker items-->
+                  <!-- Follow https://en.opensuse.org/openSUSE:Packaging_Patches_guidelines#Current_set_of_abbreviations for tracker item references-->
+                  <listitem>
+                    <para>
+                      New section on <quote>foo</quote> to resolve issue
+                      <uri>bsc#12345</uri>
+                    </para>
+                  </listitem>
+                  <!-- Name sections, but don't insert links -->
+                  <listitem>
+                    <para>
+                      New section on <quote>foo bar</quote>
+                    </para>
+                  </listitem>
+                </itemizedlist>
+              </listitem>
+              <listitem>
+                <para>
+                  Removed sections:
+                </para>
+                <itemizedlist>
+                  <listitem>
+                    <para>
+                      Removed section on <quote>foo1</quote> to resolve issue
+                      <uri>bsc#12346</uri>
+                    </para>
+                  </listitem>
+                  <listitem>
+                    <para>
+                      Removed section on <quote>foo1 bar</quote>
+                    </para>
+                  </listitem>
+                </itemizedlist>
+              </listitem>
+              <listitem>
+                <para>
+                  Changed sections:
+                </para>
+                <itemizedlist>
+                  <listitem>
+                    <para>
+                      Changed section on <quote>foo2</quote> to resolve issue
+                      <uri>bsc#12347</uri>
+                    </para>
+                  </listitem>
+                  <listitem>
+                    <para>
+                      Changed section on <quote>foo2 bar</quote>
+                    </para>
+                  </listitem>
+                </itemizedlist>
+              </listitem>
+            </itemizedlist>
+          </revdescription>
+        </revision>
+      </revhistory>
+      <!-- TODO: provide a listing of possible and validatable meta entry values. Maybe in our geekodoc repo? -->
+      <!-- add author's e-mail -->
+      <meta name="maintainer" content="" its:translate="no"/>
+      <!-- ISO date of last update as YYYY-MM-DD -->
+      <meta name="updated" content="2037-11-16" its:translate="no"/>
+      <!-- this does not work yet. Use the dm tags listed below for now
+        <meta name="bugtracker" its:translate="no">
+        <phrase role="url">https://bugzilla.suse.com/enter_bug.cgi</phrase>
+        <phrase role="component">Non-product-specific documentation</phrase>
+        <phrase role="product">Smart Docs</phrase>
+        <phrase role="assignee">[email protected]</phrase>
+        </meta>
+        -->
+      <!-- not supported, yet. Use dm: tag for now
+        <meta name="translation" its:translate="no">
+        <phrase role="trans">yes</phrase>
+        <phrase role="language">de-de,cs-cz</phrase>
+        </meta>
+        -->
+      <!-- enter the platform identifier or a list of
+        identifiers, separated by ; -->
+      <!-- For a full list of meta tags and their values,
+        see https://confluence.suse.com/x/aQDWNg
+        -->
+      <meta name="architecture" content="x86;power;zseries" its:translate="no"/>
+      <meta name="productname" its:translate="no">
+        <!-- enter product name and version --><productname version="X.Y">&productname;</productname>
+      </meta>
+      <meta name="title" its:translate="yes">&klp; on &slsa;</meta>
+      <meta name="description" its:translate="yes">&klp; on &slsa;</meta>
+      <meta name="social-descr" its:translate="yes">&klp; on &slsa;</meta>
+      <!-- suitable category, comma-separated list of categories -->
+      <meta name="category" content="Systems Management" its:translate="no"/>
+      <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
+        <dm:bugtracker>
+          <dm:url>https://bugzilla.suse.com/enter_bug.cgi</dm:url>
+          <dm:component>Smart Docs</dm:component>
+          <dm:product>Documentation</dm:product>
+          <!-- provide your BUGZILLA e-mail address, otherwise this does not work correctly-->
+          <dm:assignee>[email protected]</dm:assignee>
+        </dm:bugtracker>
+        <dm:translation>yes</dm:translation>
+      </dm:docmanager>
+      <abstract>
+        <variablelist>
+          <varlistentry>
+            <term>WHAT?</term>
+            <listitem>
+              <para>
+                Understanding and using &klp; on &sles;.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>WHY?</term>
+            <listitem>
+              <para>
+                Because you want to keep mission-critical systems secure,
+                without downtime.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>EFFORT</term>
+            <listitem>
+              <para>
+                20 minutes reading time.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>GOAL</term>
+            <listitem>
+              <para>
+                Understand how Kernel Live Patching works.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>REQUIREMENTS</term>
+            <listitem>
+              <itemizedlist>
+                <listitem>
+                  <para>
+                    Working knowledge of Linux.
+                  </para>
+                </listitem>
+              </itemizedlist>
+            </listitem>
+          </varlistentry>
+        </variablelist>
+      </abstract>
+    </merge>
+    <module resourceref="_klp-intro" renderas="section"/>
+    <module resourceref="_klp-patches" renderas="section"/>
+    <module resourceref="_klp-activate-yast" renderas="section"/>
+    <module resourceref="_klp-activate-cli" renderas="section"/>
+    <module resourceref="_klp-perform" renderas="section"/>
+    <module resourceref="_klp-troubleshoot" renderas="section"/>
+    <module resourceref="_legal"/>
+    <module resourceref="_gfdl">
+      <output renderas="appendix"/>
+    </module>
+  </structure>
+</assembly>

concepts/klp-intro.xml

@@ -0,0 +1,81 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+[
+  <!ENTITY % entities SYSTEM "../common/generic-entities.ent">
+    %entities;
+]>
+<topic xml:id="klp-intro"
+ role="concept" xml:lang="en"
+ xmlns="http://docbook.org/ns/docbook" version="5.2"
+ xmlns:its="http://www.w3.org/2005/11/its"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:trans="http://docbook.org/ns/transclusion">
+  <info>
+    <title>Introduction to &klp;</title>
+    <meta name="maintainer" content="[email protected]" its:translate="yes"/>
+  </info>
+  <para>
+    &klp; (&klpa;) makes it possible to apply the latest security updates to
+    Linux kernels without rebooting. This maximizes system uptime and
+    availability, which is particularly important for mission-critical systems.
+    As such, &klpa; offers several benefits.
+  </para>
+  <itemizedlist>
+    <listitem>
+      <para>
+        Keeping a large number of servers automatically up-to-date is essential
+        for organizations obtaining or maintaining certain compliance
+        certifications. &klpa; can help achieve compliance, while reducing the
+        need for maintenance windows.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Companies that work with service-level agreement contracts must
+        guarantee a certain level of the system accessibility and uptime.
+        Live patching makes it possible to patch systems without incurring
+        downtime.
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        Since &klpa; is part of the standard system update mechanism, there is
+        no need for specialized training or introduction of additional
+        maintenance routines.
+      </para>
+    </listitem>
+  </itemizedlist>
+
+  <section xml:id="sec-klp-scope">
+    <title>&klp; scope</title>
+
+    <para>
+      The scope of &slea; Live Patching includes fixes for SUSE Common
+      Vulnerability Scoring System (CVSS; SUSE CVSS is based on the CVSS v3.0
+      system) level 7+ vulnerabilities and bug fixes related to system
+      stability or data corruption. However, it may not be technically feasible
+      to create live patches for all fixes that fall under the specified
+      categories. &suse; therefore reserves the right to skip fixes in
+      situations where creating a kernel live patch is not possible for
+      technical reasons. Currently, over 95% of qualifying fixes are released
+      as live patches. For more information on CVSS (the base for the SUSE CVSS
+      rating), see <link xlink:href="https://www.first.org/cvss/">Common
+      Vulnerability Scoring System SIG</link>.
+    </para>
+  </section>
+  <section xml:id="sec-klp-limitations">
+    <title>&klp; limitations</title>
+
+    <para>
+      &klpa; involves replacing functions and gracefully handling replacement
+      of interdependent function sets. This is done by redirecting calls to old
+      code to updated code in a different memory location. Changes in data
+      structures make the situation more complicated, as the data remain in
+      place and cannot be extended or reinterpreted. While there are techniques
+      that allow indirect alteration of data structures, certain fixes cannot
+      be converted to live patches. In this situation, a system restart is the
+      only way to apply the fixes.
+    </para>
+  </section>
+</topic>

concepts/klp-patches.xml

@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+[
+  <!ENTITY % entities SYSTEM "../common/generic-entities.ent">
+    %entities;
+]>
+<topic xml:id="klp-patches"
+ role="concept" xml:lang="en"
+ xmlns="http://docbook.org/ns/docbook" version="5.2"
+ xmlns:its="http://www.w3.org/2005/11/its"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:trans="http://docbook.org/ns/transclusion">
+  <info>
+    <title>Understanding kernel live patches</title>
+    <meta name="maintainer" content="[email protected]" its:translate="yes"/>
+  </info>
+  <para>
+    Kernel live patches are delivered as packages with modified code that are
+    separate from the main kernel package. The live patches are cumulative, so
+    the latest patch contains all fixes from the previous ones for the kernel
+    package. Each kernel live package is tied to the exact kernel revision for
+    which it is issued. The live patch package version number increases with
+    every addition of fixes. To determine the kernel patching status, use the
+    <command>klp -v patches</command> command.
+  </para>
+  <section xml:id="sec-kernel-patches-vs-updates">
+    <title>Live patches versus kernel updates</title>
+    <para>
+      Live patches contain only critical fixes, and they do not replace regular
+      kernel updates that require a reboot. Consider live patches as temporary
+      measures that protect the kernel until a proper kernel update and a
+      reboot are performed.
+    </para>
+    <para>
+      The diagram below illustrates the overall relationship between live
+      patches and kernel updates. The list of CVEs and defect reports addressed
+      by the currently active live patch can be viewed using the <command>klp
+      -v patches</command> command.
+    </para>
+    <informalfigure>
+      <mediaobject>
+        <imageobject role="fo">
+          <imagedata fileref="klp.png" width="100%"/>
+        </imageobject>
+        <imageobject role="html">
+          <imagedata fileref="klp.png" width="100%"/>
+        </imageobject>
+      </mediaobject>
+    </informalfigure>
+    <para>
+      It is possible to have multiple versions of the kernel package installed
+      along with their live patches. These packages do not conflict. You can
+      install updated kernel packages along with live patches for the running
+      kernel. In this case, you may be prompted to reboot the system. Users
+      with &slea; Live Patching subscriptions are eligible for technical
+      support as long as there are live patch updates for the running kernel.
+    </para>
+    <para>
+      With &klpa; activated, every kernel update comes with a live patch
+      package. This live patch does not contain any fixes and serves as a seed
+      for future live patches for the corresponding kernel. These empty seed
+      patches are called <literal>initial patches</literal>.
+    </para>
+  </section>
+</topic>