Content refactor

README.md

@@ -1,23 +1,50 @@
 # Livepatch Documentation
 
-This repository contains the source documentation for Canonical Livepatch.
+Canonical Livepatch patches high and critical Linux kernel vulnerabilities without requiring a system reboot, shrinking the window between the publication of a security fix and its application on running machines. Livepatch is part of the [Ubuntu Pro](https://ubuntu.com/pro) offering.
 
-Livepatch shrinks the exploit window for critical and high severity Linux kernel vulnerabilities, by patching the Linux kernel between security maintenance windows, while the system runs.
+The Ubuntu Livepatch offering consists of the Livepatch Client, the Livepatch service hosted by Canonical, and an optional on-premises Livepatch Server. The client runs on each registered machine, periodically checks for available patches, and downloads, verifies, and installs them onto the running kernel.
 
-## What's in this repository
+Livepatch is built for critical infrastructure where unscheduled downtime is not acceptable. By applying live kernel patches for high and critical kernel vulnerabilities, upgrades can be scheduled at a convenient time without interrupting services.
 
-Documentation for:
+Livepatch is used by system administrators, security teams, and platform operators who manage Ubuntu systems at scale. The on-premises server is designed for customers operating machines in network-restricted environments where connecting client instances to external servers is not permitted. It supports staged rollout policies, centralised patch distribution, and integration with air-gapped environments.
 
-- Livepatch Client
-- Livepatch Server
+## Support
 
-## Useful links
+Support is available to customers with an [Ubuntu Pro](https://ubuntu.com/pro) subscription through the [Canonical support portal](https://portal.support.canonical.com/). See the {ref}`support <support>` page for more details.
 
-- Product page: [ubuntu.com/security/livepatch](https://ubuntu.com/security/livepatch)
-- Ubuntu Pro: [ubuntu.com/pro](https://ubuntu.com/pro)
-- Support: [portal.support.canonical.com](https://portal.support.canonical.com/)
+## In this documentation
 
-## Documentation contributions
+|                    |                                                                     |
+|--------------------|---------------------------------------------------------------------|
+| **Client** | {ref}`How-to guides <client-how-to-guides>` • {ref}`Reference <client-reference>` • {ref}`Explanation <client-explanation>` |
+| **Server** | {ref}`Tutorial <server-tutorial>` • {ref}`How-to guides <server-how-to-guides>` • {ref}`Reference <server-reference>` • {ref}`Explanation <server-explanation>` |
+| **Releases** | {ref}`Release notes for Livepatch Client and Server <release-notes>` |
+| **Resources** | {ref}`Contribute to the documentation <contribute-to-docs>` • {ref}`Get support and report bugs <support>` |
 
-Contributions to this documentation are welcome.
-For guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
+## How the documentation is organized
+
+This documentation uses the [Diátaxis documentation structure](https://diataxis.fr/).
+
+- The {ref}`server-tutorial` takes you step-by-step through deploying the Livepatch on-premises server for the first time, in environments such as LXD, MicroK8s, and air-gapped networks. <br>
+- {ref}`How-to guides <server-how-to-guides>` assume you have basic familiarity with Livepatch. They provide step-by-step instructions for achieving a practical goal, from enabling the client on a machine to deploying the on-premises server and managing patches. <br>
+- {ref}`Reference <server-reference>` contains technical specifications for the client and server — including supported platforms, networking requirements, authentication mechanisms, patch storage, and telemetry. <br>
+- {ref}`Explanation <server-explanation>` discusses background topics such as kernel live patching, the patch lifecycle, security models, and troubleshooting — helping you build a deeper understanding of how Livepatch works. <br>
+
+## Project and community
+
+Livepatch is a member of the Ubuntu family. It welcomes community contributions, suggestions, fixes, and constructive feedback.
+
+### Get involved
+
+* [Get support](https://ubuntu.com/support/community-support)
+* [Join the Discourse forum](https://discourse.ubuntu.com/c/project/livepatch/82)
+* {ref}`Contribute to the documentation <contribute-to-docs>`
+
+### Releases and policies
+
+* {ref}`Release notes <release-notes>`
+* [Our Code of Conduct](https://ubuntu.com/community/ethos/code-of-conduct)
+
+### Commercial support
+
+Thinking about using Livepatch for your next project? [Get in touch!](https://ubuntu.com/security/livepatch)

docs/.custom_wordlist.txt

@@ -1,160 +1,156 @@
 # Leave a blank line at the end of this file to support concatenation
+ABIs
+addons
+affordances
+airgapped
+Airgapped
+autoscaling
+Autoscaling
+aws
 backend
 backends
+backport
+bcrypt
+blocklisted
+blocklisting
+boolean
+bugfixes
 Canonical('s)?
 Charmcraft
+charmstore
 cjk
+crypto
 cryptographically
+CVEs
+Diátaxis
+docstrings?
+downloader
+Downloader
 dvipng
+enablement
+Enablement
+filepath
+firewalled
 fonts
 freefont
+Furo
+gcp
 github
+GitHub
+gkeop
+glibc
 GPG
 gyre
+hostnames
 hotfix(es)?
-https
 html
-io
+https
+ibm
 Intersphinx
+io
+ip
+journald
+jq
+jumpbox
 Kompare
+KPIs
+landscape
 lang
+lastmod
 LaTeX
 latexmk
+liveness
 LLMs?
+lockfile
+logrotate
+loopback
+lowlatency
+LSNs
+Makefiles?
+manpage
+minio
+mitigations
 Multipass
+MyST
 npm
+Numpy
+oem
+Open Graph
+openapi
 otf
+patchstore
+PDF
+plaintext
 plantuml
 PNG
+postgres
+PPAs
+PR
+preconfigured
+proxying
 Pygments
 pymarkdown
 pymarkdownlnt
 QEMU
-Rockcraft
+Read the Docs
 readthedocs
 redeclare
+rediraffe
+redownloading
+rerediraffe
+reStructuredText
+retrigger(ing)?
+Rockcraft
+rollout
+rollouts
 rst
+rtd
+SCons
+sequenceDiagram
 sitemapindex
+snapstore
+Sphinx
+Spread
+spread_test_example
+stdin
+subnets
 subproject
 subprojects
-SCons
+sudo
 SVG
+syscall
+tenancy
 tex
 texlive
 TOC
 toctree
+triages
 txt
 ulwazi
+unapplied
 uncomment(ing)?
+unmount(s)?
+unpatchable
+unpatched
+untrusted
+upstreams
+URIs
+URL
+USNs
 utils
 uv
+vCPUs
+venv
+VM
 VMs
+VNet
 WCAG
 whitespace
 whitespaces
 wordlist
 xetex
 xindy
 xml
-ip
-spread_test_example
-Furo
-PDF
-Open Graph
-MyST
-YouTube
-reStructuredText
-GitHub
-Sphinx
-URL
-PR
-Read the Docs
-Spread
-landscape
-lastmod
 yaml
-sequenceDiagram
-Numpy
-openapi
-docstrings?
-Makefiles?
-rediraffe
-rerediraffe
-retrigger(ing)?
-Diátaxis
-preconfigured
-venv
-rtd
-ABIs
-addons
-aws
-bcrypt
-boolean
-crypto
-CVEs
-gcp
-gkeop
-glibc
-ibm
-jq
-jumpbox
-KPIs
-LSNs
-manpage
-minio
-oem
-PPAs
-rollout
-stdin
-subnets
-sudo
-syscall
-tenancy
-triages
-unmount
-URIs
-USNs
-vCPUs
-VNet
+YouTube
 yq
-affordances
-airgapped
-Airgapped
-autoscaling
-Autoscaling
-backport
-blocklisted
-blocklisting
-bugfixes
-charmstore
-downloader
-Downloader
-enablement
-Enablement
-filepath
-firewalled
-hostnames
-journald
-livepatched
-livepatches
-Livepatches
-livepatching
-Livepatching
-lockfile
-logrotate
-loopback
-lowlatency
-mitigations
-patchstore
-plaintext
-postgres
-proxying
-redownloading
-rollouts
-snapstore
-unapplied
-unpatchable
-unpatched
-untrusted
-upstreams
-VM

docs/_static/css/custom.css

@@ -0,0 +1,3 @@
+.highlight pre span {
+  color: #111111 !important;
+}

docs/client/explanation/architecture/content-caching.md

@@ -1,24 +1,28 @@
 ---
 myst:
   html_meta:
-    description: "Content caching - technical reference for Livepatch client."
+    description: "Understand content caching in the Livepatch Client, including how SHA256 checksums and HTTP headers reduce network bandwidth when retrieving CVE data."
 ---
 
-
 (client-reference-content-caching)=
 
-# Content Caching
+# Content caching
+
+The Livepatch Client uses content caching to reduce network bandwidth when retrieving CVE data from the Livepatch Server. This document explains where and how content caching with hashes is applied.
 
-This document acts as a reference on how and where content caching with hashes is used in the livepatch server, to reduce the network bandwidth required while trying to obtain certain information.
+## Where content caching is used
 
-## Where is content caching used in the Livepatch Client?
+The Livepatch Client retrieves CVE data from the hosted Livepatch Server for the kernel packages present on the machine. If a newer version of the kernel fixes a patched CVE, the client can display information about the CVEs fixed in the new kernel version. Content caching is used when retrieving this information.
 
-The livepatch client gets the fixed CVE data from the hosted livepatch server, for the kernel packages currently present in the machine. If a newer version of the kernel fixes a patched CVE, the information of the CVEs fixed in the new kernel version can be viewed using the livepatch client. The Livepatch client uses content caching while retrieving this information from the server.
+## Why content caching is required
 
-## Why is content caching required?
+CVE data for a machine changes infrequently — only an update to the CVE data source or the installation of a new kernel package triggers a change. Sending this data to the client on every request is unnecessary.
 
-The CVE data for a machine changes infrequently, because only an update to the CVE data source or a new kernel package being installed on the machine can trigger a change. Therefore, it does not make sense for the server to send this information to the client on every request.
+## How content caching works
 
-## How is content caching achieved by the Livepatch client?
+The hosted Livepatch Server and the Livepatch Client rely on content hashes to send up-to-date CVE data efficiently:
 
-The hosted livepatch server and the livepatch client rely on caching using content hashes, to send up-to-date CVE data. An SHA256 checksum is used to track updates to the CVE data. The client sends the stored SHA256 checksum, for the current CVE data, to the server using the `If-None-Match` header. If there is a mismatch between the SHA256 checksums present in the client and the server, the updated CVE data is sent to the client along with the newly computed SHA256 checksum using the `ETag` header. The client stores this SHA256 checksum along with the content for use in future requests.
+- An SHA256 checksum tracks updates to the CVE data.
+- The client sends its stored SHA256 checksum to the server using the `If-None-Match` HTTP header.
+- If the checksums differ, the server sends the updated CVE data along with the new SHA256 checksum using the `ETag` header.
+- The client stores this checksum with the content for use in future requests.

docs/client/explanation/architecture/how-live-patching-works.md

@@ -0,0 +1,19 @@
+---
+myst:
+  html_meta:
+    description: "Understand how kernel live patching works in Livepatch, including the process from vulnerability detection to patch delivery and application."
+---
+
+(client-explanation-how-kernel-live-patching-works)=
+
+# How kernel live patching works
+
+When a high or critical vulnerability is detected in the Linux kernel, Canonical creates a live kernel patch to address it. After the patch is developed, it is tested in Canonical's internal server farm, then promoted gradually through a series of testing tiers to ensure it has been tested for a sufficient period on live systems. Once released, a [Livepatch Security Notice](https://ubuntu.com/security/notices) (LSN) is issued, and systems running the Livepatch Client receive and apply the patch over an authenticated channel.
+
+## The live patching process
+
+Kernel vulnerabilities can arise from many causes, such as logic errors or missing checks in small sections of code. At a high level, a live kernel patch provides new kernel code that replaces the vulnerable code and updates the rest of the kernel to use the new code.
+
+![Ubuntu Livepatch kernel patching diagram](/_static/images/at-a-glance-diagram.svg)
+
+The principle above also explains why some vulnerabilities that depend on complex code interactions cannot be fixed through live kernel patching. When a kernel vulnerability cannot be addressed with a live patch, a [Livepatch Security Notice](https://ubuntu.com/security/notices) is issued advising you to apply any pending kernel updates and reboot.