docs: add docs for CVE-aware reboot recommendations feature

CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Added a how-to guide for configuring the reboot notification policy of the Livepatch Client.
+- Added a reference page for the kernel upgrade recommendation, covering its results, messages, message of the day rules, and status output.
+- Added an explanation of how kernel upgrade recommendations work.
+- Added an explanation of how the Livepatch Client removes the pending reboot notice after a kernel update, and the effect on other tools.
+
+### Changed
+
+- Documented the `reboot-notification-policy` option in the Livepatch Client configuration options.
+- Added a "Livepatch reboot recommendation" section to the "When to reboot" explanation.
+- Noted in the CVE service deployment guide that both `lp.cve-lookup.enabled` and `lp.cve-sync.enabled` are required for clients to receive kernel upgrade information, and linked to the new explanation.
+
 ## [1.0.0] - 2026-06-18
 
 ### Added

docs/.custom_wordlist.txt

@@ -167,3 +167,5 @@ xml
 yaml
 YouTube
 yq
+Severities
+Livepatches

docs/client/explanation/architecture/how-kernel-upgrade-recommendations-work.md

@@ -0,0 +1,65 @@
+---
+myst:
+  html_meta:
+    description: "Understand how the Livepatch Client decides whether a reboot into a newer kernel is urgent, and why it sometimes makes no recommendation."
+---
+
+
+(client-explanation-how-kernel-upgrade-recommendations-work)=
+
+# How kernel upgrade recommendations work
+
+When a new kernel is installed, Ubuntu asks for a reboot. This page explains how Livepatch decides whether that reboot is urgent, and why it sometimes makes no recommendation.
+
+## Why the recommendation exists
+
+Live kernel patches cover high and critical kernel vulnerabilities. A newer kernel can include many fixes, but if Livepatch already covers those fixes, the machine isn't exposed while it waits for the next maintenance window. Lower-priority fixes are only available by rebooting into the new kernel.
+
+The kernel upgrade recommendation helps you tell these situations apart. It answers a single question: does the kernel that will boot next fix CVEs that this machine isn't already protected from?
+
+## Where the information comes from
+
+When the Livepatch Server is enabled with the CVE service, it knows which CVEs each Ubuntu kernel version fixes.
+
+On every check-in, the client tells the server:
+
+* The kernel that's running.
+* The kernel that will boot after a reboot.
+* The CVEs fixed by the live patches that are currently applied.
+
+The server replies with the CVEs that the next boot kernel fixes and that the running kernel doesn't.
+
+## How the client recommends reboots
+
+The client takes the CVEs that the next boot kernel adds and removes the ones that the applied live patches already cover. For example:
+
+* The next boot kernel fixes 5 CVEs that the running kernel doesn't.
+* The applied live patches already cover 3 of them.
+* The 2 that remain aren't covered, so the client recommends a reboot.
+
+If the applied Livepatch covers all the CVEs fixed by the next boot kernel, the Livepatch Client removes the pending reboot notice, and the reboot can wait for a maintenance window.
+
+## The newest kernel hint
+
+If Canonical has published an even newer kernel in the same series and flavour as the next boot kernel, the client mentions it, together with the CVEs it fixes. This is informational. It never changes the recommendation or whether a reboot notice is removed.
+
+## Why the client sometimes stays quiet
+
+The client only makes a recommendation when it has complete evidence. If anything is uncertain, it makes no recommendation rather than guessing, and it keeps any pending reboot notice. This happens in the following cases:
+
+* The Livepatch Server doesn't provide kernel upgrade information.
+* The kernel that will boot next can't be determined with confidence.
+* The kernel is a custom or unsigned kernel that doesn't match an installed Ubuntu kernel package.
+
+For the full list, see the [kernel upgrade recommendation reference](/client/reference/platform/kernel-upgrade-recommendation.md).
+
+## Requirements
+
+* Livepatch Client v11.1.0 or later.
+* For on-prem deployments, Livepatch Server v2.7.0 and CVE service v1.1.0 or later, with CVE lookup and CVE sync enabled. See [how to deploy the CVE service via snap](/server/how-to-guides/deployment/deploy-cve-service-via-snap.md).
+
+## See also
+
+* [How reboot notices are removed after a kernel update](/client/explanation/architecture/reboot-marker-suppression.md)
+* [Kernel upgrade recommendation reference](/client/reference/platform/kernel-upgrade-recommendation.md)
+* [Configure the reboot notification policy](/client/how-to-guides/configuration/configure-reboot-notification-policy.md)

docs/client/explanation/architecture/index.md

@@ -20,4 +20,6 @@ Updates not provided by Livepatch <what-kind-of-updates-are-not-provided-by-live
 Livepatch tiers <what-are-livepatch-tiers.md>
 When to expect new updates <when-should-i-expect-new-updates.md>
 Content caching <content-caching.md>
+Kernel upgrade recommendations <how-kernel-upgrade-recommendations-work.md>
+Reboot notice removal <reboot-marker-suppression.md>
 ```

docs/client/explanation/architecture/reboot-marker-suppression.md

@@ -0,0 +1,60 @@
+---
+myst:
+  html_meta:
+    description: "Understand when the Livepatch Client removes the pending reboot notice after a kernel update, and when it keeps it."
+---
+
+
+(client-explanation-how-reboot-notices-are-removed)=
+
+# How reboot notices are removed after a kernel update
+
+With the `livepatch-aware` reboot notification policy, the Livepatch Client can remove the system's pending reboot notice after a kernel install when Livepatch already covers the CVEs fixed by the next boot kernel. This page explains when that happens and when it doesn't.
+
+To configure the policy, see [how to configure the reboot notification policy](/client/how-to-guides/configuration/configure-reboot-notification-policy.md).
+
+## What Livepatch does
+
+After a kernel install, the system shows a pending reboot notice. With the `livepatch-aware` policy, the client checks whether that reboot is needed urgently. After `apt` finishes installing a kernel, a post-invoke hook created by the Livepatch Client refreshes client information and checks the [kernel upgrade recommendation](/client/explanation/architecture/how-kernel-upgrade-recommendations-work.md). It removes the pending reboot notice only when the result proves that Livepatch covers the CVEs fixed by the next boot kernel. The reboot can then wait for a maintenance window, and the Livepatch message shows that the system is protected.
+
+This only applies to the `livepatch-aware` policy.
+
+## When the notice stays
+
+The client keeps the reboot notice in the following cases:
+
+* Packages other than the kernel also need the restart.
+* The refresh or the coverage check fails or times out.
+* The evidence is incomplete. See [when there is no recommendation](/client/reference/platform/kernel-upgrade-recommendation.md) for the cases.
+* The policy is `livepatch-agnostic`.
+
+## Effects on other tools
+
+Removing the reboot notice, i.e. the `/var/run/reboot-required` file, also removes it for other tools that read it. For example:
+
+* `unattended-upgrades` with `Automatic-Reboot` enabled doesn't restart the machine, because it only reboots when a notice is pending.
+* `update-notifier` and the message of the day no longer show the system's "System restart required" message.
+* Monitoring and fleet management tools that check for the reboot notice no longer report the machine as needing a reboot.
+
+If you don't want Livepatch to change the system's reboot notice, set the policy to `livepatch-agnostic`. See [how to disable Livepatch-aware reboot notifications](/client/how-to-guides/configuration/configure-reboot-notification-policy.md#disable-livepatch-aware-reboot-notifications).
+
+## Limits
+
+* Only kernels installed or upgraded with `apt` are evaluated. A kernel installed with `dpkg -i` isn't evaluated until the next `apt` run.
+* If you change the GRUB default or the boot entry later, the notice isn't evaluated again until the next scheduled or manual refresh. The message of the day never shows a recommendation that's out of date.
+* On s390x, the client never removes the notice, because the architecture doesn't use GRUB.
+
+## Outcomes at a glance
+
+| Situation after a kernel install | Reboot notice | Livepatch message |
+| --- | --- | --- |
+| Livepatch covers the next boot kernel's CVEs | Removed | Protected |
+| Livepatch doesn't cover all of the next boot kernel's CVEs | Kept | Reboot required |
+| Other packages also need the restart | Kept | None, the system's own notice is shown |
+| The client can't prove coverage | Kept | None, the system's own notice is shown |
+
+## See also
+
+* [How kernel upgrade recommendations work](/client/explanation/architecture/how-kernel-upgrade-recommendations-work.md)
+* [Kernel upgrade recommendation reference](/client/reference/platform/kernel-upgrade-recommendation.md)
+* [Configure the reboot notification policy](/client/how-to-guides/configuration/configure-reboot-notification-policy.md)

docs/client/explanation/troubleshooting/do-i-need-to-reboot.md

@@ -22,4 +22,15 @@ Enabling the Livepatch service does not turn on automatic installation of securi
 - Subscribe to the [security announcement mailing list](https://lists.ubuntu.com/mailman/listinfo/ubuntu-security-announce)
 - Follow all advised security updates and reboot at your earliest convenience when any software component requires it
 
-Kernel SRU updates also include non-security bug fixes and lower-priority security fixes that may be important to your specific circumstances. These fixes are only available by rebooting into an updated kernel.
+Kernel SRU updates also include non-security bug fixes and lower-priority security fixes that may be important to your specific circumstances. These fixes are only available by rebooting into an updated kernel.
+
+## Livepatch reboot recommendation
+
+When Livepatch is running, the client also checks whether the kernel that will boot next fixes CVEs that your applied live patches don't cover. If it does, the message of the day recommends a reboot. If Livepatch already covers them, the message tells you that the reboot can wait for a maintenance window. With the default policy, the client can also remove the pending reboot notice after a kernel update.
+
+To learn more, see:
+
+- [How kernel upgrade recommendations work](/client/explanation/architecture/how-kernel-upgrade-recommendations-work.md)
+- [How reboot notices are removed after a kernel update](/client/explanation/architecture/reboot-marker-suppression.md)
+- [Kernel upgrade recommendation reference](/client/reference/platform/kernel-upgrade-recommendation.md)
+- [How to configure the reboot notification policy](/client/how-to-guides/configuration/configure-reboot-notification-policy.md)

docs/client/how-to-guides/configuration/configure-reboot-notification-policy.md

@@ -0,0 +1,66 @@
+---
+myst:
+  html_meta:
+    description: "How to configure the reboot notification policy of the Livepatch Client, so that reboot notices account for kernel CVEs already covered by Livepatch."
+---
+
+
+(client-how-to-guides-how-to-configure-the-reboot-notification-policy)=
+
+# How to configure the reboot notification policy
+
+By default, the Livepatch Client can remove a pending reboot notice after a kernel update when Livepatch already covers the CVEs that the next boot kernel fixes. This guide shows how to check, enable, and disable that behavior.
+
+## Requirements
+
+* Livepatch Client v11.1.0 or later.
+* For on-prem deployments, Livepatch Server v2.7.0 and CVE service v1.1.0 or later.
+
+## Check the reboot notification policy
+
+To check the reboot notification policy, run the following command:
+
+```bash
+sudo canonical-livepatch config reboot-notification-policy --format yaml
+reboot-notification-policy: livepatch-aware
+
+sudo canonical-livepatch config reboot-notification-policy --format json
+{"reboot-notification-policy":"livepatch-aware"}
+```
+
+## Enable Livepatch-aware reboot notifications
+
+To make reboot notifications aware of the Livepatch state, which is the default, run the following command:
+
+```bash
+sudo canonical-livepatch config reboot-notification-policy=livepatch-aware
+```
+
+With this policy, the client removes a pending reboot notice only after a refresh confirms that Livepatch covers the CVEs fixed by the next-boot kernel. If the refresh, the coverage check, or either command's timeout fails, the notice stays.
+
+The snap connects the interfaces that this feature needs (`etc-kernel-postinst-d`, `etc-apt-conf-d`, and `boot-grub`) automatically. If the client does not remove notices as expected, check that all three interfaces are connected:
+
+```bash
+snap connections canonical-livepatch
+```
+
+To connect a missing interface, run:
+
+```bash
+sudo snap connect canonical-livepatch:<interface>
+```
+
+## Disable Livepatch-aware reboot notifications
+
+When the client removes a reboot notice, tools that read it, such as `unattended-upgrades` and `update-notifier`, are affected. If you don't want the client to remove reboot notices, make reboot notifications independent of the Livepatch state by running the following command:
+
+```bash
+sudo canonical-livepatch config reboot-notification-policy=livepatch-agnostic
+```
+
+With this policy, the client never removes a pending reboot notice.
+
+## Next steps
+
+* To learn how the client decides to remove a reboot notice, see [how reboot notices are removed after a kernel update](/client/explanation/architecture/reboot-marker-suppression.md).
+* For all client settings, see the [configuration options](/client/reference/platform/configuration-options.md).

docs/client/how-to-guides/configuration/index.md

@@ -17,6 +17,7 @@ Configure the client, proxies, cloud-init, and patch cut-off behaviour.
 * [Configure a proxy](/client/how-to-guides/configuration/configure-proxy.md)
 * [Enable and configure the Livepatch Client with cloud-init](/client/how-to-guides/configuration/enable-and-configure-the-livepatch-client-with-cloud-init.md)
 * [Use a patch cut-off date](/client/how-to-guides/configuration/use-patch-cut-off-date.md)
+* [Configure the reboot notification policy](/client/how-to-guides/configuration/configure-reboot-notification-policy.md)
 
 ```{toctree}
 :titlesonly:
@@ -27,4 +28,5 @@ Configure Livepatch Client <configure-livepatch-client.md>
 Configure proxy <configure-proxy.md>
 Enable and configure the Livepatch Client with cloud init <enable-and-configure-the-livepatch-client-with-cloud-init.md>
 Use patch cut off date <use-patch-cut-off-date.md>
+Configure reboot notification policy <configure-reboot-notification-policy.md>
 ```

docs/client/how-to-guides/operations/check-client-status.md

@@ -129,7 +129,7 @@ The `canonical-livepatch status` command accepts flags that change the output fo
 
 * `--summary` shows a concise summary (similar to default output).
 
-* `--verbose` shows extended details such as client version, architecture, boot time, and applied CVEs.
+* `--verbose` shows extended details such as client version, architecture, boot time, applied CVEs, applied CVEs fixed in the kernels installed in the system, and CVEs fixed by the next boot kernel that are not yet fixed in the running kernel.
 
 * `--show-secrets` shows sensitive machine tokens (requires sudo).
 

docs/client/reference/platform/configuration-options.md

@@ -21,6 +21,7 @@ The following configuration options are available for the Livepatch Client. See
 | `check-interval` | integer | Interval in minutes between patch checks. Minimum `60`. Set to `0` to disable automatic checks. | `60` |
 | `log-level` | string | Log verbosity. One of `debug`, `info`, `notice`, `warning`, `error`. | `warning` |
 | `tls-patch-download` | boolean | Require TLS for all patch downloads. | `false` |
+| `reboot-notification-policy` | string | Controls whether the client removes a pending reboot notice after a kernel update. `livepatch-aware` removes it when Livepatch covers the next boot kernel's CVEs. `livepatch-agnostic` never removes it. See [how to configure the reboot notification policy](/client/how-to-guides/configuration/configure-reboot-notification-policy.md). | `livepatch-aware` |
 | `cutoff-date` <sup>1</sup> | string | RFC 3339 date in the past. Patches released after this date are not installed. | Empty |
 | `patch-delay` <sup>1</sup> | string | Duration to wait before a newly released patch is applied. Allowed units: `s`, `m`, `h`, `d`, `w`. | `0` |
 

docs/client/reference/platform/index.md

@@ -15,6 +15,7 @@ Supported kernels, architectures, and configuration options for the Livepatch Cl
 - [Supported kernels](/client/reference/platform/supported-kernels.md) — Kernel versions, flavours, and Ubuntu releases covered by the Livepatch Client.
 - [Supported architectures](/client/reference/platform/which-are-the-supported-architectures.md) — CPU architectures for which live kernel patches are available.
 - [Configuration options](/client/reference/platform/configuration-options.md) — All available configuration settings for the Livepatch Client.
+- [Kernel upgrade recommendation](/client/reference/platform/kernel-upgrade-recommendation.md) — Results, messages, and status output for the kernel upgrade recommendation.
 
 ```{toctree}
 :titlesonly:
@@ -24,4 +25,5 @@ Supported kernels, architectures, and configuration options for the Livepatch Cl
 Supported kernels <supported-kernels.md>
 Supported architectures <which-are-the-supported-architectures.md>
 Configuration options <configuration-options.md>
+Kernel upgrade recommendation <kernel-upgrade-recommendation.md>
 ```