diff --git a/README.md b/README.md index b8cb991..3b24d7f 100644 --- a/README.md +++ b/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 ` 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 ` • {ref}`Reference ` • {ref}`Explanation ` | +| **Server** | {ref}`Tutorial ` • {ref}`How-to guides ` • {ref}`Reference ` • {ref}`Explanation ` | +| **Releases** | {ref}`Release notes for Livepatch Client and Server ` | +| **Resources** | {ref}`Contribute to the documentation ` • {ref}`Get support and report bugs ` | -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.
+- {ref}`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.
+- {ref}`Reference ` contains technical specifications for the client and server — including supported platforms, networking requirements, authentication mechanisms, patch storage, and telemetry.
+- {ref}`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.
+ +## 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 ` + +### Releases and policies + +* {ref}`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) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 2d67436..0598f2e 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -1,54 +1,149 @@ # 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 @@ -56,105 +151,6 @@ 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 diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 0000000..45476b5 --- /dev/null +++ b/docs/_static/css/custom.css @@ -0,0 +1,3 @@ +.highlight pre span { + color: #111111 !important; +} diff --git a/docs/client/explanation/architecture/content-caching.md b/docs/client/explanation/architecture/content-caching.md index 76b9d62..4b1318c 100644 --- a/docs/client/explanation/architecture/content-caching.md +++ b/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. diff --git a/docs/client/explanation/architecture/how-live-patching-works.md b/docs/client/explanation/architecture/how-live-patching-works.md new file mode 100644 index 0000000..699f5d8 --- /dev/null +++ b/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. diff --git a/docs/client/explanation/architecture/how-livepatching-works.md b/docs/client/explanation/architecture/how-livepatching-works.md deleted file mode 100644 index cceb76d..0000000 --- a/docs/client/explanation/architecture/how-livepatching-works.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -myst: - html_meta: - description: "How Livepatching works? - learn about this topic in Livepatch client." ---- - - -(client-explanation-how-kernel-livepatching-works)= - -# How kernel Livepatching works? - -## The livepatching process - -When a high or critical vulnerability is detected on the Linux kernel Canonical creates a livepatch addressing the vulnerability. After the livepatch is made available, it is tested in Canonical’s internal server farm, and then promoted gradually to a series of testing tiers ensuring that any released livepatch has been tested sufficient time on live systems. Once the patch is released a [Livepatch Security Notice](https://ubuntu.com/security/notices) is issued and systems that enable the Livepatch client will receive the patch over an authenticated channel and apply it. - -## How does kernel livepatching work? - -There are many types of vulnerabilities and many reasons behind them, such as a logic error or a missing check in a small piece of code, and others. On the high level the livepatch will provide new kernel code replacing the vulnerable one, and will update the rest of the kernel to use the new code. The diagram below shows how a kernel vulnerability is being patched using Ubuntu Livepatch. - -![Ubuntu Livepatch kernel patching diagram](/_static/images/at-a-glance-diagram.svg) - -The simplistic description above shows the principle, but also hints on why some vulnerabilities that depend on very complex code interactions cannot be livepatched. When a kernel vulnerability cannot be livepatched, a [Livepatch Security Notice](https://ubuntu.com/security/notices) is issued that advises to apply any pending kernel updates and reboot. diff --git a/docs/client/explanation/architecture/index.md b/docs/client/explanation/architecture/index.md index e25586a..460d4b4 100644 --- a/docs/client/explanation/architecture/index.md +++ b/docs/client/explanation/architecture/index.md @@ -1,34 +1,23 @@ --- myst: html_meta: - description: "How Livepatching works and what kind of updates it provides." + description: "Explore Livepatch architecture concepts including kernel live patching, update types, tiers, update expectations, and content caching." --- - (client-explanation-architecture)= # Architecture -How Livepatching works and what kind of updates it provides. - -## In this section - -- [How Livepatching works?](/client/explanation/architecture/how-livepatching-works.md) -- [What kind of updates are provided by Livepatch?](/client/explanation/architecture/what-kind-of-updates-are-provided-by-livepatch.md) -- [What kind of updates are not provided by Livepatch?](/client/explanation/architecture/what-kind-of-updates-are-not-provided-by-livepatch.md) -- [What are Livepatch tiers?](/client/explanation/architecture/what-are-livepatch-tiers.md) -- [When should I expect new updates?](/client/explanation/architecture/when-should-i-expect-new-updates.md) -- [Content Caching](/client/explanation/architecture/content-caching.md) +Learn about the Livepatch architecture, including how kernel live patching works, the types of updates provided, and the tiered delivery model. ```{toctree} :titlesonly: :maxdepth: 1 -:hidden: -How livepatching works -What kind of updates are provided by livepatch -What kind of updates are not provided by livepatch -What are livepatch tiers -When should i expect new updates -Content Caching +How kernel live patching works +Updates provided by Livepatch +Updates not provided by Livepatch +Livepatch tiers +When to expect new updates +Content caching ``` diff --git a/docs/client/explanation/architecture/what-are-livepatch-tiers.md b/docs/client/explanation/architecture/what-are-livepatch-tiers.md index ce35009..ea22d22 100644 --- a/docs/client/explanation/architecture/what-are-livepatch-tiers.md +++ b/docs/client/explanation/architecture/what-are-livepatch-tiers.md @@ -1,23 +1,22 @@ --- myst: html_meta: - description: "What are Livepatch tiers? - learn about this topic in Livepatch client." + description: "Understand Livepatch tiers for patch delivery, including Proposed, Internal, Updates, and Stable tiers and how they relate to Ubuntu Pro subscriptions." --- - (client-explanation-what-are-livepatch-tiers)= -# What are Livepatch tiers? +# Livepatch tiers -Livepatch delivers patches to “tiers”. A tier is a target audience for the delivery of a patch. Your tier depends on whether you have a free or paid subscription to [Ubuntu Pro](https://ubuntu.com/pro). The differences are outlined below. +Livepatch delivers patches through a tiered system. A tier is a target audience for patch delivery. Your tier depends on whether you have a free or paid [Ubuntu Pro](https://ubuntu.com/pro) subscription. | Tier | Description | -| :--- | :---: | -| Proposed | The initial tier where patches are added before they are promoted to the next tiers. | -| Internal | For internal Canonical use. Updates are first tested then applied across Canonical infrastructure to decrease the odds of a faulty patch making it to customer machines. | -| Updates | For free users of Ubuntu Pro. Patches are delivered to these machines next. | +| :--- | :--- | +| Proposed | The initial tier where patches are added before promotion to subsequent tiers. | +| Internal | For internal Canonical use. Patches are tested and applied across Canonical infrastructure to reduce the risk of a faulty patch reaching customer machines. | +| Updates | For free users of Ubuntu Pro. Patches are delivered to these machines after the Internal tier. | | Stable | For paid users of Ubuntu Pro. Patches are delivered to these machines last. | -Our kernel team closely monitors the patch health within internal before promoting to updates and further monitoring is done before promoting the patch to stable. +The kernel team monitors patch health within the Internal tier before promoting to the Updates tier, and performs further monitoring before promoting to the Stable tier. -For finer-grained control over patch roll-out take a look at [Livepatch On-Prem](/server/index.md). +For finer-grained control over patch rollout, see the [Livepatch On-Prem documentation](/server/index.md). diff --git a/docs/client/explanation/architecture/what-kind-of-updates-are-not-provided-by-livepatch.md b/docs/client/explanation/architecture/what-kind-of-updates-are-not-provided-by-livepatch.md index 2e11d4e..5e8be16 100644 --- a/docs/client/explanation/architecture/what-kind-of-updates-are-not-provided-by-livepatch.md +++ b/docs/client/explanation/architecture/what-kind-of-updates-are-not-provided-by-livepatch.md @@ -1,23 +1,22 @@ --- myst: html_meta: - description: "What kind of updates are not provided by Livepatch? - learn about this topic in Livepatch client." + description: "Understand which updates are not provided by the Livepatch service, including bug fixes, performance improvements, and driver updates outside of high and critical CVEs." --- - (client-explanation-what-kind-of-updates-are-not-provided-by-the-livepatch-service)= -# What kind of updates are not provided by the Livepatch service? +# Updates not provided by Livepatch -The livepatch service provides patches exclusively for Canonical-released kernels, addressing security issues that have been assigned a CVE and are rated as high or critical priority. +The Livepatch service provides patches exclusively for Canonical-released kernels, addressing security issues that have been assigned a CVE and are rated as high or critical priority. -Livepatches are intended to address significant security issues in the kernel, and provide customers with protection from serious vulnerabilities until they can schedule a reboot. All CVEs that are rated as either a high or critical issue will always be livepatched if possible, and, if it is not possible, a notification that a reboot is required will be issued by the Livepatch client. +Live kernel patches are intended to address significant security issues in the kernel and provide protection from serious vulnerabilities until a reboot can be scheduled. All CVEs rated as high or critical will be fixed through live kernel patching whenever possible. If a live patch cannot be produced, the Livepatch Client issues a notification that a reboot is required. -There are frequently patches included in [kernel updates](https://wiki.ubuntu.com/KernelTeam/KernelUpdates) that are not included in the Livepatch service, such as: +Many patches included in [kernel updates](https://wiki.ubuntu.com/KernelTeam/KernelUpdates) are outside the scope of the Livepatch service, including: -- bug fixes that are not security issues -- performance improvements -- driver updates -- new features +- Bug fixes that are not security issues +- Performance improvements +- Driver updates +- New features -To receive these updates, it is necessary to upgrade the kernel package using the package manager for the system (apt for Ubuntu desktop or server, or snapd if running on Ubuntu Core) and then reboot into the upgraded kernel. +To receive these updates, upgrade the kernel package using your system's package manager — `apt` for Ubuntu Desktop or Server, or `snapd` for Ubuntu Core — then reboot into the upgraded kernel. diff --git a/docs/client/explanation/architecture/what-kind-of-updates-are-provided-by-livepatch.md b/docs/client/explanation/architecture/what-kind-of-updates-are-provided-by-livepatch.md index f1e49be..ccacc51 100644 --- a/docs/client/explanation/architecture/what-kind-of-updates-are-provided-by-livepatch.md +++ b/docs/client/explanation/architecture/what-kind-of-updates-are-provided-by-livepatch.md @@ -1,15 +1,13 @@ --- myst: html_meta: - description: "What kind of updates are provided by Livepatch? - learn about this topic in Livepatch client." + description: "Understand which updates the Livepatch service provides, including high and critical CVE fixes for Linux kernel vulnerabilities delivered as cumulative live kernel patches." --- - (client-explanation-what-kind-of-updates-will-be-provided-by-the-ubuntu-livepatch-service)= -# What kind of updates will be provided by the Ubuntu Livepatch Service? +# Updates provided by Livepatch -The Livepatch Service intends to address high and critical severity Linux kernel security vulnerabilities, as identified by [Ubuntu Security Notices](https://ubuntu.com/security/notices) and the [CVE tracker](https://ubuntu.com/security/cve). Since there are limitations to the [kernel livepatch technology](https://github.com/torvalds/linux/blob/master/Documentation/livepatch/livepatch.rst), some Linux kernel code paths cannot be safely patched while running. There may be occasions when the traditional kernel upgrade and reboot might still be necessary. +The Livepatch service addresses high and critical severity Linux kernel security vulnerabilities, as identified by [Ubuntu Security Notices](https://ubuntu.com/security/notices) and the [CVE tracker](https://ubuntu.com/security/cve). Due to limitations of the [kernel livepatch technology](https://github.com/torvalds/linux/blob/master/Documentation/livepatch/livepatch.rst), some Linux kernel code paths cannot be safely patched while running. In these cases, a traditional kernel upgrade and reboot is necessary. -Livepatches are developed and released based on kernel SRU releases, and contain a subset of the CVEs fixed by that kernel SRU. Livepatches are cumulative, so when a new livepatch is released, it contains both the new CVE fixes, as well as all of the CVE fixes from the previous release of that livepatch. - \ No newline at end of file +Live kernel patches are developed and released based on kernel SRU releases, and contain a subset of the CVEs fixed by each kernel SRU. Patches are cumulative — when a new live kernel patch is released, it contains both the new CVE fixes and all CVE fixes from the previous release of that patch. diff --git a/docs/client/explanation/architecture/when-should-i-expect-new-updates.md b/docs/client/explanation/architecture/when-should-i-expect-new-updates.md index 7281b93..9b22450 100644 --- a/docs/client/explanation/architecture/when-should-i-expect-new-updates.md +++ b/docs/client/explanation/architecture/when-should-i-expect-new-updates.md @@ -1,19 +1,18 @@ --- myst: html_meta: - description: "When should I expect new updates? - learn about this topic in Livepatch client." + description: "Understand when to expect new Livepatch updates, including the relationship between kernel SRU updates and live kernel patches, and notification mechanisms." --- - (client-explanation-when-should-i-expect-new-updates)= -# When should I expect new updates?? +# When to expect new updates -Livepatches are related to and are ''usually'' derived from, but are not the same as, the kernel SRU updates for CVEs. While the vulnerabilities being addressed by both kernel SRU updates and livepatches are the same, the process for development and testing are not. A livepatch for a vulnerability can be significantly more complex than an ordinary kernel patch, and due to the additional complexity, can take more time to develop and test. +Live kernel patches are related to kernel SRU updates for CVEs and are usually derived from them, but are not the same. While the vulnerabilities addressed by both kernel SRU updates and live kernel patches are identical, the development and testing processes differ. A live kernel patch for a vulnerability can be significantly more complex than an ordinary kernel patch and may require additional time to develop and test. -Canonical is committed to livepatching every high or critical rated CVE possible as quickly as we can, and in ideal circumstances, a livepatch will be available at the same time as the corresponding kernel SRU update. +Canonical is committed to live patching every high or critical CVE as quickly as possible. In ideal circumstances, a live kernel patch is available at the same time as the corresponding kernel SRU update. -If we determine that we cannot livepatch a high or critical CVE, we will inform our livepatch users at the same time an SRU kernel update that does fix the issue becomes available, in two ways: +If a high or critical CVE cannot be fixed through live kernel patching, Livepatch users are informed when the SRU kernel update that resolves the issue becomes available. Two notifications are issued: -- The livepatch client will indicate that the system must be rebooted by reporting a state of "reboot required." This will be accompanied by a notification in the desktop, on desktop systems, and a notification in the MOTD on the terminal. -- A LSN will be released containing instructions to reboot into a new SRU kernel that contains a fix for the CVE. LSNs are released on both the security website and via email. +- The Livepatch Client indicates that the system must be rebooted by reporting a state of "reboot required." On desktop systems, this is accompanied by a desktop notification. On all systems, a notification appears in the MOTD on the terminal. +- An LSN is released containing instructions to reboot into a new SRU kernel that includes the CVE fix. LSNs are published on both the security website and via email. diff --git a/docs/client/explanation/index.md b/docs/client/explanation/index.md index 98169e5..ea27e88 100644 --- a/docs/client/explanation/index.md +++ b/docs/client/explanation/index.md @@ -1,30 +1,55 @@ --- myst: html_meta: - description: "Explanation - learn about this topic in Livepatch client." + description: "Explore explanatory and conceptual guides for Livepatch including architecture, security, patch lifecycle, and troubleshooting." --- - (client-explanation)= # Explanation -Discussion and clarification of key topics related to Livepatch. +These explanatory and conceptual guides provide a deeper understanding of how Livepatch works, how patches are delivered, and how to diagnose common issues. -## In this section +## Architecture -- [Architecture](/client/explanation/architecture/index.md) — How Livepatching works and what kind of updates it provides. -- [Security](/client/explanation/security/index.md) — How CVEs are rated and how Livepatch keeps systems secure. -- [Patches](/client/explanation/patches/index.md) — How patches are installed and their lifecycle. -- [Troubleshooting](/client/explanation/troubleshooting/index.md) — Diagnose and understand Livepatch client issues. +Understand how kernel live patching works and the types of updates Livepatch provides. ```{toctree} :titlesonly: :maxdepth: 2 -:hidden: Architecture +``` + +## Security + +Learn how CVEs are rated and how Livepatch protects your systems. + +```{toctree} +:titlesonly: +:maxdepth: 2 + Security +``` + +## Patches + +Explore the lifecycle of live kernel patches, from CVE identification to installation on client machines. + +```{toctree} +:titlesonly: +:maxdepth: 2 + Patches +``` + +## Troubleshooting + +Diagnose and resolve common Livepatch Client issues. + +```{toctree} +:titlesonly: +:maxdepth: 2 + Troubleshooting ``` diff --git a/docs/client/explanation/patches/index.md b/docs/client/explanation/patches/index.md index eefb674..129c284 100644 --- a/docs/client/explanation/patches/index.md +++ b/docs/client/explanation/patches/index.md @@ -1,28 +1,19 @@ --- myst: html_meta: - description: "How patches are installed, their lifecycle, and security considerations." + description: "Explore the Livepatch patch lifecycle and installation process, including how patches move from CVE identification to client application." --- - (client-explanation-patches)= # Patches -How patches are installed, their lifecycle, and security considerations. - -## In this section - -- [Patch Lifecycle: From CVE to Client Machines](/client/explanation/patches/patch-lifecycle.md) -- [Patch Installation](/client/explanation/patches/patch-installation.md) +Explore the lifecycle of live kernel patches, from initial CVE identification through development, testing, and distribution to installation on client machines. ```{toctree} :titlesonly: :maxdepth: 1 -:hidden: -Patch Lifecycle -Patch Installation +Patch lifecycle +Patch installation ``` - - diff --git a/docs/client/explanation/patches/patch-installation.md b/docs/client/explanation/patches/patch-installation.md index 9c565d7..6236501 100644 --- a/docs/client/explanation/patches/patch-installation.md +++ b/docs/client/explanation/patches/patch-installation.md @@ -1,37 +1,31 @@ --- myst: html_meta: - description: "Patch Installation - technical reference for Livepatch client." + description: "Understand how Livepatch patch installation works, including module insertion, crash loop prevention, boot behavior, and kernel version matching." --- - (client-explanation-patches-patch-installation)= -# Patch Installation - -This document acts as a reference on how patch installation takes place. - -## How are patches installed? +# Patch installation -Once the Livepatch client downloads a patch, it is stored on the machine's filesystem. The patch contains a Linux kernel module responsible for patching the running kernel. +This document explains how live kernel patches are installed, how the Livepatch Client prevents crash loops, and how patches are matched to the running kernel. -The Livepatch client inserts the kernel module by making the appropriate syscall. The kernel module only affects the kernel as it is in-memory, without modifying the installed kernel. +## How patches are installed -## What if my system crashes or the patch is buggy after a Livepatch module is inserted? +When the Livepatch Client downloads a patch, it is stored on the machine's filesystem. The patch contains a Linux kernel module responsible for patching the running kernel. The client inserts this kernel module by making the appropriate syscall. The module affects only the in-memory kernel, without modifying the installed kernel on disk. -If a module crashes a system, it will not be loaded on reboot. Livepatch will make a best-effort attempt to not re-insert and reload the patch, given it detects a system crash within 10 seconds of loading the module. +## Crash loop prevention -In a scenario where a patch contains a bug, Livepatch will do a best effort match against the kernel logs to locate bug messages after insertion. In case a bug is found the Livepatch client will report that the module was inserted but caused a bug and the patch will not be reapplied on reboot +If a module causes a system crash, it is not loaded on reboot. The Livepatch Client makes a best-effort attempt to avoid re-inserting and reloading the patch if it detects a system crash within 10 seconds of loading the module. -Additionally, in both cases a “lockfile” is created, containing the bug trace. +If a patch contains a bug, the Livepatch Client performs a best-effort match against kernel logs to locate bug messages after insertion. When a bug is detected, the client reports that the module was inserted but caused a bug, and the patch is not reapplied on reboot. -On the next reboot of the machine, if the lockfile is present, the patch will not be inserted again. -After Canonical becomes aware that the patch is faulty, it will be blocked from delivery. +In both crash and bug scenarios, a lockfile is created containing the bug trace. On the next reboot, if the lockfile is present, the patch is not inserted again. Once Canonical becomes aware that the patch is faulty, it is blocked from delivery. -## Are the Livepatch modules inserted on system boot? +## Boot behavior -No, we do not insert the modules at boot, instead patches are inserted when the Livepatch client daemon service starts. This helps to prevent placing a system into a crash loop. +Modules are not inserted at boot time. Patches are inserted when the Livepatch Client daemon service starts. This design prevents placing a system into a crash loop during startup. -## How do I know if the patch is designed for my system? +## Kernel version matching -Each patch payload designed for Livepatch contains the kernel version in the format “ABI.BUILDNO-FLAVOUR” which is matched against the currently running kernel. +Each patch payload designed for Livepatch contains the kernel version in the format `ABI.BUILDNO-FLAVOUR`, which is matched against the currently running kernel. This ensures a patch is only applied to the kernel it was built for. diff --git a/docs/client/explanation/patches/patch-lifecycle.md b/docs/client/explanation/patches/patch-lifecycle.md index 6cf63b5..3a32df3 100644 --- a/docs/client/explanation/patches/patch-lifecycle.md +++ b/docs/client/explanation/patches/patch-lifecycle.md @@ -1,56 +1,58 @@ --- myst: html_meta: - description: "Patch Lifecycle - technical reference for Livepatch client." + description: "Understand the full lifecycle of live kernel patches in Livepatch, from CVE triage and development through testing, release, installation, and ongoing monitoring." --- - (client-explanation-patches-patch-lifecycle-from-cve-to-client-machines)= -# Patch Lifecycle: From CVE to Client Machines - -This document outlines the comprehensive lifecycle of kernel live patches, from the initial identification of Common Vulnerabilities and Exposures (CVEs), to their distribution and ongoing monitoring on customer systems. It details the rigorous quality assurance (QA) methods employed to ensure the stability and effectiveness of patches, and how they are delivered and observed in the field. +# Patch lifecycle: from CVE to client machines -## CVE Triage and Kernel Patching Process +This document outlines the complete lifecycle of kernel live patches, from the initial identification of Common Vulnerabilities and Exposures (CVEs) through to distribution and ongoing monitoring on customer systems. It covers the quality assurance (QA) methods used to ensure patch stability and effectiveness, and how patches are delivered and observed in the field. -The process begins with the Canonical Security team, which receives initial CVE reports and provides a list of CVEs affecting kernel packages, and passes them on to the kernel team. The kernel team then triages these CVEs, assigning priority levels (e.g., high, critical). The kernel team also writes the patches for the affected kernels to fix these CVEs. Only patches that fix high or critical severity Linux kernel vulnerabilities are eligible for livepatch. The Livepatch team is responsible for developing kernel livepatches based on the prioritized patches. While the vulnerabilities being addressed by the kernel updates and livepatches are the same, a livepatch for a vulnerability can be significantly more complex than an ordinary kernel patch. +## CVE triage and kernel patching -## Livepatch Testing and Release +The process begins with the Canonical Security team, which receives initial CVE reports, identifies CVEs affecting kernel packages, and forwards them to the kernel team. The kernel team triages these CVEs, assigning priority levels such as high or critical, and writes patches for the affected kernels. Only patches that fix high or critical severity Linux kernel vulnerabilities are eligible for live kernel patching. -Livepatches undergo a meticulous testing process. Easy patches are prioritized first, while more complex ones requiring rework or backports are addressed subsequently. Testing involves: +The Livepatch team develops live kernel patches based on the prioritized kernel patches. While the vulnerabilities addressed by kernel updates and live kernel patches are the same, a live kernel patch for a vulnerability can be significantly more complex than an ordinary kernel patch. -- **Unit tests**: Performed on a virtual machine by loading the livepatch against the same kernel it was written for. -- **Kernel regression tests**: Determine if the livepatch causes any issues while running kernel regression tests. The goal is for the livepatched kernel to pass the same tests as the original, unpatched kernel. These tests are performed on internal machines and monitored for any problems in the patches +## Testing and release -Upon successful testing internally, patches are released in phases to the updates tier (e.g., 10%, 20%, 40%, 60%), which consists of free users of Ubuntu Pro. The Livepatch team continuously monitors the metrics for each patch version. This is done using the monitoring support included with the Livepatch client to track patch health and client machine issues. If no crashes are detected and no negative feedback or bug reports are raised, the livepatches are then promoted to the stable tier, which is available to paid Ubuntu Pro users. +Live kernel patches undergo a thorough testing process. Simpler patches are prioritized first, while more complex ones requiring rework or backports are addressed subsequently. Testing includes: -## Livepatch Installation +- **Unit tests**: Performed on a virtual machine by loading the live kernel patch against the same kernel it was written for. +- **Kernel regression tests**: Verify that the live kernel patch does not introduce issues when running kernel regression tests. The objective is for the live-patched kernel to pass the same tests as the original, unpatched kernel. These tests run on internal machines and are monitored for any problems. -Once the livepatch for a kernel has been released for use, the Livepatch client downloads the patch from the configured Livepatch server and patch source. The downloaded payload consists of the Linux kernel module responsible for patching the running kernel, as well as some metadata. The Livepatch client then inserts the kernel module by making the appropriate syscall. This only affects the in-memory kernel code and not the installed kernel. +After successful internal testing, patches are released in phases to the Updates tier (for example, 10%, 20%, 40%, 60%), which serves free users of Ubuntu Pro. The Livepatch team continuously monitors metrics for each patch version using the monitoring support included with the Livepatch Client to track patch health and client machine issues. If no crashes are detected and no negative feedback or bug reports are raised, the patches are promoted to the Stable tier, available to paid Ubuntu Pro users. -The Livepatch client is also equipped with mechanisms to prevent crash loops on installation of a faulty livepatch. For more information on patch installation and preventing crash loops, see [Patch Installation reference](/client/explanation/patches/patch-installation.md) +## Installation -## Livepatch Security +Once a live kernel patch has been released, the Livepatch Client downloads it from the configured Livepatch Server and patch source. The downloaded payload consists of the Linux kernel module responsible for patching the running kernel, along with metadata. The Livepatch Client inserts the kernel module by making the appropriate syscall. This affects only the in-memory kernel code, not the installed kernel. -Ensuring the secure transmission and application of a livepatch is paramount to maintaining kernel stability and preventing installation of malicious kernel modules. The Livepatch client ensures that installed livepatches are genuine and authentic before applying them to the kernel. This is achieved by verifying the livepatch content using SHA256 file checksums, verifying the digital signature for the livepatch kernel module using asymmetric encryption and using TLS to communicate with the hosted Canonical Livepatch server. +The Livepatch Client includes mechanisms to prevent crash loops when installing a faulty live kernel patch. For more information on patch installation and crash loop prevention, see the [Patch installation reference](/client/explanation/patches/patch-installation.md). -For more information on how the security of livepatches is ensured, see [Patch Security reference.](/client/reference/patches/patch-security.md) +## Security -## Livepatch Monitoring and Blocklisting on faulty patches +Ensuring secure transmission and application of live kernel patches is essential to maintaining kernel stability and preventing the installation of malicious kernel modules. The Livepatch Client verifies that installed patches are genuine before applying them to the kernel: -In order to [avoid crash loops after application of a faulty livepatch](/client/explanation/patches/patch-installation.md), Livepatch client monitors the health of the machine before, during, and after the patching activity. The various phases of Livepatch client's activity include: patch download, patch insertion, patch transition, and patch application. +- Patch content is verified using SHA256 file checksums. +- The digital signature for the Livepatch kernel module is verified using asymmetric encryption. +- Communication with the hosted Canonical Livepatch Server uses TLS. -Livepatch client transmits pings which contain data about patching activity to Livepatch server. These pings are anonymous and are only used to understand the health and status of machines during the insertion process and after the application process. +For more information on how patch security is ensured, see the [Patch security reference](/client/reference/patches/patch-security.md). -Insertion pings are sent just before and after the livepatch module has been loaded into the kernel. These pings enable the Livepatch team to monitor the number of livepatch module insertions that were attempted. Note that once loaded, the kernel may not apply the patch immediately if the patch affects functions that are under heavy use. +## Monitoring and blocklisting -If the system is running a kernel version above 4.4, the client will move into a transition period where it waits for the kernel to report the patch has been applied. Livepatch client sends transition pings to Livepatch Server which provides data about how many machines have livepatch modules loaded into the kernel, but have not been applied yet. However, if the application of a livepatch results in a kernel crash or a kernel bug within the transition period the error state is reported to the Livepatch server detailing the reason for the failure. Once the client detects the kernel applied the livepatch module, the client proceeds to the the health check pings. +To prevent crash loops after applying a faulty live kernel patch, the Livepatch Client monitors machine health before, during, and after patching activity. The phases of client activity include patch download, patch insertion, patch transition, and patch application. -If the system is on kernel version 4.4 or earlier, due to older kernel interfaces, the client will not enter a transition period, and instead check kernel logs for issues after 10 seconds before proceeding to the health check pings. +The Livepatch Client transmits pings containing data about patching activity to the Livepatch Server. These pings are anonymous and are used solely to understand the health and status of machines during and after the patching process. -After a livepatch module is applied, the Livepatch client sends multiple health pings to the hosted Canonical Livepatch server. The first ping will have the time spent waiting for the kernel to apply the livepatch module (if running a kernel later than version 4.4), Then the client sends 3 more health pings from 1 minute, 5 minutes and 15 minutes from the time the kernel applied the livepatch module. +**Insertion pings** are sent immediately before and after the Livepatch module is loaded into the kernel. These pings allow the Livepatch team to monitor the number of insertion attempts. After loading, the kernel may not apply the patch immediately if the affected functions are under heavy use. -If Livepatch client is retrieving patches from livepatch.canonical.com, the reported metrics are monitored by Canonical's Livepatch team. In the unlikely event that Livepatch client is reporting an error across a significant number of machines, the Livepatch team performs further analysis, and considers halting distribution (blocklisting) of the patch in question. Once a patch has been blocklisted, it will no longer be distributed to new clients or applied in the client machines that already possess the blocklisted patch. +If the system is running a kernel version above 4.4, the client enters a **transition period** where it waits for the kernel to report that the patch has been applied. The client sends transition pings to the Livepatch Server, providing data about machines with loaded but unapplied patch modules. If patch application results in a kernel crash or bug during the transition period, the error state is reported to the Livepatch Server with details about the failure. Once the client detects the kernel has applied the module, it proceeds to health check pings. +If the system is on kernel version 4.4 or earlier, the client does not enter a transition period due to older kernel interfaces. Instead, it checks kernel logs for issues after 10 seconds before proceeding to health check pings. +After a Livepatch module is applied, the client sends multiple **health pings** to the hosted Canonical Livepatch Server. The first ping includes the time spent waiting for the kernel to apply the module (for kernels later than version 4.4). The client then sends three additional health pings at 1 minute, 5 minutes, and 15 minutes from the time the kernel applied the module. +If the client retrieves patches from `livepatch.canonical.com`, the reported metrics are monitored by Canonical's Livepatch team. If the client reports errors across a significant number of machines, the Livepatch team performs further analysis and considers halting distribution (blocklisting) of the patch. Once a patch is blocklisted, it is no longer distributed to new clients or applied on client machines that already possess it. diff --git a/docs/client/explanation/security/how-cves-are-rated.md b/docs/client/explanation/security/how-cves-are-rated.md index ffc1b9e..e99b935 100644 --- a/docs/client/explanation/security/how-cves-are-rated.md +++ b/docs/client/explanation/security/how-cves-are-rated.md @@ -1,20 +1,19 @@ --- myst: html_meta: - description: "How CVEs are rated? - learn about this topic in Livepatch client." + description: "Understand how Canonical rates CVEs in Livepatch, including the rating scale from negligible to critical and what each rating means." --- - (client-explanation-how-do-you-rate-a-cve)= -# How do you rate a CVE? +# How CVEs are rated -We do not use an external rating system, but rate based on these qualifications: +Canonical uses its own rating system for CVEs based on the following qualifications: -| | | -|-----------------------|-----------------------------------------------------------------------| -| *negligible* | Something that is technically a security problem, but is only theoretical in nature, requires a very special situation, has almost no install base, or does no real damage. These tend not to get backport from upstreams, and will likely not be included in security updates unless there is an easy fix and some other issue causes an update.| -| *low* | Something that is a security problem, but is hard to exploit due to environment, requires a user-assisted attack, a small install base, or does very little damage. These tend to be included in security updates only when higher priority issues require an update, or if many low priority issues have built up.| -| *medium* | Something is a real security problem, and is exploitable for many people. Includes network daemon denial of service attacks, cross-site scripting, and gaining user privileges. Updates should be made soon for this priority of issue.| -| *high* | A real problem, exploitable for many people in a default installation. Includes serious remote denial of services, local root privilege escalations, or data loss.| -| *critical* | A world-burning problem, exploitable for nearly all people in a default installation of Ubuntu. Includes remote root privilege escalations, or massive data loss.| +| Rating | Description | +|--------|-------------| +| Negligible | A theoretical security problem that requires a very specific scenario, has a minimal install base, or causes negligible damage. These usually do not receive backports from upstream and are unlikely to be included in security updates unless an easy fix is available and another issue triggers an update. | +| Low | A security problem that is difficult to exploit due to environment constraints, requires a user-assisted attack, has a small install base, or causes limited damage. These are typically included in security updates only when higher priority issues require an update or when many low priority issues have accumulated. | +| Medium | A real security problem that is exploitable for many users. Includes network daemon denial of service attacks, cross-site scripting, and gaining user privileges. Updates should be produced promptly for this priority. | +| High | A real problem, exploitable for many users in a default installation. Includes serious remote denial of service, local root privilege escalation, or data loss. | +| Critical | A severe problem, exploitable for nearly all users in a default installation of Ubuntu. Includes remote root privilege escalation or massive data loss. | diff --git a/docs/client/explanation/security/index.md b/docs/client/explanation/security/index.md index 4e3a4c0..67719b7 100644 --- a/docs/client/explanation/security/index.md +++ b/docs/client/explanation/security/index.md @@ -1,29 +1,20 @@ --- myst: html_meta: - description: "How CVEs are rated and how Livepatch keeps systems secure." + description: "Explore Livepatch security concepts including CVE rating, security lifecycle, security notices, and overview of built-in protections." --- - (client-explanation-security)= # Security -How CVEs are rated and how Livepatch keeps systems secure. - -## In this section - -- [How CVEs are rated?](/client/explanation/security/how-cves-are-rated.md) -- [Security Overview](/client/explanation/security/security-overview.md) -- [Security Lifecycle](/client/explanation/security/security-lifecycle.md) -- [Livepatch security notices](/client/explanation/security/livepatch-security-notices.md) +Understand how Livepatch secures your systems, including how CVEs are rated, how the client security lifecycle is managed, and what built-in protections are in place. ```{toctree} :titlesonly: :maxdepth: 1 -:hidden: -How cves are rated +How CVEs are rated Security overview Security lifecycle Livepatch security notices diff --git a/docs/client/explanation/security/livepatch-security-notices.md b/docs/client/explanation/security/livepatch-security-notices.md index 10ebf08..1140181 100644 --- a/docs/client/explanation/security/livepatch-security-notices.md +++ b/docs/client/explanation/security/livepatch-security-notices.md @@ -1,17 +1,18 @@ --- myst: html_meta: - description: "Livepatch security notices - learn about this topic in Livepatch client." + description: "Understand Livepatch security notices (LSNs), including when they are issued and how to subscribe to Ubuntu Security Announcements." --- - (client-explanation-livepatch-security-notices)= # Livepatch security notices -The Livepatch Security Notices (LSN) are notifications issued for kernel vulnerabilities. They can be accessed by following our [Security notices](https://ubuntu.com/security/notices) or by subscribing to the [Ubuntu Security Announcements](https://lists.ubuntu.com/mailman/listinfo/ubuntu-security-announce) mailing list. LSNs are released for every high or critical kernel vulnerability. They are released for: +Livepatch Security Notices (LSNs) are notifications issued for kernel vulnerabilities. You can access them through the [Security notices](https://ubuntu.com/security/notices) page or subscribe to the [Ubuntu Security Announcements](https://lists.ubuntu.com/mailman/listinfo/ubuntu-security-announce) mailing list. + +LSNs are released for every high or critical kernel vulnerability. They are issued in two scenarios: -- Announcing a new livepatch addressing a vulnerability. -- Communicating an alert if a livepatch cannot be released describing the reason and possible mitigation. In that case - - a standard [Ubuntu security notice](https://ubuntu.com/security/notices) (USN) will be released with packages along side it to fix the issue. - - the livepatch client will issue a warning that an update and reboot is necessary. +- Announcing a new live kernel patch that addresses a vulnerability. +- Alerting users when a live kernel patch cannot be released, describing the reason and possible mitigation. In this case: + - A standard [Ubuntu Security Notice](https://ubuntu.com/security/notices) (USN) is released with packages to resolve the issue. + - The Livepatch Client issues a warning that an update and reboot is necessary. diff --git a/docs/client/explanation/security/security-lifecycle.md b/docs/client/explanation/security/security-lifecycle.md index f99d9b3..b0af6ee 100644 --- a/docs/client/explanation/security/security-lifecycle.md +++ b/docs/client/explanation/security/security-lifecycle.md @@ -1,25 +1,31 @@ --- myst: html_meta: - description: "Security Lifecycle - learn about this topic in Livepatch client." + description: "Understand the Livepatch Client security lifecycle, including snap release channels, automatic security updates, and managing refresh behavior." --- - (client-explanation-livepatch-client-security-lifecycle)= -# Livepatch Client Security Lifecycle +# Livepatch Client security lifecycle + +The Livepatch Client is released as a snap. Releases are issued on an ad-hoc basis as features and bug fixes are implemented. When a security vulnerability is detected in an upstream dependency, a best-effort attempt is made to upgrade the dependency to the latest version that resolves the vulnerability. This security fix is then included in the next ad-hoc release. + +It is recommended to install the [canonical-livepatch snap](https://snapcraft.io/canonical-livepatch) from the `latest/stable` channel in the Snap Store. This channel provides the latest stable version of the snap, including all recent stable security updates. -The Livepatch Client is released as a snap. The releases for the client are done ad-hoc as a number of features and bug fixes are implemented. When a security vulnerability in an upstream dependency is detected, a best-case effort is made to upgrade the dependency to the latest version that fixes the vulnerability. This security fix is then included in the next ad-hoc release. +## Security updates -It is recommended that the [canonical-livepatch snap](https://snapcraft.io/canonical-livepatch) is installed from the `latest/stable` channel from the snapstore. This channel will hold the latest stable version for the snap, including receiving all of the most recent stable security updates. +Security updates are released to the `latest/stable` channel of the canonical-livepatch snap. By default, these updates are automatically applied by the snapd daemon, which checks for updates four times a day and applies them when available. Each update check is called a **refresh**. -## Security Updates +You can control the default update behavior of snapd using the `snap refresh` command. This includes: -Security updates will be released to the `latest/stable` channel of the canonical-livepatch snap. By default, these security updates will be automatically applied to the installed canonical-livepatch snap by the snapd daemon. The snapd daemon checks for these updates four times a day and applies an update when it is available. Each of these update checks is called a **refresh**. +- Manually checking for and applying updates +- Postponing updates for a period of time or indefinitely +- Scheduling updates +- Rolling back automatically applied updates -The default update behaviour of the snapd daemon can be controlled using the `snap refresh` command. This includes manually checking for and applying updates, postponing updates for a period of time or indefinitely, scheduling updates and rolling back automatically applied updates. For more information, view the [snap documentation](https://snapcraft.io/docs/how-to-guides/manage-snaps/manage-updates/#refresh-update-control) on managing snap updates. +For more information, see the [snap documentation on managing updates](https://snapcraft.io/docs/how-to-guides/manage-snaps/manage-updates/#refresh-update-control). -Please note that, modifying the default auto-update behavior of the snapd daemon, could leave systems vulnerable to important security updates shipped to the snaps. To verify that a security update has been successfully applied, run `snap info canonical-livepatch` and ensure that the installed snap version matches the snap version in the `latest/stable` channel. If the versions do not match, manually apply the most recent updates by running the following command: +Modifying the default auto-update behavior of snapd could leave systems vulnerable to important security updates. To verify that a security update has been applied, run `snap info canonical-livepatch` and confirm that the installed snap version matches the version in the `latest/stable` channel. If the versions do not match, manually apply the most recent updates: ``` sudo snap refresh canonical-livepatch --channel=latest/stable diff --git a/docs/client/explanation/security/security-overview.md b/docs/client/explanation/security/security-overview.md index f235856..e89bf7c 100644 --- a/docs/client/explanation/security/security-overview.md +++ b/docs/client/explanation/security/security-overview.md @@ -1,44 +1,39 @@ --- myst: html_meta: - description: "Security Overview - learn about this topic in Livepatch client." + description: "Overview of Livepatch Client security including patch verification, cryptographic signatures, TLS communication, and related security documentation." --- - (client-explanation-security-overview)= -# Security Overview +# Security overview -This document provides an overview of the security features and practices implemented within the Livepatch Client. It aims to give users a general perspective on how security is handled, outlining built-in protections and pointing to more detailed documentation for specific cryptographic approaches and operational guides. +This document provides an overview of the security features and practices implemented in the Livepatch Client. It describes the built-in protections and points to more detailed documentation for specific cryptographic approaches and operational guides. -## Built-in Protection +## Built-in protections -The Livepatch client incorporates several mechanisms to ensure the integrity and authenticity of patches and the security of communication: +The Livepatch Client incorporates several mechanisms to ensure the integrity and authenticity of patches and the security of communication: -- **Patch Verification**: Patches undergo a verification process using SHA256 checksums to ensure file integrity upon download. For more details, refer to the [Cryptographic Documentation](/client/reference/patches/patch-security.md). +- **Patch verification**: Patches undergo verification using SHA256 checksums to confirm file integrity after download. For more details, see the [Patch security reference](/client/reference/patches/patch-security.md). -- **Patch Signatures**: All Linux kernel modules distributed as part of patches are cryptographically signed by Canonical using SHA512 with RSA. This verifies their authenticity and prevents the installation of malicious patches. Further information can be found in the [Cryptographic Documentation](/client/reference/patches/patch-security.md). +- **Patch signatures**: All Linux kernel modules distributed as patches are cryptographically signed by Canonical using SHA512 with RSA. This verifies authenticity and prevents the installation of malicious patches. For more information, see the [Patch security reference](/client/reference/patches/patch-security.md). -- **TLS Communication**: The Livepatch client uses HTTPS and relies on TLS v1.2 or higher for secure communication with the Livepatch server, utilizing host machine CA certificates and additional fixed certificates for server authentication. Details on TLS communication are available in the [Cryptographic Documentation](/client/reference/patches/patch-security.md). +- **TLS communication**: The Livepatch Client uses HTTPS with TLS v1.2 or higher for secure communication with the Livepatch Server, using host machine CA certificates and additional fixed certificates for server authentication. For details on TLS communication, see the [Patch security reference](/client/reference/patches/patch-security.md). ## Risks -While the Livepatch client is designed with security in mind, it is important to be aware of potential risks: - -- **TLS Enforcement (On-premises deployments)**: Although the Canonical hosted Livepatch server redirects HTTP to HTTPS, there is no client-side enforcement for TLS usage in on-premises deployments. Forgoing TLS in such scenarios is not recommended due to security implications. - -- **Privileged access to Auth Tokens**: Authentication for the Livepatch Client, with the Livepatch Server, can be established using [Auth Tokens](/server/reference/authentication/authentication.md#client-apis) or [Resource Tokens](/server/reference/authentication/authentication.md#client-apis). After successful client registration, a machine token is issued to the Livepatch client which can be used for subsequent authentication. Privileged access to this token must be controlled to prevent usage by a malicious third-party. - -- **Data at Rest**: The Livepatch client does not encrypt its data at rest. However, all client data is stored in the [$SNAP_COMMON](https://snapcraft.io/docs/reference/development/environment-variables/#snap-common) and [$SNAP_DATA](https://snapcraft.io/docs/reference/development/environment-variables/#snap-data) directories. The Livepatch client snap ensures that only the root user has read and write access to the sensitive data stored in these directories. It is recommended to maintain strict privileged access controls, to prevent unauthorized access of the snap data. - -## Related Security Documentation +While the Livepatch Client is designed with security in mind, be aware of the following potential risks: -[Patch Security](/client/reference/patches/patch-security.md): This document provides in-depth details on the cryptographic approaches used by the Livepatch client for patch verification, signatures, and secure communication. +- **TLS enforcement (on-premises deployments)**: The Canonical hosted Livepatch Server redirects HTTP to HTTPS, but there is no client-side enforcement for TLS usage in on-premises deployments. Forgoing TLS in such deployments is not recommended. -[Secure Client Operation](/client/how-to-guides/security/securely-configure-and-operate-the-client.md): This document provides information on how to securely configure and operate the Livepatch client. +- **Privileged access to auth tokens**: Authentication for the Livepatch Client can be established using [Auth tokens](/server/reference/authentication/authentication.md#client-apis) or [Resource tokens](/server/reference/authentication/authentication.md#client-apis). After successful client registration, a machine token is issued to the client for subsequent authentication. Control privileged access to this token to prevent use by a malicious third party. -[Secure Client Decommissioning](/client/how-to-guides/security/securely-decommission-the-client.md): This document provides information on how to securely decommission the Livepatch client snap and its data. +- **Data at rest**: The Livepatch Client does not encrypt its data at rest. All client data is stored in the `$SNAP_COMMON` and `$SNAP_DATA` directories. The Livepatch Client snap ensures only the root user has read and write access to sensitive data in these directories. Maintain strict privileged access controls to prevent unauthorized access to snap data. -[Security Lifecycle](/client/explanation/security/security-lifecycle.md):This document provides insights into how the security of the Livepatch client is maintained. It also provides guidelines on how security updates to the Livepatch client snap can be controlled. +## Related documentation -[Reporting Security Vulnerabilities](/client/how-to-guides/security/report-client-vulnerability.md): This document lays out the process to report security vulnerabilities found in the Livepatch client and provides information about the Ubuntu Security disclosure and embargo policy. +- [Patch security](/client/reference/patches/patch-security.md): In-depth details on the cryptographic approaches used by the Livepatch Client for patch verification, signatures, and secure communication. +- [Secure client operation](/client/how-to-guides/security/securely-configure-and-operate-the-client.md): How to securely configure and operate the Livepatch Client. +- [Secure client decommissioning](/client/how-to-guides/security/securely-decommission-the-client.md): How to securely decommission the Livepatch Client snap and its data. +- [Security lifecycle](/client/explanation/security/security-lifecycle.md): How the security of the Livepatch Client is maintained, with guidelines on controlling security updates to the snap. +- [Reporting security vulnerabilities](/client/how-to-guides/security/report-client-vulnerability.md): The process for reporting security vulnerabilities in the Livepatch Client, including information about the Ubuntu Security disclosure and embargo policy. diff --git a/docs/client/explanation/troubleshooting/do-i-need-to-reboot.md b/docs/client/explanation/troubleshooting/do-i-need-to-reboot.md index 3be3ce9..66c2a67 100644 --- a/docs/client/explanation/troubleshooting/do-i-need-to-reboot.md +++ b/docs/client/explanation/troubleshooting/do-i-need-to-reboot.md @@ -1,22 +1,25 @@ --- myst: html_meta: - description: "Do I need to reboot? - learn about this topic in Livepatch client." + description: "Understand when a reboot is required for Ubuntu systems using Livepatch, including kernel upgrades and other system components that require restarts." --- - (client-explanation-do-i-need-to-reboot)= -# Do I need to reboot? +# When to reboot + +Live kernel patching is not sufficient when you need to upgrade your kernel to a newer version — a reboot is required in that case. Live kernel patches include only high and critical kernel vulnerabilities. The service provides protection from serious security issues, but this is only one aspect of keeping your system secure and well maintained. -To upgrade (not just patch) your kernel to the newest version livepatching is not sufficient, and you need to reboot. Note that livepatches include only high and critical kernel vulnerabilities. The service provides protection from serious security issues, but this is just one aspect of keeping your system secure and well maintained. There are a number of other software components that can require you to reboot your system, including, but not limited to: +Several other software components can require a system reboot, including: - CPU firmware and microcode updates -- Updates to shared libraries and low-level dependencies (glibc, for example) +- Updates to shared libraries and low-level dependencies (such as glibc) - System BIOS and EFI updates -**Enabling the Livepatch service does not turn on automatic installation of security updates in APT.** +Enabling the Livepatch service does not turn on automatic installation of security updates in APT. For best security, you should: -For best security, you should [enable security updates using APT](https://help.ubuntu.com/community/AutomaticSecurityUpdates), subscribe to the [security announcement mailing list](https://lists.ubuntu.com/mailman/listinfo/ubuntu-security-announce), follow all advised security updates, and reboot your system at your earliest convenience when any software component requires it. +- [Enable security updates using APT](https://help.ubuntu.com/community/AutomaticSecurityUpdates) +- 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 -Additionally, kernel SRU updates include non-security bugfixes and lower-priority security fixes that may be important to your specific circumstances, and 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. \ No newline at end of file diff --git a/docs/client/explanation/troubleshooting/index.md b/docs/client/explanation/troubleshooting/index.md index 5d22433..51c59c5 100644 --- a/docs/client/explanation/troubleshooting/index.md +++ b/docs/client/explanation/troubleshooting/index.md @@ -1,34 +1,23 @@ --- myst: html_meta: - description: "Diagnose and understand Livepatch client issues." + description: "Diagnose and understand common Livepatch Client issues including unsupported kernels, missing patches, reboots, service access, and patch cut-off dates." --- - (client-explanation-troubleshooting)= # Troubleshooting -Diagnose and understand Livepatch client issues. - -## In this section - -- [Why Livepatch is not working on my machine?](/client/explanation/troubleshooting/why-livepatch-is-not-working-on-my-machine.md) -- [Service access problem](/client/explanation/troubleshooting/service-access-problem.md) -- [Why are there missing patches?](/client/explanation/troubleshooting/why-are-there-missing-patches.md) -- [What happens when a problem cannot be patched?](/client/explanation/troubleshooting/what-happens-when-a-problem-cannot-be-patched.md) -- [Do I need to reboot?](/client/explanation/troubleshooting/do-i-need-to-reboot.md) -- [What is patch cut-off date?](/client/explanation/troubleshooting/what-is-patch-cut-off-date.md) +Diagnose and understand common Livepatch Client issues. ```{toctree} :titlesonly: :maxdepth: 1 -:hidden: -Why livepatch is not working on my machine -Service access problem -Why are there missing patches -What happens when a problem cannot be patched -Do i need to reboot -What is patch cut off date -``` +Livepatch not working +Service access problems +Missing patches +Unpatchable problems +When to reboot +Patch cut-off date +``` \ No newline at end of file diff --git a/docs/client/explanation/troubleshooting/service-access-problem.md b/docs/client/explanation/troubleshooting/service-access-problem.md index 7d1bef6..883d15d 100644 --- a/docs/client/explanation/troubleshooting/service-access-problem.md +++ b/docs/client/explanation/troubleshooting/service-access-problem.md @@ -1,14 +1,13 @@ --- myst: html_meta: - description: "Service access problem - learn about this topic in Livepatch client." + description: "Diagnose Livepatch service access problems including network connectivity to the Livepatch service and proxy configuration requirements." --- - (client-explanation-i-cannot-access-the-livepatch-service)= -# I cannot access the Livepatch service +# Service access problems -Network access to the Ubuntu Livepatch Service ([https://livepatch.canonical.com:443](https://livepatch.canonical.com/)) is necessary as well as snapd version 2.15 - check your snapd version with `snap version`. +Network access to the Ubuntu Livepatch Service at `https://livepatch.canonical.com:443` is required for the client to function. The system must also be running snapd version 2.15 or later. Check your snapd version with `snap version`. -In addition to that, sometimes it could be a problem with the proxy configurations. Please check out [this](/client/how-to-guides/configuration/configure-proxy.md) guide on how to configure the Livepatch client to use a proxy. +If network access is available but the client cannot connect, the issue may be related to proxy configuration. See the guide on [configuring the Livepatch Client to use a proxy](/client/how-to-guides/configuration/configure-proxy.md). \ No newline at end of file diff --git a/docs/client/explanation/troubleshooting/what-happens-when-a-problem-cannot-be-patched.md b/docs/client/explanation/troubleshooting/what-happens-when-a-problem-cannot-be-patched.md index 1b4561a..66d06f1 100644 --- a/docs/client/explanation/troubleshooting/what-happens-when-a-problem-cannot-be-patched.md +++ b/docs/client/explanation/troubleshooting/what-happens-when-a-problem-cannot-be-patched.md @@ -1,14 +1,13 @@ --- myst: html_meta: - description: "What happens when a problem cannot be patched? - learn about this topic in Livepatch client." + description: "Understand what happens when a kernel vulnerability cannot be patched via live kernel patching, including kernel upgrades, reboots, and client notifications." --- - (client-explanation-what-happens-when-a-problem-occurs-that-cant-be-patched)= -# What happens when a problem occurs that can’t be patched? +# Unpatchable problems -When an un-patchable security issue occurs, users *must* upgrade to a version of the kernel that is fixed, and reboot. Problems of this type are announced on the mailing list via LSN. Kernels prior to the levels named in that announcement will no longer be livepatched. +When a security issue occurs that cannot be addressed with a live kernel patch, you must upgrade to a fixed version of the kernel and reboot. Problems of this type are announced on the mailing list via LSNs. Kernels prior to the levels identified in that announcement will no longer receive live kernel patches. -The Livepatch client will report a state of "kernel-upgrade-required" if you are running a kernel that is no longer livepatched due to an earlier un-patchable kernel security issue. This notice will appear in the user's desktop notifications, and in the text-based message of the day (MOTD) if logged into a terminal. +The Livepatch Client reports a state of "kernel-upgrade-required" if you are running a kernel that no longer receives live kernel patches due to an earlier unpatchable kernel security issue. This notice appears in the user's desktop notifications and in the text-based message of the day (MOTD) when logged into a terminal. \ No newline at end of file diff --git a/docs/client/explanation/troubleshooting/what-is-patch-cut-off-date.md b/docs/client/explanation/troubleshooting/what-is-patch-cut-off-date.md index 5d3c936..3a793c1 100644 --- a/docs/client/explanation/troubleshooting/what-is-patch-cut-off-date.md +++ b/docs/client/explanation/troubleshooting/what-is-patch-cut-off-date.md @@ -1,29 +1,28 @@ --- myst: html_meta: - description: "What is patch cut-off date? - learn about this topic in Livepatch client." + description: "Understand the patch cut-off date feature in Livepatch, including how it controls patch application, availability requirements, and security risk warnings." --- - (client-explanation-what-is-patch-cut-off-date)= -# What is patch cut-off date? +# Patch cut-off date -*Patch cut-off date* is a feature that allows you to set a time in the past, after which no patches will be applied to the system. This is useful for ensuring that the state of the system is deterministic and reproducible. It guarantees that no changes will be made after a certain date. +The patch cut-off date is a feature that allows you to set a point in time after which no patches will be applied to the system. This is useful for ensuring that the system state is deterministic and reproducible, guaranteeing that no changes occur after a specific date. -The use of patch cut-off date is recommended only for groups of systems that require a high level of uniformity, and synchronized updates. Delaying the application of high and critical security patches leaves the exploit window of a known vulnerability open, until the patch is applied. +The use of a patch cut-off date is recommended only for groups of systems that require a high level of uniformity and synchronized updates. Delaying the application of high and critical security patches leaves the exploit window of a known vulnerability open until the patch is applied. ## Availability -This feature is available only for users with a paid Ubuntu Pro subscription, or to public cloud customers running Ubuntu Pro images, which retrieve Livepatch patches from Canonical's hosted Livepatch service. This feature is not available for self-hosted Livepatch servers. +This feature is available only for users with a paid Ubuntu Pro subscription, or to public cloud customers running Ubuntu Pro images that retrieve Livepatch patches from Canonical's hosted Livepatch service. It is not available for self-hosted Livepatch Servers. -Livepatch Client version 10.11.2 or greater is required. +Livepatch Client version 10.11.2 or later is required. ## Excluded CVE fixes -Starting from Livepatch Client version 10.15.0, the verbose output will contain a warning message if the cut-off date blocked the latest patch. This message will contain the CVEs the machine is no longer protected against, along with the related LSN and LSN publish timestamp. +Starting from Livepatch Client version 10.15.0, verbose output includes a warning message if the cut-off date has blocked the latest patch. This message lists the CVEs the machine is no longer protected against, along with the related LSN and LSN publish timestamp. -An example of running `canonical-livepatch status –verbose` with an older patch: +Example output from running `canonical-livepatch status --verbose` with an older patch: ``` [!] KERNEL PATCHES BLOCKED: SECURITY RISK DETECTED @@ -51,11 +50,10 @@ UBUNTU-CVE-2024-53104 2025-03-26 09:20:22 +0000 UTC LSN-0110-1 UBUNTU-CVE-2024-53140 2025-03-26 09:20:22 +0000 UTC LSN-0110-1 UBUNTU-CVE-2024-56672 2025-03-26 09:20:22 +0000 UTC LSN-0110-1 UBUNTU-CVE-2025-0927 2025-03-26 09:20:22 +0000 UTC LSN-0110-1 - ``` -## What if I already have a patch applied? +## What happens if a patch has already been applied -If you already have a patch applied and its release date is after the cut-off date to fully remove the changes from your system, you will need to reboot the machine. +If you already have a patch applied and its release date is after the cut-off date, you must reboot the machine to fully remove the changes. -If you set a cut-off date and the release date of the patch is before the cut-off date, you are not required to take any action. The patch will remain applied. +If the patch release date is before the cut-off date, no action is required — the patch will remain applied. \ No newline at end of file diff --git a/docs/client/explanation/troubleshooting/why-are-there-missing-patches.md b/docs/client/explanation/troubleshooting/why-are-there-missing-patches.md index 8a35d37..954a037 100644 --- a/docs/client/explanation/troubleshooting/why-are-there-missing-patches.md +++ b/docs/client/explanation/troubleshooting/why-are-there-missing-patches.md @@ -1,14 +1,17 @@ --- myst: html_meta: - description: "Why are there missing patches? - learn about this topic in Livepatch client." + description: "Understand why live kernel patches may be missing for certain CVEs, including unsupported kernels, non-kernel vulnerabilities, and third-party driver limitations." --- - (client-explanation-why-was-there-no-livepatch-for-some-particular-high-or-critical-cve)= -# Why was there no livepatch for some particular high or critical CVE? +# Missing patches -Livepatches are only produced for [supported kernels](/client/reference/platform/supported-kernels.md), and only for CVEs that require a Linux kernel modification to fix the problem (for example, a CPU bug may not have a kernel fix). Further, livepatches do not address security problems in Ubuntu software packages, or in third-party drivers that do not ship as part of the Linux kernel (i.e. NVIDIA GPU drivers). +Live kernel patches are produced only for [supported kernels](/client/reference/platform/supported-kernels.md) and only for CVEs that require a Linux kernel modification to resolve the issue. The following scenarios may result in no live kernel patch being available: -Livepatch is intended to provide protection from security issues in *addition* to regular kernel security updates, so be sure to read and follow the security advisories published in Ubuntu Security Notifications ([USNs](https://ubuntu.com/security/notices)) for your kernel. +- The CVE does not have a kernel fix (for example, a CPU bug may not have a kernel-level fix). +- The security problem exists in Ubuntu software packages rather than the kernel. +- The vulnerability affects third-party drivers that do not ship as part of the Linux kernel (such as NVIDIA GPU drivers). + +Livepatch is intended to provide protection in addition to regular kernel security updates. Always read and follow the security advisories published in [Ubuntu Security Notices](https://ubuntu.com/security/notices) (USNs) for your kernel. \ No newline at end of file diff --git a/docs/client/explanation/troubleshooting/why-livepatch-is-not-working-on-my-machine.md b/docs/client/explanation/troubleshooting/why-livepatch-is-not-working-on-my-machine.md index 8bca7d4..6cd1019 100644 --- a/docs/client/explanation/troubleshooting/why-livepatch-is-not-working-on-my-machine.md +++ b/docs/client/explanation/troubleshooting/why-livepatch-is-not-working-on-my-machine.md @@ -1,59 +1,56 @@ --- myst: html_meta: - description: "Why Livepatch is not working on my machine? - learn about this topic in Livepatch client." + description: "Diagnose why Livepatch is not working, including unsupported kernels, HWE vs GA kernel differences, and Secure Boot key enrollment requirements." --- - (client-explanation-why-isnt-livepatch-working-on-my-machine)= -# Why isn’t Livepatch working on my machine?? +# Livepatch not working -## UNSUPPORTED KERNELS +This document explains common reasons why Livepatch may not function as expected and how to diagnose each situation. -Livepatch supports only kernels that have been released by the kernel team to the updates pocket, i.e. officially-released kernels acquired through APT using Canonical's repository for system updates, or Snap-based kernels released by Canonical to stable Snap channels. +## Unsupported kernels -While a livepatch *might* successfully apply to a kernel acquired from other sources, only certain kernels released by Canonical are supported. Kernels from other sources are not supported, including but not limited to: +Livepatch supports only kernels that have been released by the kernel team to the updates pocket — officially released kernels acquired through APT using Canonical's repository for system updates, or snap-based kernels released by Canonical to stable snap channels. -- kernels acquired from the development (proposed) kernel PPA -- kernels acquired from the kernel team's build PPA -- test kernels acquired from the kernel team's development PPAs -- personally-rebuilt kernels using the source debian package -- personally-rebuilt kernels using snapcraft -- kernels acquired from a Ubuntu-derived distribution +While a live kernel patch might successfully apply to a kernel from other sources, only certain kernels released by Canonical are supported. Kernels from the following sources are not supported: -Please be aware that while it may be possible to build a kernel with the same version markings as an officially-supported kernel, and to attempt to load a Canonical-generated livepatch into that kernel, it will likely not work, and can potentially crash your system or corrupt your data. +- Kernels acquired from the development (proposed) kernel PPA +- Kernels acquired from the kernel team's build PPA +- Test kernels acquired from the kernel team's development PPAs +- Personally rebuilt kernels using the source Debian package +- Personally rebuilt kernels using Snapcraft +- Kernels acquired from an Ubuntu-derived distribution -Also note that a kernel running unsigned, out-of-tree drivers will be tainted, and the kernel will refuse to apply livepatches in this state. +Building a kernel with the same version markings as an officially supported kernel and attempting to load a Canonical-generated live patch into it will likely not work, and can potentially crash your system or corrupt your data. -A full list of supported kernels is available [here](/client/reference/platform/supported-kernels.md). +Kernels running unsigned, out-of-tree drivers are tainted, and the kernel will refuse to apply live kernel patches in this state. -## HWE vs GA Kernels +A full list of supported kernels is available in the [Supported kernels reference](/client/reference/platform/supported-kernels.md). -Related to the above, detailing certain scenarios when a kernel may not be supported, it felt necessary to add a dedicated section on HWE (hardware enablement) versus GA (general availability) kernels. +## HWE vs GA kernels -Existing [blog posts](https://canonical.com/blog/canonical-livepatch-gets-even-better-now-supporting-hardware-enablement-kernels) and [official pages](https://ubuntu.com/kernel/variants) detail what exactly an HWE kernel is. Newer releases of LTS Ubuntu Desktop default to the HWE kernel, meaning your machine will be running a kernel version that will update alongside each Ubuntu release before settling on the kernel released alongside the next LTS. Ubuntu Server installs continue to remain on the GA kernel. +Livepatch support differs between Hardware Enablement (HWE) and General Availability (GA) kernels. -While Livepatch supports the GA kernel and the HWE that you eventually settle on alongside the next LTS, it does not completely support the interim kernels that are released every 6 months. This is why you might see your machine running an LTS Ubuntu Desktop release, but still encounter Livepatch messaging saying your kernel is not supported. +Newer releases of LTS Ubuntu Desktop default to the HWE kernel, meaning your machine runs a kernel version that updates alongside each Ubuntu release before settling on the kernel released with the next LTS. Ubuntu Server installations remain on the GA kernel. For more details on HWE kernels, see the [Canonical blog](https://canonical.com/blog/canonical-livepatch-gets-even-better-now-supporting-hardware-enablement-kernels) and [Ubuntu kernel variants page](https://ubuntu.com/kernel/variants). -It is possible to switch from an HWE kernel to the GA if desired by following the instructions [here](https://wiki.ubuntu.com/Kernel/LTSEnablementStack). One should take care to backup data and other important information before making such system level changes. +Livepatch supports the GA kernel and the HWE kernel that you settle on with the next LTS. It does not fully support the interim kernels released every 6 months. This is why a machine running an LTS Ubuntu Desktop release may still display Livepatch messaging indicating that the kernel is not supported. -Finally, while prior to Ubuntu 22.04, Livepatch offered no support for interim kernel versions, recently Livepatch has grown support for some flavours of interim HWE kernels as described in our [blog post](https://ubuntu.com/blog/canonical-livepatch-gets-even-better-now-supporting-hardware-enablement-kernels). Kernels for desktop users are the "generic" flavour, while kernels for public clouds have their own unique flavours, supporting cloud specific functionality. Livepatch is now supported on interim HWE kernels for various public cloud flavours. Check your kernel flavour with `uname -r`. +You can switch from an HWE kernel to the GA kernel by following the [LTS Enablement Stack instructions](https://wiki.ubuntu.com/Kernel/LTSEnablementStack). Back up your data and important information before making system-level changes. -As above, a full list of GA and HWE kernels supported is available [here](/client/reference/platform/supported-kernels.md) +Prior to Ubuntu 22.04 LTS, Livepatch offered no support for interim kernel versions. Livepatch has since added support for some flavours of interim HWE kernels. Desktop user kernels are the "generic" flavour, while public cloud kernels have their own unique flavours supporting cloud-specific functionality. Livepatch is now supported on interim HWE kernels for various public cloud flavours. Check your kernel flavour with `uname -r`. -## SECUREBOOT +A full list of GA and HWE supported kernels is available in the [Supported kernels reference](/client/reference/platform/supported-kernels.md). -If you are using secure boot with a kernel older than April 1 2021, you will also need to import the livepatch public keys into your keyring. If your kernel is newer, there is no need to import keys as the key is included in the kernel, but doing so will not cause any harm. +## Secure Boot -Use the following command to import the livepatch key: +If you are using Secure Boot with a kernel older than April 1, 2021, you must import the Livepatch public keys into your keyring. For newer kernels, the key is already included, and no import is necessary (though importing will not cause harm). -``` +To import the Livepatch key: +``` sudo mokutil --import /snap/canonical-livepatch/current/keys/livepatch-kmod.x509 - ``` -After this enter a password if necessary for MOK, then reboot. - -Your BIOS will then guide you through enrolling a new key in MOK. At this point you will be able to verify the module signatures. +Enter a password if prompted by MOK, then reboot. Your BIOS will guide you through enrolling the new key in MOK. After enrollment, you can verify the module signatures. \ No newline at end of file diff --git a/docs/client/how-to-guides/configuration/configure-livepatch-client.md b/docs/client/how-to-guides/configuration/configure-livepatch-client.md index 9598a3a..af51272 100644 --- a/docs/client/how-to-guides/configuration/configure-livepatch-client.md +++ b/docs/client/how-to-guides/configuration/configure-livepatch-client.md @@ -1,17 +1,17 @@ --- myst: html_meta: - description: "How to configure livepatch client with Livepatch client." + description: "How to configure the Livepatch Client." --- (client-how-to-guides-how-to-configure-the-livepatch-client)= -# How to configure the Livepatch client +# How to configure the Livepatch Client -Livepatch client can be configured using the CLI or its configuration file at `/var/snap/canonical-livepatch/common/config`. +The Livepatch Client can be configured using the CLI or its configuration file at `/var/snap/canonical-livepatch/common/config`. -## CLI Configuration +## CLI configuration Show the current configuration: @@ -38,9 +38,9 @@ Change settings, reading a long, multi-line value from stdin: canonical-livepatch config remote-server=https://2.3.4.5 ca-certs=@stdin < chain.pem ``` -## YAML Configuration +## YAML configuration -Livepatch client can also be configured by editing `/var/snap/canonical-livepatch/common/config`. The file is YAML-formatted. In order for changes to the file to take affect you must restart the daemon: +The Livepatch Client can also be configured by editing `/var/snap/canonical-livepatch/common/config`. The file is YAML-formatted. For changes to the file to take effect, restart the daemon: ``` sudo snap restart canonical-livepatch diff --git a/docs/client/how-to-guides/configuration/configure-proxy.md b/docs/client/how-to-guides/configuration/configure-proxy.md index 8ec81a0..bb5146a 100644 --- a/docs/client/how-to-guides/configuration/configure-proxy.md +++ b/docs/client/how-to-guides/configuration/configure-proxy.md @@ -1,18 +1,19 @@ --- myst: html_meta: - description: "How to configure proxy with Livepatch client." + description: "How to configure proxy with Livepatch Client." --- + (client-how-to-guides-how-to-configure-a-proxy-in-the-livepatch-client)= -# How to configure a proxy in the Livepatch client +# How to configure a proxy in the Livepatch Client -Livepatch client users have the option to communicate with the Livepatch server through a proxy. Livepatch supports communicating through HTTP, HTTPS, or SOCKS5 proxies. To do so, there are a few configuration parameters that should be assigned. +The Livepatch Client supports communicating with the Livepatch Server through HTTP, HTTPS, or SOCKS5 proxies. Several configuration parameters control this behaviour. ## Check proxy configuration -To check the proxy configuration of the Livepatch client, run the following command: +To check the proxy configuration of the Livepatch Client, run the following command: ```bash canonical-livepatch config @@ -23,36 +24,36 @@ ca-certs: "" ... ``` -Note that an empty string value (“”) means the corresponding parameter is not set and system defaults will be used. +An empty string value (`""`) means the corresponding parameter is not set and system defaults are used. -## Using an HTTP/SOCKS5 proxy +## Use an HTTP proxy or SOCKS5 proxy -To enable the usage of an HTTP proxy, run the following commands: +To enable an HTTP proxy, run the following commands: ```bash sudo canonical-livepatch config http-proxy=http://proxy.example.com sudo canonical-livepatch config https-proxy=http://proxy.example.com ``` -Users can also configure the Livepatch client to use a SOCKS5 proxy by running these commands: +To configure a SOCKS5 proxy, run these commands: ```bash sudo canonical-livepatch config http-proxy=socks5://proxy.example.com:1080 sudo canonical-livepatch config https-proxy=socks5://proxy.example.com:1080 ``` -Although the client respects the standard Linux environment variables used for proxy setup (i.e., `HTTP_PROXY`, `HTTPS_PROXY` or `NO_PROXY`), please note that for them to take effect, they should be set in the Livepatch client daemon process environment. Therefore, it is more straightforward for users to use the above configuration parameters. +The client respects the standard Linux environment variables for proxy setup (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`). However, these variables must be set in the Livepatch Client daemon process environment to take effect. Using the configuration parameters above is the recommended approach. -## Using an HTTPS proxy +## Use an HTTPS proxy -When using an HTTPS proxy (not to be confused with proxying HTTPS requests), users need to make sure they are including `https://` scheme when setting the above configuration parameters: +When using an HTTPS proxy (not to be confused with proxying HTTPS requests), include the `https://` scheme when setting the configuration parameters: ```bash sudo canonical-livepatch config http-proxy=https://proxy.example.com sudo canonical-livepatch config https-proxy=https://proxy.example.com ``` -If a self-signed CA certificate is included in the HTTPS proxy’s TLS certificate chain, the user should add the CA certificate to the trusted certificates on the host machine by running the following commands (assuming `ca.crt` is the CA certificate file): +If a self-signed CA certificate is included in the HTTPS proxy's TLS certificate chain, add the CA certificate to the trusted certificates on the host machine. Run the following commands (assuming `ca.crt` is the CA certificate file): ```bash sudo apt-get install ca-certificates @@ -60,15 +61,15 @@ sudo cp ca.crt /usr/share/ca-certificates sudo dpkg-reconfigure ca-certificates ``` -However, if a user does not want to install a self-signed CA certificate as a system-wide trusted one, they can explicitly instruct Livepatch client to trust the CA certificate: +To trust a self-signed CA certificate without installing it system-wide, explicitly instruct the Livepatch Client to trust the CA certificate: ```bash sudo canonical-livepatch config ca-certs=@stdin < ca.crt ``` -## Routing directly to Livepatch server +## Route directly to the Livepatch Server -If there is already a system-wide proxy set up (e.g., by `HTTP_PROXY` environment variable), the users can escape it for communication with the Livepatch server by using the following configuration: +If a system-wide proxy is already configured (for example, through the `HTTP_PROXY` environment variable), bypass it for communication with the Livepatch Server using the following configuration: ```bash sudo canonical-livepatch config no-proxy=canonical.com diff --git a/docs/client/how-to-guides/configuration/enable-and-configure-the-livepatch-client-with-cloud-init.md b/docs/client/how-to-guides/configuration/enable-and-configure-the-livepatch-client-with-cloud-init.md index 1073fc3..2a5c0fe 100644 --- a/docs/client/how-to-guides/configuration/enable-and-configure-the-livepatch-client-with-cloud-init.md +++ b/docs/client/how-to-guides/configuration/enable-and-configure-the-livepatch-client-with-cloud-init.md @@ -1,19 +1,19 @@ --- myst: html_meta: - description: "How to enable and configure the livepatch client with cloud-init with Livepatch client." + description: "How to enable and configure the Livepatch Client with cloud-init" --- (client-how-to-guides-how-to-enable-and-configure-the-livepatch-client-with-cloud-init)= -# How to enable and configure the Livepatch client with cloud-init +# How to enable and configure the Livepatch Client with cloud-init -This guide walks through how to enable and configure the Livepatch client with [cloud-init](https://docs.cloud-init.io/en/latest/). Livepatch client supports cloud-init for communicating with the Canonical-hosted Livepatch server, and for an on-prem Livepatch server. +This guide describes how to enable and configure the Livepatch Client with [cloud-init](https://docs.cloud-init.io/en/latest/). The Livepatch Client supports cloud-init for communicating with the Canonical-hosted Livepatch Server and with an on-premises Livepatch Server. -## Using The Client With The Hosted Livepatch Server +## Use the client with the hosted Livepatch Server -When using the Livepatch client with the Canonical-hosted Livepatch server (the default configuration), you can use the following template cloud-init module: +When using the Livepatch Client with the Canonical-hosted Livepatch Server (the default configuration), use the following template cloud-init module: ```yaml #cloud-config @@ -60,19 +60,19 @@ runcmd: snap restart canonical-livepatch - | rm /etc/livepatch/* -final_message: The system is up, up to date, and Livepatch client is active after $UPTIME seconds +final_message: The system is up, up to date, and Livepatch Client is active after $UPTIME seconds ``` -To configure the Livepatch client through the cloud-init module, replace each template value in the write_files section for `/etc/livepatch/livepatch.env`, such as `__LOG_LEVEL__`, with a valid configuration based on the [available configuration options](/client/reference/platform/configuration-options.md). +To configure the Livepatch Client through the cloud-init module, replace each template value in the `write_files` section for `/etc/livepatch/livepatch.env`, such as `__LOG_LEVEL__`, with a valid configuration based on the [available configuration options](/client/reference/platform/configuration-options.md). -> Note: To enable Livepatch, you need to attach the instance to Ubuntu Pro. Do not write the Pro token into the cloud-init module. Instead, store the pro token in a secrets vault, and access the pro token from the vault, writing the token into a root-owned file at`/etc/livepatch/pro_token`. The cloud-init module reads from this file to attach to Ubuntu Pro. The file is deleted at the last step of the cloud-init setup process. +> Note: To enable Livepatch, attach the instance to Ubuntu Pro. Do not write the Pro token into the cloud-init module. Instead, store the Pro token in a secrets vault, and access the Pro token from the vault, writing the token into a root-owned file at `/etc/livepatch/pro_token`. The cloud-init module reads from this file to attach to Ubuntu Pro. The file is deleted at the last step of the cloud-init setup process. -For any configuration values you do not wish to change, remove them from the `canonical-livepatch config` statement in the second block of commands. +Any configuration values that do not require changes should be removed from the `canonical-livepatch config` statement in the second block of commands. -## Using The Client With An On-Prem Livepatch Server +## Use the client with an on-premises Livepatch Server -The cloud-init module for using the client with an on-prem Livepatch server is similar to the previous module; instead of the Pro token, you use an auth token generated by the admin tool: +The cloud-init module for using the client with an on-premises Livepatch Server is similar to the previous module. Instead of the Pro token, use an auth token generated by the admin tool: ```bash canonical-livepatch-server-admin.livepatch-admin auth-token [flags] @@ -84,9 +84,9 @@ For example: canonical-livepatch-server-admin.livepatch-admin auth-token test edge ``` -This command will output an auth token you can use with your client machines to apply patches in the `edge` tier. +This command outputs an auth token that can be used with client machines to apply patches in the `edge` tier. -The following cloud-init module should be used for client machines with an on-prem server: +The following cloud-init module is used for client machines with an on-premises server: ```yaml #cloud-config @@ -135,11 +135,11 @@ runcmd: canonical-livepatch enable $(cat /etc/livepatch/authToken) - | rm /etc/livepatch/* -final_message: The system is up, up to date, and Livepatch client is active after $UPTIME seconds +final_message: The system is up, up to date, and Livepatch Client is active after $UPTIME seconds ``` -Similar to the previous cloud-init module, any configuration values you do not wish to change should be removed from the canonical-livepatch config statement in the second block of commands. +Similar to the previous cloud-init module, any configuration values that do not require changes should be removed from the `canonical-livepatch config` statement in the second block of commands. -> Note: To enable Livepatch with an on-prem Livepatch server, you need to attach the instance with an auth token. Do not write the auth token into the cloud-init module. Instead, store the auth token in a secrets vault, and redirect to `/etc/livepatch/authToken`. -> -> Be sure to set the `__SERVER_URL__` variable to the URL of your Livepatch on-prem server. +> Note: To enable Livepatch with an on-premises Livepatch Server, attach the instance with an auth token. Do not write the auth token into the cloud-init module. Instead, store the auth token in a secrets vault, and redirect to `/etc/livepatch/authToken`. +> +> Set the `__SERVER_URL__` variable to the URL of the on-premises Livepatch Server. diff --git a/docs/client/how-to-guides/configuration/index.md b/docs/client/how-to-guides/configuration/index.md index 039e22c..f4d787a 100644 --- a/docs/client/how-to-guides/configuration/index.md +++ b/docs/client/how-to-guides/configuration/index.md @@ -13,18 +13,18 @@ Configure the client, proxies, cloud-init, and patch cut-off behaviour. ## In this section -- [Configure Livepatch client](/client/how-to-guides/configuration/configure-livepatch-client.md) -- [Configure 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 patch cut-off date](/client/how-to-guides/configuration/use-patch-cut-off-date.md) +* [Configure the Livepatch Client](/client/how-to-guides/configuration/configure-livepatch-client.md) +* [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) ```{toctree} :titlesonly: :maxdepth: 1 :hidden: -Configure livepatch client +Configure Livepatch Client Configure proxy -Enable and configure the livepatch client with cloud init +Enable and configure the Livepatch Client with cloud init Use patch cut off date ``` diff --git a/docs/client/how-to-guides/configuration/use-patch-cut-off-date.md b/docs/client/how-to-guides/configuration/use-patch-cut-off-date.md index 7e15924..a5c8df3 100644 --- a/docs/client/how-to-guides/configuration/use-patch-cut-off-date.md +++ b/docs/client/how-to-guides/configuration/use-patch-cut-off-date.md @@ -1,7 +1,7 @@ --- myst: html_meta: - description: "How to use patch cut-off date with Livepatch client." + description: "How to use patch cut-off date with Livepatch Client." --- @@ -9,9 +9,9 @@ myst: # How to use a patch cut-off date -See our [explanation](/client/explanation/troubleshooting/what-is-patch-cut-off-date.md) to understand the patch cut-off date feature. +See the [explanation](/client/explanation/troubleshooting/what-is-patch-cut-off-date.md) to understand the patch cut-off date feature. -## Checking the cut-off date +## Check the cut-off date To check the cut-off date, run the following command: @@ -23,7 +23,7 @@ sudo canonical-livepatch config cutoff-date --format json {"cutoff-date": "2024-02-01T00:00:00Z"} ``` -## Enabling or disabling the cut-off date +## Enable or disable the cut-off date To enable the cut-off date, run the following command: @@ -31,7 +31,7 @@ To enable the cut-off date, run the following command: sudo canonical-livepatch config cutoff-date="2024-10-01T12:00:00Z" ``` -The argument to `cutoff-date` should be in the RFC3339 format. Only times in the past can be set as the cut-off date. +The argument to `cutoff-date` must be in RFC3339 format. Only times in the past can be set as the cut-off date. To disable the cut-off date, run the following command: diff --git a/docs/client/how-to-guides/index.md b/docs/client/how-to-guides/index.md index 3245603..86c89c4 100644 --- a/docs/client/how-to-guides/index.md +++ b/docs/client/how-to-guides/index.md @@ -1,22 +1,22 @@ --- myst: html_meta: - description: "How-to guides with Livepatch client." + description: "How-to guides with Livepatch Client." --- (client-how-to-guides)= -# How-To-Guides +# How-to guides Step-by-step guides covering key operations and common tasks related to Livepatch. ## In this section -- [Installation](/client/how-to-guides/installation/index.md) — Enable or disable the Livepatch client on your machines. -- [Configuration](/client/how-to-guides/configuration/index.md) — Configure the client, proxies, cloud-init, and patch cut-off behaviour. -- [Operations](/client/how-to-guides/operations/index.md) — Day-to-day operation of the Livepatch client. -- [Security](/client/how-to-guides/security/index.md) — Operate and decommission the client securely, and report vulnerabilities. +* [Installation](/client/how-to-guides/installation/index.md): Enable or disable the Livepatch Client on machines. +* [Configuration](/client/how-to-guides/configuration/index.md): Configure the client, proxies, cloud-init, and patch cut-off behaviour. +* [Operations](/client/how-to-guides/operations/index.md): Day-to-day operation of the Livepatch Client. +* [Security](/client/how-to-guides/security/index.md): Operate and decommission the client securely, and report vulnerabilities. ```{toctree} :titlesonly: diff --git a/docs/client/how-to-guides/installation/disable-client.md b/docs/client/how-to-guides/installation/disable-client.md index 543a38c..c2ccfea 100644 --- a/docs/client/how-to-guides/installation/disable-client.md +++ b/docs/client/how-to-guides/installation/disable-client.md @@ -1,31 +1,32 @@ --- myst: html_meta: - description: "How to disable client with Livepatch client." + description: "How to disable client with Livepatch Client." --- + (client-how-to-guides-how-to-disable-the-livepatch-client)= -# How to disable the Livepatch client +# How to disable the Livepatch Client -In case the livepatch client needs to be disabled, there are several ways of approaching this. +Several methods are available to disable the Livepatch Client. -If you have access to the system, one way is to disable the livepatch service: +When direct access to the system is available, disable the Livepatch service: ``` sudo snap stop --disable canonical-livepatch ``` -If direct access to the system is not available, livepatch client can be disabled in two ways: +When direct access to the system is not available, the Livepatch Client can be disabled in two ways: -- by setting a kernel command line parameter `canonical_livepatch_mode` -- by writing the mode to the `/var/local/canonical_livepatch_mode` file +* Set a kernel command line parameter `canonical_livepatch_mode` +* Write the mode to the `/var/local/canonical_livepatch_mode` file -These two locations are only checked when the livepatch daemon is started (usually at boot). +These two locations are checked only when the Livepatch daemon is started, typically at boot. The mode value can be: -- `normal` - the default operation mode, patch information is refreshed regularly and new patches are applied. -- `no-apply` - patch information is refreshed, but new patches are not applied to the kernel. -- `no-refresh` - patch information is not refreshed. -- `stop` - the livepatch daemon will not start. +* `normal`: The default operation mode. Patch information is refreshed regularly and new patches are applied. +* `no-apply`: Patch information is refreshed, but new patches are not applied to the kernel. +* `no-refresh`: Patch information is not refreshed. +* `stop`: The Livepatch daemon does not start. diff --git a/docs/client/how-to-guides/installation/disable-livepatch-during-startup.md b/docs/client/how-to-guides/installation/disable-livepatch-during-startup.md index 67d21f8..5fc6546 100644 --- a/docs/client/how-to-guides/installation/disable-livepatch-during-startup.md +++ b/docs/client/how-to-guides/installation/disable-livepatch-during-startup.md @@ -1,7 +1,7 @@ --- myst: html_meta: - description: "How to disable livepatch during startup with Livepatch client." + description: "How to disable Livepatch during startup." --- @@ -9,51 +9,51 @@ myst: # How to disable Livepatch during startup -The Livepatch client will make a best-effort attempt to [prevent re-inserting and reloading a faulty patch](/client/explanation/patches/patch-installation.md) that causes a system crash or causes kernel bug log entries. In the extremely rare case that a faulty patch causes a system crash loop, recovery methods are available to disable the Livepatch daemon, thereby preventing the application of the faulty patch. The following methods explain how to recover the system in such scenarios. These recovery methods rely on setting different values for the [Livepatch mode](/client/how-to-guides/installation/disable-client.md). +The Livepatch Client makes a best-effort attempt to [prevent re-inserting and reloading a faulty patch](/client/explanation/patches/patch-installation.md) that causes a system crash or kernel bug log entries. In the extremely rare case that a faulty patch causes a system crash loop, recovery methods are available to disable the Livepatch daemon, thereby preventing the application of the faulty patch. The following methods explain how to recover the system in such scenarios. These recovery methods rely on setting different values for the [Livepatch mode](/client/how-to-guides/installation/disable-client.md). -## Various ways to disable Livepatch +## Disable Livepatch using the kernel command line -1. **Using the kernel command-line** +1. If the faulty patch is causing a system crash and reboot loop, enter the GRUB boot menu during the boot process. +2. Edit the boot options for the kernel being booted and add `canonical_livepatch_mode=stop` to the kernel command line, to prevent the Livepatch daemon from starting. +3. Alternatively, add `canonical_livepatch_mode=no-apply` to the kernel command line. This mode enables the Livepatch Client and daemon and refreshes the patch information, but the patch is never applied to the kernel. -- If the faulty patch is causing a system crash and reboot loop, enter the GRUB boot menu during the boot process. -- Edit the boot options for the kernel you are booting into and add `canonical_livepatch_mode=stop` to the kernel command-line, to prevent the Livepatch daemon from starting up. -- Alternatively, you can add `canonical_livepatch_mode=no-apply` to the kernel command-line. This mode enables the Livepatch client and daemon and refreshes the patch information, but the patch is never applied to the kernel. -- The limitation of solely relying on this recovery method is that the Livepatch mode is not permanent. On a reboot, the Livepatch mode reverts to `normal`. This will start up the Livepatch daemon and apply the faulty patch to the kernel. +The limitation of relying solely on this recovery method is that the Livepatch mode is not permanent. On a reboot, the Livepatch mode reverts to `normal`. This starts the Livepatch daemon and applies the faulty patch to the kernel. -2. **Using the `/var/local/canonical_livepatch_mode` file** +## Disable Livepatch using the mode file -- To ensure that the Livepatch mode persists across reboots and prevents patch application, the mode string can be written to the `/var/local/canonical_livepatch_mode` file. For example, to stop the Livepatch daemon from starting up on system initialization, the Livepatch mode `stop` can be written to the file as follows: +To ensure that the Livepatch mode persists across reboots and prevents patch application, write the mode string to the `/var/local/canonical_livepatch_mode` file. For example, to stop the Livepatch daemon from starting on system initialization, write the Livepatch mode `stop` to the file: ```shell sudo bash -c 'echo -n stop > /var/local/canonical_livepatch_mode' ``` -- The Livepatch mode can also be written to the `/var/local/canonical_livepatch_mode` file during the boot process, to disable the Livepatch client and daemon. - - Boot into recovery mode for the kernel, get access to the root shell and execute the command shown above. Once the Livepatch mode has been written to the file, continue the normal boot process. - - Boot into rescue mode by adding `systemd.unit=rescue.target` in the kernel command-line, which gives full access to the root user and local file systems. On getting access to the shell as the root user, execute the command shown above and then continue the normal boot process. +The Livepatch mode can also be written to the `/var/local/canonical_livepatch_mode` file during the boot process, to disable the Livepatch Client and daemon: -## Resume the normal operation of Livepatch +* Boot into recovery mode for the kernel, get access to the root shell, and execute the command shown above. Once the Livepatch mode has been written to the file, continue the normal boot process. +* Boot into rescue mode by adding `systemd.unit=rescue.target` to the kernel command line, which gives full access to the root user and local file systems. On gaining access to the shell as the root user, execute the command shown above and then continue the normal boot process. -After recovering from the crash loop, resuming the normal operation of the Livepatch client and daemon is necessary to secure the running kernel. However, we need to ensure that enabling Livepatch does not result in a crash loop again. +## Resume normal operation of Livepatch -- The Livepatch client sends anonymous pings before, during and after a patch is applied, to the Livepatch server. The client pings are continuously [monitored by the Livepatch team](/client/explanation/patches/patch-lifecycle.md) to ensure the sanity of the patches. If the analysis of the ping metrics points towards a patch being faulty, it is [blocklisted](/client/explanation/patches/patch-lifecycle.md) to prevent it from being served to client machines. -- Users can also [report bugs](https://bugs.launchpad.net/canonical-livepatch-client) upon facing a system crash loop that could be caused by the application of a patch. If the patch is found to be faulty by the Livepatch team, it will be blocklisted. -- After the faulty patch is blocklisted or a new and stable patch is released, it is safe to resume the normal operation of the Livepatch client. +After recovering from the crash loop, resume the normal operation of the Livepatch Client and daemon to secure the running kernel. Ensure that enabling Livepatch does not result in a crash loop again. -The process to resume the normal operation of Livepatch depends on the recovery method used. +* The Livepatch Client sends anonymous pings before, during, and after a patch is applied to the Livepatch Server. The client pings are continuously [monitored by the Livepatch team](/client/explanation/patches/patch-lifecycle.md) to ensure the sanity of the patches. If the analysis of the ping metrics points towards a patch being faulty, it is [blocklisted](/client/explanation/patches/patch-lifecycle.md) to prevent it from being served to client machines. +* [Report bugs](https://bugs.launchpad.net/canonical-livepatch-client) upon encountering a system crash loop that could be caused by the application of a patch. If the patch is found to be faulty by the Livepatch team, it is blocklisted. +* After the faulty patch is blocklisted or a new and stable patch is released, it is safe to resume the normal operation of the Livepatch Client. -- When the kernel command-line parameter `canonical_livepatch_mode=` is used for recovery, the only way to resume normal operation is to reboot the system. -- If recovery is done by writing a Livepatch mode into the `/var/local/canonical_livepatch_mode` file, the first step to resume normal operation would be to change the mode to `normal` or delete the file. Then, run the command `sudo snap restart canonical-livepatch`. +The process to resume normal operation depends on the recovery method used: -## Enable Livepatch with a cutoff-date to withhold one or more LSNs +* When the kernel command line parameter `canonical_livepatch_mode=` is used for recovery, the only way to resume normal operation is to reboot the system. +* If recovery is done by writing a Livepatch mode into the `/var/local/canonical_livepatch_mode` file, change the mode to `normal` or delete the file. Then, run `sudo snap restart canonical-livepatch`. -The process of reporting, blocklisting, and releasing a replacement Livepatch takes time. If installing a kernel package update is not possible, it is possible to exclude one or more LSNs by enabling Livepatch with a cutoff date. The `cutoff-date` configuration option available in the Livepatch client can be used to selectively apply some LSNs to a kernel, and selectively omit one or more newer LSNs. The `cutoff-date` config option allows users to set a date in the past, and only patches released before this `cutoff-date` will be applied to the kernel. This will allow users to apply the desired LSNs to the kernel, and omit certain LSNs by date. The following steps outline how this can be accomplished: +## Enable Livepatch with a cutoff date to withhold one or more LSNs -1. If the current Livepatch mode in the `/var/local/canonical_livepatch_mode` file is `stop` and the Livepatch daemon is not running, we cannot make any configuration changes. -2. Set the Livepatch mode to `no-apply` using `sudo bash -c 'echo -n no-apply > /var/local/canonical_livepatch_mode'` -3. Run `sudo snap restart canonical-livepatch`. This should enable the Livepatch daemon. The daemon will refresh patch information but never apply the patch to the kernel in this mode. -4. Once the daemon is enabled, set the `cutoff-date` configuration option to a date before the faulty patch was released. For example, `sudo canonical-livepatch config cutoff-date=2024-01-01T01:00:00Z`. The release date for the problematic LSN can be found [here](https://ubuntu.com/security/notices?details=lsn). +The process of reporting, blocklisting, and releasing a replacement Livepatch takes time. If installing a kernel package update is not possible, exclude one or more LSNs by enabling Livepatch with a cutoff date. The `cutoff-date` configuration option available in the Livepatch Client can be used to selectively apply some LSNs to a kernel, and selectively omit one or more newer LSNs. The `cutoff-date` config option allows setting a date in the past, and only patches released before this `cutoff-date` are applied to the kernel. This allows applying the desired LSNs to the kernel, and omitting certain LSNs by date. The following steps outline how to accomplish this: + +1. If the current Livepatch mode in the `/var/local/canonical_livepatch_mode` file is `stop` and the Livepatch daemon is not running, no configuration changes can be made. +2. Set the Livepatch mode to `no-apply` using `sudo bash -c 'echo -n no-apply > /var/local/canonical_livepatch_mode'`. +3. Run `sudo snap restart canonical-livepatch`. This enables the Livepatch daemon. The daemon refreshes patch information but never applies the patch to the kernel in this mode. +4. Once the daemon is enabled, set the `cutoff-date` configuration option to a date before the faulty patch was released. For example, `sudo canonical-livepatch config cutoff-date=2024-01-01T01:00:00Z`. The release date for the problematic LSN can be found on the [Ubuntu Security Notices page](https://ubuntu.com/security/notices?details=lsn). 5. Set the Livepatch mode to `normal` or delete the Livepatch mode file. -6. Run `sudo snap restart canonical-livepatch`. This should enable the full operation of the Livepatch daemon. The daemon will get the most recent stable patch version due to the `cutoff-date` config option and apply it to the running kernel. +6. Run `sudo snap restart canonical-livepatch`. This enables the full operation of the Livepatch daemon. The daemon retrieves the most recent stable patch version due to the `cutoff-date` config option and applies it to the running kernel. -This process improves kernel security until a new and stable Livepatch is released for the kernel, at which point the cutoff-date configuration option can be disabled or changed to get the most recent Livepatch. +This process improves kernel security until a new and stable Livepatch is released for the kernel, at which point the `cutoff-date` configuration option can be disabled or changed to retrieve the most recent Livepatch. \ No newline at end of file diff --git a/docs/client/how-to-guides/installation/enable-client-on-ubuntu-core.md b/docs/client/how-to-guides/installation/enable-client-on-ubuntu-core.md index 93db581..c990bc0 100644 --- a/docs/client/how-to-guides/installation/enable-client-on-ubuntu-core.md +++ b/docs/client/how-to-guides/installation/enable-client-on-ubuntu-core.md @@ -1,54 +1,54 @@ --- myst: html_meta: - description: "How to enable client on ubuntu core with Livepatch client." + description: "How to enable client on ubuntu core with Livepatch Client." --- (client-how-to-guides-how-to-enable-the-livepatch-client-on-ubuntu-core)= -# How to enable the Livepatch client on Ubuntu Core +# How to enable the Livepatch Client on Ubuntu Core -Canonical Livepatch supports live kernel patching on Ubuntu Core machines. Livepatch is supported on Core20+ for amd64 and Core26+ for arm64 architectures. Canonical Livepatch is typically enabled using the Pro Client on classic Ubuntu machines. The Pro Client is not available for install on Ubuntu Core machines, therefore users must enable Livepatch client directly. To do so, follow these steps on the Ubuntu Core machine: +Canonical Livepatch supports live kernel patching on Ubuntu Core machines. Livepatch is supported on Core20+ for amd64 and Core26+ for arm64 architectures. Canonical Livepatch is typically enabled using the Pro Client on classic Ubuntu machines. The Pro Client is not available for installation on Ubuntu Core machines, so the Livepatch Client must be enabled directly. Follow these steps on the Ubuntu Core machine: -1. Install canonical-livepatch: +1. Install `canonical-livepatch`: -```shell -sudo snap install canonical-livepatch -``` + ```shell + sudo snap install canonical-livepatch + ``` -2. Install jq and curl +2. Install `jq` and `curl`: -```shell -sudo snap install jq curl -``` + ```shell + sudo snap install jq curl + ``` -3. Obtain a contract resource token using the Ubuntu Pro token from [ubuntu.com/pro](http://ubuntu.com/pro) dashboard. +3. Obtain a contract resource token using the Ubuntu Pro token from the [ubuntu.com/pro](http://ubuntu.com/pro) dashboard. -```shell -export pro_token= + ```shell + export pro_token= -body="{\"architecture\":\"$(uname -m)\", \"hostType\":\"physical\", \"machineId\":\"$(cat /etc/machine-id)\", \"os\":{\"distribution\":\"$(. /etc/os-release && echo $PRETTY_NAME)\", \"kernel\":\"$(uname -r)\", \"release\":\"$(. /etc/os-release && echo $VERSION_ID)\", \"series\":\"core$(. /etc/os-release && echo $VERSION_ID)\", \"type\":\"Linux\"}}" && curl -X POST -H "Authorization: Bearer $pro_token" -H "Content-Type: application/json" https://contracts.canonical.com/v1/context/machines/token -d "$body" | jq '.resourceTokens | map(select(.type=="livepatch"))' + body="{\"architecture\":\"$(uname -m)\", \"hostType\":\"physical\", \"machineId\":\"$(cat /etc/machine-id)\", \"os\":{\"distribution\":\"$(. /etc/os-release && echo $PRETTY_NAME)\", \"kernel\":\"$(uname -r)\", \"release\":\"$(. /etc/os-release && echo $VERSION_ID)\", \"series\":\"core$(. /etc/os-release && echo $VERSION_ID)\", \"type\":\"Linux\"}}" && curl -X POST -H "Authorization: Bearer $pro_token" -H "Content-Type: application/json" https://contracts.canonical.com/v1/context/machines/token -d "$body" | jq '.resourceTokens | map(select(.type=="livepatch"))' -``` + ``` -**Note:** Replace with your Ubuntu Pro token obtained for [ubuntu.com/pro](http://ubuntu.com/pro) dashboard. + Replace `` with the Ubuntu Pro token obtained from the [ubuntu.com/pro](http://ubuntu.com/pro) dashboard. -You should see the following output: + The following output is expected: -```json -[ - { - "token": "", - "type": "livepatch" - } -] -``` + ```json + [ + { + "token": "", + "type": "livepatch" + } + ] + ``` -4. Enable Livepatch client using the \ from the previous step. +4. Enable the Livepatch Client using the `` from the previous step: -``` -sudo canonical-livepatch enable -``` + ``` + sudo canonical-livepatch enable + ``` -At this point, the Canonical Livepatch client has been enabled on your Ubuntu Core machine. +At this point, the Canonical Livepatch Client is enabled on the Ubuntu Core machine. \ No newline at end of file diff --git a/docs/client/how-to-guides/installation/enable-client.md b/docs/client/how-to-guides/installation/enable-client.md index def7cb9..3426c2a 100644 --- a/docs/client/how-to-guides/installation/enable-client.md +++ b/docs/client/how-to-guides/installation/enable-client.md @@ -1,15 +1,15 @@ --- myst: html_meta: - description: "How to enable client with Livepatch client." + description: "How to enable client with Livepatch Client." --- (client-how-to-guides-how-to-enable-the-livepatch-client)= -# How to enable the Livepatch client +# How to enable the Livepatch Client -Livepatch is included in Ubuntu Pro (previously known as Ubuntu Advantage). The recommended way to install it is using the Ubuntu Pro client. The instructions below show how to enable livepatching and install the client. Instructions can also be found in [this tutorial](https://ubuntu.com/tutorials/enable-the-livepatch-service#1-overview). +Livepatch is included in Ubuntu Pro (previously known as Ubuntu Advantage). The recommended way to install it is using the Ubuntu Pro client. The following commands enable live kernel patching and install the Livepatch Client. See also [this tutorial](https://ubuntu.com/tutorials/enable-the-livepatch-service#1-overview). ``` # Attach your personal or enterprise subscription from ubuntu.com/pro @@ -19,4 +19,4 @@ sudo pro attach sudo pro enable livepatch ``` -This will install the livepatch client, and enroll the system to the Ubuntu livepatch service. +This installs the Livepatch Client and enrolls the system in the Ubuntu Livepatch service. diff --git a/docs/client/how-to-guides/installation/index.md b/docs/client/how-to-guides/installation/index.md index 5d6fdfe..9d89b3f 100644 --- a/docs/client/how-to-guides/installation/index.md +++ b/docs/client/how-to-guides/installation/index.md @@ -1,7 +1,7 @@ --- myst: html_meta: - description: "Enable or disable the Livepatch client on your machines." + description: "Enable or disable the Livepatch Client on your machines." --- @@ -9,14 +9,14 @@ myst: # Installation -Enable or disable the Livepatch client on your machines. +Enable or disable the Livepatch Client on machines. ## In this section -- [Enable client](/client/how-to-guides/installation/enable-client.md) -- [Enable client on Ubuntu Core](/client/how-to-guides/installation/enable-client-on-ubuntu-core.md) -- [Disable client](/client/how-to-guides/installation/disable-client.md) -- [Disable Livepatch during startup](/client/how-to-guides/installation/disable-livepatch-during-startup.md) +* [Enable the client](/client/how-to-guides/installation/enable-client.md) +* [Enable the client on Ubuntu Core](/client/how-to-guides/installation/enable-client-on-ubuntu-core.md) +* [Disable the client](/client/how-to-guides/installation/disable-client.md) +* [Disable Livepatch during startup](/client/how-to-guides/installation/disable-livepatch-during-startup.md) ```{toctree} :titlesonly: diff --git a/docs/client/how-to-guides/operations/check-client-status.md b/docs/client/how-to-guides/operations/check-client-status.md index 1c0075d..c4c4f1e 100644 --- a/docs/client/how-to-guides/operations/check-client-status.md +++ b/docs/client/how-to-guides/operations/check-client-status.md @@ -1,14 +1,15 @@ --- myst: html_meta: - description: "How to check client status with Livepatch client." + description: "How to check client status with Livepatch Client." --- + (client-how-to-guides-how-to-check-the-livepatch-client-status)= -# How to check the Livepatch client status +# How to check the Livepatch Client status -Once `canonical-livepatch`, the livepatch client, is running on a machine, it will periodically (every hour by default) check for new patches. +Once `canonical-livepatch`, the Livepatch Client, is running on a machine, it periodically (every hour by default) checks for new patches. To show the current state of the client, run: @@ -23,119 +24,119 @@ last check: 52 seconds ago kernel: 5.4.0-216.236-generic server check-in: succeeded kernel state: ✓ kernel series 5.4 is covered by Livepatch -patch state: ✓ all applicable livepatch kernel modules applied +patch state: ✓ all applicable live kernel patch modules applied patch version: 113.1 tier: updates (Free usage; This machine beta tests new patches.) machine id: {alpha-numeric-string} ``` -The `kernel state` line indicates the current security coverage status for your running kernel: +The `kernel state` line indicates the current security coverage status for the running kernel: -- **✓ kernel series {kernel-series} is covered by Livepatch** +* **✓ kernel series {kernel-series} is covered by Livepatch** - The kernel series (e.g. `5.4`) is still security maintained by Canonical. Livepatches are available for this series until the security coverage window ends. + The kernel series (for example, `5.4`) is still security maintained by Canonical. Live kernel patches are available for this series until the security coverage window ends. -- **✓ kernel {kernel-version} is covered by Livepatch until {date}, please install available kernel updates and reboot before then** +* **✓ kernel {kernel-version} is covered by Livepatch until {date}, please install available kernel updates and reboot before then** - This specific kernel version (e.g. `5.4.0-216.236-generic`) is security maintained until the given date (its SRU end-of-security coverage date). You must install updates and reboot before then to stay covered. + This specific kernel version (for example, `5.4.0-216.236-generic`) is security maintained until the given date (its SRU end-of-security coverage date). Install updates and reboot before then to stay covered. -- **✗ kernel is not covered by Livepatch** +* **✗ kernel is not covered by Livepatch** The running kernel version is not security maintained by Canonical Livepatch. Consider upgrading to a security maintained kernel. -- **✗ kernel is no longer covered by Livepatch** +* **✗ kernel is no longer covered by Livepatch** - This kernel has reached end of life and no longer receives livepatches. Upgrade to a newer kernel. + This kernel has reached end of life and no longer receives live kernel patches. Upgrade to a newer kernel. -- **✗ Livepatch coverage has ended; please upgrade the kernel and reboot** +* **✗ Livepatch coverage has ended; please upgrade the kernel and reboot** Security maintenance has ended and no SRU date was provided. An upgrade is required. -- **✗ Livepatch coverage ended {date}; please upgrade the kernel and reboot** +* **✗ Livepatch coverage ended {date}; please upgrade the kernel and reboot** Security maintenance has ended as of the specified date. Upgrade to continue receiving patches. -- **✗ unable to determine kernel support status; please contact Canonical support** +* **✗ unable to determine kernel support status; please contact Canonical support** - An unexpected error occurred. Please [file a bug](https://bugs.launchpad.net/canonical-livepatch-client/+filebug) or contact Canonical support. + An unexpected error occurred. [File a bug](https://bugs.launchpad.net/canonical-livepatch-client/+filebug) or contact Canonical support. The `patch state` line can also have one of several values: -- **⧗ livepatches are downloaded, but the kernel module is not yet inserted** +* **⧗ live kernel patches are downloaded, but the kernel module is not yet inserted** A patch has been downloaded but the kernel module has not yet been inserted. -- **⧗ patching the kernel** +* **⧗ patching the kernel** A patch is currently being applied. -- **✓ no livepatches available for kernel {kernel-version}** +* **✓ no live kernel patches available for kernel {kernel-version}** No patches exist yet for the kernel with the specified version. -- **✓ all applicable livepatch kernel modules applied** +* **✓ all applicable live kernel patch modules applied** - All available livepatch kernel modules for this kernel have been inserted and applied. + All available live kernel patch modules for this kernel have been inserted and applied. -- **✗ livepatch kernel module inserted but kernel bug detected** +* **✗ Livepatch kernel module inserted but kernel bug detected** - The kernel reported an error after the livepatch kernel module was inserted. + The kernel reported an error after the Livepatch kernel module was inserted. -- **✗ detected a crash last time the livepatch kernel module was applied, check system logs with** `journalctl -f -u snap.canonical-livepatch.canonical-livepatchd` +* **✗ detected a crash last time the Livepatch kernel module was applied, check system logs with** `journalctl -f -u snap.canonical-livepatch.canonical-livepatchd` An earlier patch attempt caused a crash. -- **✗ unknown error occurred, please check system logs with** `journalctl -f -u snap.canonical-livepatch.canonical-livepatchd` +* **✗ unknown error occurred, please check system logs with** `journalctl -f -u snap.canonical-livepatch.canonical-livepatchd` An unexpected error occurred. -- **✗ kernel {kernel-version} contains a vulnerability that cannot be livepatched, please upgrade and reboot** +* **✗ kernel {kernel-version} contains a vulnerability that cannot be remediated with live kernel patching, please upgrade and reboot** This kernel has an unpatchable vulnerability. An upgrade is required. -- **✓ kernel upgraded after a reboot** +* **✓ kernel upgraded after a reboot** The kernel was recently upgraded and rebooted successfully. -- **✗ failed to verify the signature of the livepatch kernel module** +* **✗ failed to verify the signature of the Livepatch kernel module** Signature verification failed. The patch was not applied. -- **✗ failed to extract information about the livepatch kernel module** +* **✗ failed to extract information about the Livepatch kernel module** Patch metadata could not be read. -- **✗ failed to load certificate used to verify the signature of the livepatch kernel module** +* **✗ failed to load certificate used to verify the signature of the Livepatch kernel module** The required certificate could not be loaded. -- **✗ failed to confirm that the livepatch kernel module was applied successfully** +* **✗ failed to confirm that the Livepatch kernel module was applied successfully** - The client could not confirm that the livepatch kernel module was applied successfully. + The client could not confirm that the Livepatch kernel module was applied successfully. -If livepatches have been applied, you will see a `patch version` field `patch version: 113.1` as in the status output above. +If live kernel patches have been applied, a `patch version` field appears, for example `patch version: 113.1`, as in the status output above. Patch versions map directly to [Ubuntu Livepatch Security Notices (LSN)](https://ubuntu.com/security/notices) published in the format `LSN-`. The notices describe the vulnerabilities that were resolved in that version. -You can retrieve the corresponding LSN by mapping the version to the LSN identifier. For example: +The corresponding LSN can be retrieved by mapping the version to the LSN identifier. For example: -- `patch version: 113.1` maps to [LSN-0113-1](https://ubuntu.com/security/notices/LSN-0113-1) -- `patch version: 94.1` maps to [LSN-0094-1](https://ubuntu.com/security/notices/LSN-0094-1) +* `patch version: 113.1` maps to [LSN-0113-1](https://ubuntu.com/security/notices/LSN-0113-1) +* `patch version: 94.1` maps to [LSN-0094-1](https://ubuntu.com/security/notices/LSN-0094-1) -**Note**: LSN identifiers are zero-padded (e.g. `113.1` maps to `LSN-0113-1`). +**Note**: LSN identifiers are zero-padded (for example, `113.1` maps to `LSN-0113-1`). -The canonical-livepatch status command accepts flags that change the output format: +The `canonical-livepatch status` command accepts flags that change the output format: -- `--summary` shows a concise summary (similar to default output). +* `--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, and applied CVEs. -- `--show-secrets` shows sensitive machine tokens (requires sudo). +* `--show-secrets` shows sensitive machine tokens (requires sudo). -- `--format ` chooses the output format. Supported values: +* `--format ` chooses the output format. Supported values: - - `humane` (default, human-readable with minimal detail) + -- `humane` (default, human-readable with minimal detail) - - `json` (machine-readable JSON with extra metadata like architecture, CPU model, boot time, uptime, patch tier, etc.) + -- `json` (machine-readable JSON with extra metadata like architecture, CPU model, boot time, uptime, patch tier, etc.) - - `yaml` (machine-readable YAML with extra metadata similar to JSON output) + -- `yaml` (machine-readable YAML with extra metadata similar to JSON output) \ No newline at end of file diff --git a/docs/client/how-to-guides/operations/index.md b/docs/client/how-to-guides/operations/index.md index 8e0156e..f9ea30a 100644 --- a/docs/client/how-to-guides/operations/index.md +++ b/docs/client/how-to-guides/operations/index.md @@ -1,7 +1,7 @@ --- myst: html_meta: - description: "Day-to-day operation of the Livepatch client." + description: "Day-to-day operation of the Livepatch Client." --- @@ -9,11 +9,11 @@ myst: # Operations -Day-to-day operation of the Livepatch client. +Day-to-day operation of the Livepatch Client. ## In this section -- [Check client status](/client/how-to-guides/operations/check-client-status.md) +* [Check client status](/client/how-to-guides/operations/check-client-status.md) ```{toctree} :titlesonly: @@ -21,4 +21,4 @@ Day-to-day operation of the Livepatch client. :hidden: Check client status -``` +``` \ No newline at end of file diff --git a/docs/client/how-to-guides/security/index.md b/docs/client/how-to-guides/security/index.md index bddbc5e..856cbc5 100644 --- a/docs/client/how-to-guides/security/index.md +++ b/docs/client/how-to-guides/security/index.md @@ -13,9 +13,9 @@ Operate and decommission the client securely, and report vulnerabilities. ## In this section -- [Securely configure and operate the client](/client/how-to-guides/security/securely-configure-and-operate-the-client.md) -- [Securely Decommission the client](/client/how-to-guides/security/securely-decommission-the-client.md) -- [Report Client Vulnerability](/client/how-to-guides/security/report-client-vulnerability.md) +* [Securely configure and operate the client](/client/how-to-guides/security/securely-configure-and-operate-the-client.md) +* [Securely decommission the client](/client/how-to-guides/security/securely-decommission-the-client.md) +* [Report a client vulnerability](/client/how-to-guides/security/report-client-vulnerability.md) ```{toctree} :titlesonly: @@ -25,4 +25,4 @@ Operate and decommission the client securely, and report vulnerabilities. Securely configure and operate the client Securely decommission the client Report client vulnerability -``` +``` \ No newline at end of file diff --git a/docs/client/how-to-guides/security/report-client-vulnerability.md b/docs/client/how-to-guides/security/report-client-vulnerability.md index cadf863..c131d7b 100644 --- a/docs/client/how-to-guides/security/report-client-vulnerability.md +++ b/docs/client/how-to-guides/security/report-client-vulnerability.md @@ -1,16 +1,16 @@ --- myst: html_meta: - description: "How to report client vulnerability with Livepatch client." + description: "How to report client vulnerability with Livepatch Client." --- (client-how-to-guides-how-to-report-a-livepatch-client-vulnerability)= -# How to report a Livepatch client vulnerability +# How to report a Livepatch Client vulnerability -To report a security issue, please email [security@ubuntu.com](mailto:security@ubuntu.com) with a description of the issue, the steps to take to reproduce the issue, affected versions, and, if known, mitigations for the issue. You can also [report a bug to the Livepatch team on Launchpad](https://bugs.launchpad.net/canonical-livepatch-client/+filebug). Launchpad provides the option to mark a bug as “Private Security”, to only disclose the bug to the security group. See[ this](https://blog.launchpad.net/general/reimagining-the-nature-of-privacy-in-launchpad-part-1) for more information on how to file a private security bug on Launchpad. +To report a security issue, email [security@ubuntu.com](mailto:security@ubuntu.com) with a description of the issue, the steps to reproduce the issue, affected versions, and, if known, mitigations for the issue. A bug can also be [reported to the Livepatch team on Launchpad](https://bugs.launchpad.net/canonical-livepatch-client/+filebug). Launchpad provides the option to mark a bug as "Private Security", to only disclose the bug to the security group. See [this Launchpad blog post](https://blog.launchpad.net/general/reimagining-the-nature-of-privacy-in-launchpad-part-1) for more information on how to file a private security bug on Launchpad. -The Livepatch team will be notified of the issue and will work with you to determine whether the issue qualifies as a security issue. We will then handle figuring out a fix, getting a CVE assigned and coordinating the release of the fix. +The Livepatch team is notified of the issue and works to determine whether the issue qualifies as a security issue. The team then handles finding a fix, getting a CVE assigned, and coordinating the release of the fix. -The [Ubuntu Security disclosure and embargo policy](https://ubuntu.com/security/disclosure-policy) contains more information about what you can expect when you contact us and what we expect from you. +The [Ubuntu Security disclosure and embargo policy](https://ubuntu.com/security/disclosure-policy) contains more information about what to expect when contacting the team, and what is expected in return. \ No newline at end of file diff --git a/docs/client/how-to-guides/security/securely-configure-and-operate-the-client.md b/docs/client/how-to-guides/security/securely-configure-and-operate-the-client.md index e4de49f..fcb53b8 100644 --- a/docs/client/how-to-guides/security/securely-configure-and-operate-the-client.md +++ b/docs/client/how-to-guides/security/securely-configure-and-operate-the-client.md @@ -1,21 +1,21 @@ --- myst: html_meta: - description: "How to securely configure and operate the client with Livepatch client." + description: "How to securely configure and operate the client with Livepatch Client." --- (client-how-to-guides-how-to-securely-configure-and-operate-the-livepatch-client)= -# How to securely configure and operate the Livepatch client +# How to securely configure and operate the Livepatch Client -The Livepatch client is available for use as a confined snap, and therefore only has access to the specific interfaces defined for it. This massively reduces the attack vector, in the case that the Livepatch client is compromised. However, administrators and users of the Livepatch client snap must still ensure that the recommended security practices are followed, to maintain the security of the snap in their environments. +The Livepatch Client is available for use as a confined snap, and therefore only has access to the specific interfaces defined for it. This massively reduces the attack vector, in the case that the Livepatch Client is compromised. However, administrators of the Livepatch Client snap must still ensure that the recommended security practices are followed, to maintain the security of the snap in their environments. ## Use the latest version -The Livepatch client snap must always be installed from the [latest/stable channel](https://snapcraft.io/canonical-livepatch). This channel serves the latest stable release of the snap, and all security updates will be made available through this channel. +The Livepatch Client snap must always be installed from the [latest/stable channel](https://snapcraft.io/canonical-livepatch). This channel serves the latest stable release of the snap, and all security updates are made available through this channel. -Use the following commands to check if the latest version of the Livepatch client snap has been installed in the system. +Use the following commands to check if the latest version of the Livepatch Client snap is installed on the system: ```shell # Install yq if not already present @@ -26,29 +26,29 @@ snap info canonical-livepatch | yq '.channels.latest/stable' | awk '{print $1}' snap info canonical-livepatch | yq '.installed' | awk '{print $1}' ``` -If the versions do not match, update the Livepatch client snap to the latest version by running the following command. +If the versions do not match, update the Livepatch Client snap to the latest version by running the following command: ``` sudo snap refresh canonical-livepatch --channel=latest/stable ``` -## Encrypt connection between the client and the server +## Encrypt the connection between the client and the server -The default configuration of the Livepatch client uses the Canonical-hosted Livepatch server as the remote-server, with no additional ca-certs or proxy configurations enabled. Using the default configuration ensures that the data is always encrypted in transit, as the Livepatch client uses TLS (minimum v1.2) with server-side authentication while communicating with the Canonical-hosted Livepatch server. +The default configuration of the Livepatch Client uses the Canonical-hosted Livepatch Server as the remote server, with no additional CA certificates or proxy configurations enabled. Using the default configuration ensures that the data is always encrypted in transit, as the Livepatch Client uses TLS (minimum v1.2) with server-side authentication while communicating with the Canonical-hosted Livepatch Server. -However, for on-premises Livepatch server deployments, users can decide to forgo TLS while communicating with the Livepatch server, as there is no strict TLS enforcement at the client-side. It is strongly recommended to enable TLS for communication between the client and the on-prem Livepatch servers, to prevent attacks from malicious actors. The Livepatch client supports using TLS for such communications, by providing a way to configure additional CA certificates and route traffic through proxies. See these how-to guides on [configuring the client for TLS with custom certificates](/server/how-to-guides/security/setup-tls.md#configuring-livepatch-client-with-tls) and [configuring the client to use proxies](/client/how-to-guides/configuration/configure-proxy.md). +However, for on-premises Livepatch Server deployments, TLS can be forgone while communicating with the Livepatch Server, as there is no strict TLS enforcement at the client side. It is strongly recommended to enable TLS for communication between the client and the on-premises Livepatch Servers, to prevent attacks from malicious actors. The Livepatch Client supports using TLS for such communications, by providing a way to configure additional CA certificates and route traffic through proxies. See the how-to guides on [configuring the client for TLS with custom certificates](/server/how-to-guides/security/setup-tls.md#configure-the-livepatch-client-with-tls) and [configuring the client to use proxies](/client/how-to-guides/configuration/configure-proxy.md). -It is also recommended to enforce TLS for patch downloads, when using an on-premises deployment of the Livepatch server, by setting the `tls-patch-download` configuration option to `true`. +It is also recommended to enforce TLS for patch downloads, when using an on-premises deployment of the Livepatch Server, by setting the `tls-patch-download` configuration option to `true`. ## Maintain strict privileged access -The Livepatch client snap does not encrypt its data at rest. However, all client specific data is stored in the [$SNAP_COMMON](https://snapcraft.io/docs/reference/development/environment-variables/#snap-common) and [$SNAP_DATA](https://snapcraft.io/docs/reference/development/environment-variables/#snap-data) directories. For further information, see the [security overview for snaps](https://snapcraft.io/docs/explanation/security/security-policies/#security-overview) and the documentation on [data locations used by snaps](https://snapcraft.io/docs/reference/administration/data-locations/#data-locations). +The Livepatch Client snap does not encrypt its data at rest. However, all client-specific data is stored in the [$SNAP_COMMON](https://snapcraft.io/docs/reference/development/environment-variables/#snap-common) and [$SNAP_DATA](https://snapcraft.io/docs/reference/development/environment-variables/#snap-data) directories. For further information, see the [security overview for snaps](https://snapcraft.io/docs/explanation/security/security-policies/#security-overview) and the documentation on [data locations used by snaps](https://snapcraft.io/docs/reference/administration/data-locations/#data-locations). -By default, the Livepatch client runs as a privileged daemon process and stores all necessary data in these directories. The stored data can only be accessed by the root user for reads and writes. Therefore, maintaining strict privileged access controls on machines running the Livepatch client snap, is essential to preventing unauthorized access of the snap data. +By default, the Livepatch Client runs as a privileged daemon process and stores all necessary data in these directories. The stored data can only be accessed by the root user for reads and writes. Therefore, maintaining strict privileged access controls on machines running the Livepatch Client snap is essential to preventing unauthorized access of the snap data. -## Configuring the Livepatch client +## Configure the Livepatch Client -See these how-to guides and configuration references to understand how to configure the Livepatch client and the configuration options available: +See the following how-to guides and configuration references to understand how to configure the Livepatch Client and the configuration options available: -1. [How to configure the Livepatch client](/client/how-to-guides/configuration/configure-livepatch-client.md) -2. [Livepatch client configuration options reference](/client/reference/platform/configuration-options.md) +1. [How to configure the Livepatch Client](/client/how-to-guides/configuration/configure-livepatch-client.md) +2. [Livepatch Client configuration options reference](/client/reference/platform/configuration-options.md) diff --git a/docs/client/how-to-guides/security/securely-decommission-the-client.md b/docs/client/how-to-guides/security/securely-decommission-the-client.md index d37c39d..38aac0e 100644 --- a/docs/client/how-to-guides/security/securely-decommission-the-client.md +++ b/docs/client/how-to-guides/security/securely-decommission-the-client.md @@ -1,49 +1,50 @@ --- myst: html_meta: - description: "How to securely decommission the client with Livepatch client." + description: "How to securely decommission the client with Livepatch Client." --- (client-how-to-guides-how-to-securely-decommission-the-livepatch-client)= -# How to securely decommission the Livepatch client +# How to securely decommission the Livepatch Client -The canonical-livepatch snap holds user, application and configuration data during its lifecycle. The canonical-livepatch snap also produces application and security logs. This guide provides an overview on how to decommission the Livepatch client securely. +The `canonical-livepatch` snap holds user, application, and configuration data during its lifecycle. The `canonical-livepatch` snap also produces application and security logs. This guide provides an overview of how to decommission the Livepatch Client securely. ## Decommission the snap data -Decommissioning the snap data requires deleting the snap and any remnant data that the snap has created. The following steps highlight how this can be done: +Decommissioning the snap data requires deleting the snap and any remnant data that the snap has created. The following steps outline how to accomplish this: -1. Remove and delete the snap. Running this command will unmount the snap and remove all snap data under `/var/snap/canonical-livepatch/` and `/home//snap/canonical-livepatch/`. However, **a copy of the snap data is retained as a snapshot for 30 days**. This snapshot can be restored or manually retrieved. +1. Remove and delete the snap. Running this command unmounts the snap and removes all snap data under `/var/snap/canonical-livepatch/` and `/home//snap/canonical-livepatch/`. However, **a copy of the snap data is retained as a snapshot for 30 days**. This snapshot can be restored or manually retrieved. -``` -sudo snap remove canonical-livepatch -``` + ``` + sudo snap remove canonical-livepatch + ``` -2. To remove and **delete a snap without creating any new data snapshots**, use the `--purge` flag with the `snap remove` command. While this will remove the snap data and not create any new snapshots, previously created snapshots will not be deleted. +2. To remove and **delete a snap without creating any new data snapshots**, use the `--purge` flag with the `snap remove` command. While this removes the snap data and does not create any new snapshots, previously created snapshots are not deleted. -``` -sudo snap remove --purge canonical-livepatch -``` + ``` + sudo snap remove --purge canonical-livepatch + ``` -3. Any remnant data snapshots of the canonical-livepatch snap can be found and deleted in a two-step process. +3. Any remnant data snapshots of the `canonical-livepatch` snap can be found and deleted in a two-step process. -- The first step involves finding the snapshots. + Find the snapshots: -``` -sudo snap saved canonical-livepatch -``` + ``` + sudo snap saved canonical-livepatch + ``` -- If any snapshots exist for the canonical-livepatch snap, running the command will display the snapshot IDs under the Set column. The snapshot IDs can then be used to delete the snap data snapshots. - For example, if there are 3 existing snapshots for the canonical-livepatch snap with IDs 1, 2 and 3, run the following command to delete the snapshots + If any snapshots exist for the `canonical-livepatch` snap, running the command displays the snapshot IDs under the Set column. The snapshot IDs can then be used to delete the snap data snapshots. -``` -printf "%s\n" 1 2 3 | xargs -I {} sudo snap forget {} canonical-livepatch -``` + For example, if there are three existing snapshots for the `canonical-livepatch` snap with IDs 1, 2, and 3, run the following command to delete the snapshots: + + ``` + printf "%s\n" 1 2 3 | xargs -I {} sudo snap forget {} canonical-livepatch + ``` ## Decommission the snap logs -The canonical-livepatch snap generates two kinds of logs during its lifecycle. These include the security logs and the application logs. The security logs are always stored in the logs file under the [$SNAP_COMMON](https://snapcraft.io/docs/reference/administration/data-locations/#system-data) directory for the snap. Therefore, these logs can be securely deleted and purged by deleting the snap and all of its snapshots, using the steps mentioned above. +The `canonical-livepatch` snap generates two kinds of logs during its lifecycle: security logs and application logs. The security logs are always stored in the logs file under the [$SNAP_COMMON](https://snapcraft.io/docs/reference/administration/data-locations/#system-data) directory for the snap. Therefore, these logs can be securely deleted and purged by deleting the snap and all of its snapshots, using the steps mentioned above. -The application logs on the other hand, are captured by the systemd-journald service. Use `journalctl --directory=/var/log/journal -u snap.canonical-livepatch.canonical-livepatchd.service` to check if logs for the canonical-livepatch snap exist in the journal. These logs are interleaved with other system logs in the journal, and therefore, cannot be removed without impacting other system logs. The remnant logs from the snap will be removed when the journal automatically rotates and vacuums the logs as per the system configurations for the journald service. See the manpage for the [journald service](https://man7.org/linux/man-pages/man8/systemd-journald.service.8.html) and [journald configuration](https://man7.org/linux/man-pages/man5/journald.conf.5.html) for more information. +The application logs, on the other hand, are captured by the `systemd-journald` service. Use `journalctl --directory=/var/log/journal -u snap.canonical-livepatch.canonical-livepatchd.service` to check if logs for the `canonical-livepatch` snap exist in the journal. These logs are interleaved with other system logs in the journal, and therefore cannot be removed without impacting other system logs. The remnant logs from the snap are removed when the journal automatically rotates and vacuums the logs as per the system configurations for the `journald` service. See the manpage for the [journald service](https://man7.org/linux/man-pages/man8/systemd-journald.service.8.html) and [journald configuration](https://man7.org/linux/man-pages/man5/journald.conf.5.html) for more information. \ No newline at end of file diff --git a/docs/client/index.md b/docs/client/index.md index aa0d8d3..440e0e7 100644 --- a/docs/client/index.md +++ b/docs/client/index.md @@ -1,30 +1,31 @@ --- myst: html_meta: - description: "Livepatch client documentation home." + description: "Reference and how-to documentation for the Livepatch Client, including configuration, networking, patch management, and troubleshooting." --- - (client)= # Client -Livepatch client is the software running on a machine, that periodically checks for the availability of new patches. Once new patches are available, they are downloaded, verified and applied to the current kernel. +The Livepatch Client runs on each registered machine to periodically check for the availability of new live kernel patches. When new patches are available, the client downloads, verifies, and applies them to the running kernel without requiring a system reboot. + +The Livepatch Client can connect to Canonical's hosted Livepatch service or to an on-premises Livepatch Server. ## In this documentation -| | | -|----------------------------------------------------------------------------------------------|-| -| Tutorials
Get started with Canonical Livepatch Client. | [How-to guides](/client/how-to-guides/index.md)
Step-by-step guides covering key operations and common tasks
| -| [Explanation](/client/explanation/index.md)
Discussion and clarification of key topics | [Reference](/client/reference/index.md)
Technical information - specifications, APIs, architecture | +| | | +| --- | --- | +| [How-to guides](/client/how-to-guides/index.md)
Step-by-step guides covering key operations and common tasks. | [Reference](/client/reference/index.md)
Technical reference for the Livepatch Client, including platform support, networking requirements, and patch security. | +| [Explanation](/client/explanation/index.md)
Discussion and clarification of key Livepatch Client topics. | | ## Getting support -Canonical customers can receive support and report issues on the Ubuntu Livepatch service, Livepatch client or Livepatch on-prem, on Canonical's [support portal](https://portal.support.canonical.com/). +Canonical customers can receive support and report issues with the Ubuntu Livepatch service, the Livepatch Client, or Livepatch on-prem through the [Canonical support portal](https://portal.support.canonical.com/). -The projects maintain bug trackers at +The projects maintain bug trackers at: -- [Livepatch client bug tracker](https://bugs.launchpad.net/canonical-livepatch-client/+filebug) +- [Livepatch Client bug tracker](https://bugs.launchpad.net/canonical-livepatch-client/+filebug) - [Livepatch on-prem bug tracker](https://bugs.launchpad.net/livepatch-onprem/+filebug) ```{toctree} @@ -36,4 +37,4 @@ The projects maintain bug trackers at How-to guides Reference Explanation -``` +``` \ No newline at end of file diff --git a/docs/client/reference/index.md b/docs/client/reference/index.md index 9a5f7fd..266db0e 100644 --- a/docs/client/reference/index.md +++ b/docs/client/reference/index.md @@ -1,21 +1,20 @@ --- myst: html_meta: - description: "Reference - technical reference for Livepatch client." + description: "Technical reference for the Livepatch Client, covering supported platforms, networking requirements, patch lifecycle, and release notes." --- - (client-reference)= # Reference -Technical information - security, APIs, architecture, etc., related to Livepatch. +This section provides technical reference information for the Livepatch Client. ## In this section - [Platform](/client/reference/platform/index.md) — Supported kernels, architectures, and client configuration options. -- [Networking](/client/reference/networking/index.md) — Network requirements, content caching, and data sent to Canonical. -- [Patches](/client/reference/patches/index.md) — How patches are installed, their lifecycle, and their security. +- [Networking](/client/reference/networking/index.md) — Network requirements, firewall rules, and data sent during patch checks. +- [Patches](/client/reference/patches/index.md) — How patches are verified, signed, and installed, and the cryptographic mechanisms that secure them. - [Releases](/release-notes/client/index.md) — Release notes for the Livepatch Client. ```{toctree} @@ -27,4 +26,4 @@ Platform Networking Patches Releases <../../release-notes/client/index.md> -``` +``` \ No newline at end of file diff --git a/docs/client/reference/networking/data-sent.md b/docs/client/reference/networking/data-sent.md index 91f2d93..a673d27 100644 --- a/docs/client/reference/networking/data-sent.md +++ b/docs/client/reference/networking/data-sent.md @@ -1,22 +1,21 @@ --- myst: html_meta: - description: "Data sent - technical reference for Livepatch client." + description: "Reference listing the system information transmitted by the Livepatch Client to Canonical during periodic patch status checks." --- - (client-reference-data-sent-to-canonical)= # Data sent to Canonical -Livepatch client instances ping servers hosted by Canonical at a configurable schedule (every hour by default) to check for the availability of new patches. These requests contain the following information: +The Livepatch Client sends periodic requests to servers hosted by Canonical to check for the availability of new patches. These requests are sent at a configurable interval (every 60 minutes by default) and include the following information: -- system architecture +- System architecture - CPU model -- kernel version -- boot time and uptime -- unique machine identifier, based on `/etc/machine-id` -- version of the currently applied livepatch (if any) -- current state of the system (whether a livepatch has been applied or not) -- time of the last server request -- version of the client +- Kernel version +- Boot time and uptime +- Unique machine identifier, derived from `/etc/machine-id` +- Version of the currently applied live kernel patch, if any +- Current state of the system (whether a live kernel patch has been applied) +- Time of the last server request +- Livepatch Client version \ No newline at end of file diff --git a/docs/client/reference/networking/index.md b/docs/client/reference/networking/index.md index 1499bab..91d4bed 100644 --- a/docs/client/reference/networking/index.md +++ b/docs/client/reference/networking/index.md @@ -1,26 +1,25 @@ --- myst: html_meta: - description: "Network requirements, content caching, and data sent to Canonical." + description: "Reference for Livepatch Client networking, including firewall requirements and data transmitted during patch status checks." --- - (client-reference-networking)= # Networking -Network requirements, content caching, and data sent to Canonical. +Network requirements, firewall configurations, and data sent by the Livepatch Client during its periodic patch checks. ## In this section -- [Network requirements](/client/reference/networking/network-requirements.md) -- [Data sent](/client/reference/networking/data-sent.md) +- [Firewall configuration](/client/reference/networking/network-requirements.md) — Hostnames and ports the Livepatch Client requires for outbound connectivity. +- [Data sent to Canonical](/client/reference/networking/data-sent.md) — Information included in the client's periodic patch status requests. ```{toctree} :titlesonly: :maxdepth: 1 :hidden: -Network requirements -Data sent -``` +Firewall configuration +Data sent to Canonical +``` \ No newline at end of file diff --git a/docs/client/reference/networking/network-requirements.md b/docs/client/reference/networking/network-requirements.md index 1637ccf..286d0db 100644 --- a/docs/client/reference/networking/network-requirements.md +++ b/docs/client/reference/networking/network-requirements.md @@ -1,21 +1,22 @@ --- myst: html_meta: - description: "Network requirements - technical reference for Livepatch client." + description: "Reference for Livepatch Client firewall requirements, listing the hostnames and ports needed for outbound connectivity." --- - (client-reference-livepatch-client-firewall-configuration)= -# Livepatch client firewall configuration +# Livepatch Client firewall configuration -On firewalled machines, `canonical-livepatch` needs access to two hostnames: +On firewalled machines, the Livepatch Client requires outbound access to the following hostnames: - `livepatch.canonical.com`, port 443 - `livepatch-files.canonical.com`, port 443 -If livepatch client is enabled using Ubuntu Pro, additional access to `contracts.canonical.com` on port 443 will be required. +If the Livepatch Client is enabled through Ubuntu Pro, additional access to `contracts.canonical.com` on port 443 is required. -For snap installation, see [snap network requirements](https://forum.snapcraft.io/t/network-requirements/5147). +For snap installations, see the [snap network requirements](https://forum.snapcraft.io/t/network-requirements/5147). -**Note:** Previously patches were served via HTTP until switching over to HTTPS in ~Oct 2023. +```{note} +Before October 2023, patches were served over HTTP. All patch downloads now use HTTPS. +``` \ No newline at end of file diff --git a/docs/client/reference/patches/index.md b/docs/client/reference/patches/index.md index 71af05a..4f4f65d 100644 --- a/docs/client/reference/patches/index.md +++ b/docs/client/reference/patches/index.md @@ -1,19 +1,18 @@ --- myst: html_meta: - description: "How patches are installed, their lifecycle, and their security." + description: "Reference for Livepatch Client patch handling, including how patches are verified, signed, and secured during download and application." --- - (client-reference-patches)= # Patches -How patches are installed, their lifecycle, and their security. +How patches are verified, signed, and secured during download and application by the Livepatch Client. ## In this section -- [Patch Security](/client/reference/patches/patch-security.md) +- [Patch security](/client/reference/patches/patch-security.md) — Cryptographic mechanisms used for patch verification, digital signatures, and TLS communication. ```{toctree} :titlesonly: @@ -21,4 +20,4 @@ How patches are installed, their lifecycle, and their security. :hidden: Patch security -``` +``` \ No newline at end of file diff --git a/docs/client/reference/patches/patch-security.md b/docs/client/reference/patches/patch-security.md index bfdf7ba..d506b9e 100644 --- a/docs/client/reference/patches/patch-security.md +++ b/docs/client/reference/patches/patch-security.md @@ -1,59 +1,60 @@ --- myst: html_meta: - description: "Patch Security - technical reference for Livepatch client." + description: "Technical reference for Livepatch Client patch security, covering patch verification via SHA-256 checksums, RSA-signed kernel modules, and TLS communication." --- - (client-reference-patch-security)= -# Patch Security +# Patch security -This document acts as a reference on how patches are secured and outlines the cryptography used by the Livepatch client for this purpose. +This document describes how live kernel patches are secured and outlines the cryptographic mechanisms used by the Livepatch Client. -## Patch Verification +## Patch verification -Patches are downloaded in a multi-step process, +Patches are downloaded in a multi-step process: -1. Client queries for any new patches from the Livepatch-server. -2. The server returns a SHA256 checksum of the patch contents and a link to the patch file. -3. The client downloads the patch and verifies that a checksum of the downloaded patch matches the expected value. +1. The client queries the Livepatch Server for available patches. +2. The server returns a SHA-256 checksum of the patch contents and a URL to the patch file. +3. The client downloads the patch and verifies that the SHA-256 checksum of the downloaded file matches the expected value. -This process ensures the integrity of the downloaded file using SHA256 hashing. +This process ensures file integrity using SHA-256 hashing. Go packages used for patch verification: -- crypto/sha256 -## Patch Signatures +- [`crypto/sha256`](https://pkg.go.dev/crypto/sha256) + +## Patch signatures -Patch files are distributed as tarballs. Within each tarball is some metadata and a Linux kernel module (.ko file). The kernel module is responsible for modifying the running kernel to patch high and critical vulnerabilities. +Patch files are distributed as tarballs containing metadata and a Linux kernel module (`.ko` file). The kernel module modifies the running kernel to patch high and critical vulnerabilities. -All kernel modules are signed by Canonical to verify their authenticity. This process is done using asymmetric encryption. +All kernel modules are signed by Canonical to verify their authenticity, using asymmetric encryption: -- Signature algorithm: SHA512 with RSA -- Canonical’s [Public key](https://git.launchpad.net/~ubuntu-kernel/ubuntu/+source/linux/+git/jammy/plain/debian/certs/canonical-livepatch-all.pem) +- Signature algorithm: SHA-512 with RSA +- Canonical's [public key](https://git.launchpad.net/~ubuntu-kernel/ubuntu/+source/linux/+git/jammy/plain/debian/certs/canonical-livepatch-all.pem) -Kernel modules are authenticated before they are installed, ensuring that the patch was made by Canonical and securing the Livepatch client against installation of maliciously crafted patches. The public keys used for signature verification are baked into the livepatch client, and therefore, no external access is required to use them. +Kernel modules are authenticated before they are installed. This ensures the patch was produced by Canonical and protects the client from installing maliciously crafted patches. The public keys used for signature verification are embedded in the Livepatch Client and do not require external access. -Go packages used in the process of verifying kernel module signatures: +Go packages used for verifying kernel module signatures: -- encoding/pem for decoding PEM encoded public certificates -- crypto/x509 for parsing the public certificates -- github.com/smallstep/pkcs7 for parsing and verifying the signature with the public certificates. +- [`encoding/pem`](https://pkg.go.dev/encoding/pem) — Decoding PEM-encoded public certificates +- [`crypto/x509`](https://pkg.go.dev/crypto/x509) — Parsing public certificates +- [`github.com/smallstep/pkcs7`](https://github.com/smallstep/pkcs7) — Parsing and verifying signatures with public certificates ## TLS communication -The Livepatch client supports HTTPS as a transport layer protocol. This relies on TLS communication. Without delving into TLS, the Livepatch client uses certificates from the host machine’s CA cert pool along with additional fixed certificates, to verify the authenticity of the Livepatch server. The livepatch client also provides users with the ability to add their custom certificates to the CA cert pool. +The Livepatch Client supports HTTPS as its transport protocol, relying on standard TLS communication. The client uses certificates from the host machine's CA certificate pool, together with additional fixed certificates, to verify the authenticity of the Livepatch Server. Custom CA certificates can also be added to the pool. + +The client requires a minimum of TLS v1.2. -The client supports a minimum of TLS v1.2. +The `remote-server` configuration option determines which upstream Livepatch Server the client contacts. There is no client-side enforcement that TLS be used — an on-premises Livepatch Server may operate without TLS, although this is not recommended. Canonical's hosted Livepatch Server redirects HTTP traffic to HTTPS. -The `remote-server` config option on the client influences the upstream Livepatch server. There is no client side enforcement that TLS be used, and an on-premises deployment of the Livepatch server may decide to forgo TLS although this is not recommended. The Canonical hosted Livepatch server redirects HTTP traffic to HTTPS. +To add custom CA certificates to the CA certificate pool, see the [Livepatch Client configuration reference](/client/reference/platform/configuration-options.md). Custom CA certificates must be encoded as PEM. -The Livepatch client provides users with the ability to add their custom certificates to the CA cert pool. For more information on how to add custom certificates to the CA certificate pool, see the [configuration reference](/client/reference/platform/configuration-options.md) for the Livepatch client. The custom CA certificates should be encoded as PEM. +The Livepatch Client can connect to the hosted Livepatch Server or an on-premises server through HTTPS proxies. See the [proxy configuration guide](/client/how-to-guides/configuration/configure-proxy.md) for instructions on configuring proxy communication. -The Livepatch client can also connect to the hosted Livepatch server or an on-premises Livepatch server through HTTPS proxies. See [this how-to guide](/client/how-to-guides/configuration/configure-proxy.md) to understand how to configure proxies for secure communication. +The Livepatch Client can also be configured to enforce TLS for all patch downloads. When connecting to Canonical's hosted service, the server always provides an `https` URL, ensuring patch downloads occur over TLS. To enforce TLS for patch downloads from an on-premises Livepatch Server, see the [configuration reference](/client/reference/platform/configuration-options.md). -The Livepatch client can also be configured to enforce TLS for all patch downloads. The Canonical-hosted Livepatch server will always serve a `https` URL, so that all patch downloads from the hosted patch storage are made securely over TLS. For more information on how to enforce TLS patch downloads, when clients are getting updates from on-premises Livepatch servers, see the [configuration reference](/client/reference/platform/configuration-options.md) for the Livepatch client. +Go packages used for TLS configuration: -Go packages used for setting up TLS configuration for the Livepatch client: -- crypto/tls +- [`crypto/tls`](https://pkg.go.dev/crypto/tls) \ No newline at end of file diff --git a/docs/client/reference/platform/configuration-options.md b/docs/client/reference/platform/configuration-options.md index 6123ca9..dafabd3 100644 --- a/docs/client/reference/platform/configuration-options.md +++ b/docs/client/reference/platform/configuration-options.md @@ -1,28 +1,27 @@ --- myst: html_meta: - description: "Configuration Options - technical reference for Livepatch client." + description: "Configuration reference for the Livepatch Client, including proxy settings, server URL, check intervals, and TLS enforcement options." --- - (client-reference-livepatch-client-configuration-options)= -# Livepatch client configuration options +# Livepatch Client configuration options -The following configuration options are available for the Livepatch client, which can be set following the [How to configure Livepatch client](/client/how-to-guides/configuration/configure-livepatch-client.md) how-to guide. +The following configuration options are available for the Livepatch Client. See the [how-to guide on configuring the Livepatch Client](/client/how-to-guides/configuration/configure-livepatch-client.md) for instructions on applying these settings. -|Key | Data Type | Description | Default Value| -|--- | --- | --- | ---| -|`http-proxy` | string | Value passed as `HTTP_PROXY` (overrides `/etc/environment`) | Empty| -|`https-proxy` | string | Value passed as `HTTPS_PROXY` (overrides `/etc/environment`) | Empty| -|`no-proxy` | string | Value passed as `NO_PROXY` (overrides `/etc/environment`) | Empty| -|`remote-server` | string | Livepatch server URL | `https://livepatch.canonical.com`| -|`ca-certs` | string | Custom CA root certificate(s) encoded as PEM | Empty| -|`dial-timeout` | string | Timeout for opening TCP connections; allowed units are `s`, `m`, `h` | `12s`| -|`check-interval` | integer | Minutes between checks for new patches. Minimum `60`. Use `0` to disable auto refresh | `60`| -|`log-level` | string | One of `debug`, `info`, `notice`, `warning`, `error` | `warning`| -|`tls-patch-download` | boolean | Enforce using TLS for patch downloads | `false` | -|`cutoff-date` 1 | string | RFC3339 date in the past after which new patched will not be installed | Empty| -|`patch-delay` 1 | string | Duration before a newly released patch is received by the client; allowed units are `s`, `m`, `h`, `d`, `w` | `0`| +| Key | Data type | Description | Default value | +| --- | --------- | ----------- | ------------- | +| `http-proxy` | string | Value passed as `HTTP_PROXY`. Overrides `/etc/environment`. | Empty | +| `https-proxy` | string | Value passed as `HTTPS_PROXY`. Overrides `/etc/environment`. | Empty | +| `no-proxy` | string | Value passed as `NO_PROXY`. Overrides `/etc/environment`. | Empty | +| `remote-server` | string | URL of the Livepatch Server. | `https://livepatch.canonical.com` | +| `ca-certs` | string | Custom CA root certificates encoded as PEM. | Empty | +| `dial-timeout` | string | Timeout for opening TCP connections. Allowed units: `s`, `m`, `h`. | `12s` | +| `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` | +| `cutoff-date` 1 | string | RFC 3339 date in the past. Patches released after this date are not installed. | Empty | +| `patch-delay` 1 | string | Duration to wait before a newly released patch is applied. Allowed units: `s`, `m`, `h`, `d`, `w`. | `0` | -1 Only available to paid Ubuntu Pro users who are using Canonical-hosted Livepatch, with the `remote-server` option unchanged +1 Only available to paid Ubuntu Pro subscribers using Canonical's hosted Livepatch service (with the `remote-server` option unchanged). \ No newline at end of file diff --git a/docs/client/reference/platform/index.md b/docs/client/reference/platform/index.md index 07b48d4..998dcee 100644 --- a/docs/client/reference/platform/index.md +++ b/docs/client/reference/platform/index.md @@ -1,21 +1,20 @@ --- myst: html_meta: - description: "Supported kernels, architectures, and client configuration options." + description: "Reference for Livepatch Client platform support, including supported kernels, architectures, and available configuration options." --- - (client-reference-platform)= # Platform -Supported kernels, architectures, and client configuration options. +Supported kernels, architectures, and configuration options for the Livepatch Client. ## In this section -- [Supported kernels](/client/reference/platform/supported-kernels.md) -- [Configuration Options](/client/reference/platform/configuration-options.md) -- [Which are the supported architectures?](/client/reference/platform/which-are-the-supported-architectures.md) +- [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. ```{toctree} :titlesonly: @@ -23,6 +22,6 @@ Supported kernels, architectures, and client configuration options. :hidden: Supported kernels +Supported architectures Configuration options -Which are the supported architectures -``` +``` \ No newline at end of file diff --git a/docs/client/reference/platform/supported-kernels.md b/docs/client/reference/platform/supported-kernels.md index 75cf573..d60884a 100644 --- a/docs/client/reference/platform/supported-kernels.md +++ b/docs/client/reference/platform/supported-kernels.md @@ -1,16 +1,17 @@ --- myst: html_meta: - description: "Supported kernels - technical reference for Livepatch client." + description: "Reference of kernel versions, flavours, and Ubuntu releases with Livepatch support, including upgrade and reboot interval guidance." --- - (client-reference-kernels-covered-by-livepatch)= # Kernels covered by Livepatch -| Ubuntu release | Arch | Kernel Version | Kernel Variants | Upgrade and Reboot\* | -| ---------------- | ---------- | -------------- | -------------------------------------------------------------------------------------------------------- | ------------------- | +The following table lists the kernel versions, flavours, and Ubuntu releases for which live kernel patches are available. + +| Ubuntu release | Architecture | Kernel version | Kernel flavours | Upgrade and reboot interval* | +| -------------- | ------------ | -------------- | --------------- | --------------------------- | | Ubuntu 26.04 LTS | arm64 | 7.0 (GA) | aws, azure, fips, gcp, generic, gke, ibm, lowlatency, oracle | every 13 months | | Ubuntu 26.04 LTS | 64-bit x86 | 7.0 (GA) | aws, azure, fips, gcp, generic, gke, ibm, ibm-gt, ibm-gt-tdx, lowlatency, oracle | every 13 months | | Ubuntu 24.04 LTS | 64-bit x86 | 7.0 (HWE) | aws, azure, fips, gcp, generic, gke, ibm | every 13 months | @@ -30,12 +31,12 @@ myst: | Ubuntu 16.04 LTS | 64-bit x86 | 4.4 (GA) | aws, fips, generic, lowlatency | every 13 months | | Ubuntu 14.04 LTS | 64-bit x86 | 4.4 (HWE) | generic, lowlatency | every 13 months | -**Upgrade and Reboot Interval:** Security patches are only created for a kernel for up to 9-13 months from the release date of the kernel. We recommend updating and restarting your machine within this period to continue receiving Livepatch updates. New kernel ABIs are provided during the Ubuntu Pro security coverage period, which you can learn more about [here](https://ubuntu.com/pro). +**\*Upgrade and reboot interval:** Security patches are created for a kernel for up to 9–13 months from its release date. Upgrade and restart the machine within this period to continue receiving Livepatch patches. New kernel ABIs are provided during the [Ubuntu Pro security coverage period](https://ubuntu.com/pro). -GA is the kernel a release launched with, while [HWE or Hardware Enablement](https://ubuntu.com/kernel/lifecycle) kernels are a set of newer kernel that become available in the current LTS release as these newer kernels are released with subsequent Ubuntu versions, up until the next LTS release. +GA refers to the kernel a release launched with. [HWE (Hardware Enablement)](https://ubuntu.com/kernel/lifecycle) kernels are newer kernels introduced into the current LTS release as they ship with subsequent Ubuntu versions, up until the next LTS release. -There will be Livepatch support for HWE kernels across a limited combination of kernel flavour (variants), kernel version, and Ubuntu release as detailed above. +Livepatch provides HWE kernel support for a limited combination of kernel flavour, kernel version, and Ubuntu release, as described in the table above. -Livepatch will provide security coverage for ARM64 architectures from release 26.04. Older releases are not covered for the ARM64 architecture, due to limitations in the tooling available in these releases. +Livepatch provides security coverage for ARM64 (arm64) architectures from release 26.04 onward. Older releases are not covered for the ARM64 architecture due to limitations in the available tooling. -See [this page](/client/explanation/troubleshooting/why-livepatch-is-not-working-on-my-machine.md) to better understand why your kernel might not be supported. +For help diagnosing why a specific kernel may not be receiving patches, see the [troubleshooting guide](/client/explanation/troubleshooting/why-livepatch-is-not-working-on-my-machine.md). \ No newline at end of file diff --git a/docs/client/reference/platform/which-are-the-supported-architectures.md b/docs/client/reference/platform/which-are-the-supported-architectures.md index 1c15d1c..60daca6 100644 --- a/docs/client/reference/platform/which-are-the-supported-architectures.md +++ b/docs/client/reference/platform/which-are-the-supported-architectures.md @@ -1,12 +1,16 @@ --- myst: html_meta: - description: "Which are the supported architectures? - learn about this topic in Livepatch client." + description: "Reference listing the CPU architectures supported by Canonical Livepatch for live kernel patching." --- - (client-reference-which-are-the-supported-architectures)= -# Which are the supported architectures? +# Supported architectures + +Canonical currently provides live kernel patches for kernels on the following CPU architectures: + +- **amd64** (x86-64) +- **s390x** -Canonical currently only creates livepatches for kernels on amd64 (x86-64) and s390x architectures. +Support for ARM64 (arm64) is available starting with Ubuntu 26.04 LTS. Older Ubuntu releases are not covered for ARM64 due to limitations in the tooling available in those releases. \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 2d8ab56..1a4871b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -247,13 +247,14 @@ # Excludes files or directories from processing exclude_patterns = [ "doc-cheat-sheet*", + "_dev/*", ".venv*", ] # Adds custom CSS files, located remotely or in 'html_static_path'. -# html_css_files = [ -# "https://assets.ubuntu.com/v1/d86746ef-cookie_banner.css", -# ] +html_css_files = [ + "css/custom.css", +] # Adds custom JavaScript files, located remotely or in 'html_static_path'. # html_js_files = [ diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 7a544e9..818955b 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -1,49 +1,147 @@ --- myst: html_meta: - description: "How to contribute to Livepatch documentation." + description: "Contribute to Livepatch documentation. Learn how to improve docs, give back to the community, and expand your technical skills." --- -(contribute-contribute-to-our-docs)= +(contribute-to-docs)= -# Contribute to our docs +# Contribute to our documentation -Our documentation is a community effort, published on the [Livepatch docs](https://ubuntu.com/security/livepatch/docs). +We warmly welcome your engagement with the Livepatch community and appreciate all contributions, suggestions, and feedback. There are many reasons why you should contribute to the Livepatch documentation. -**We warmly welcome community contributions, suggestions, fixes and constructive feedback.** +- **Improve your skills** -Contributing to documentation can be a fantastic way to get started as a contributor to open source projects, no matter your level of experience! + Contributing to the Livepatch documentation is a great way to improve your documentation and technical communication skills. You will get experience writing clear, concise documentation that is helpful to the Livepatch community, and you will have the opportunity to learn about writing documentation that focuses on user needs. -We hope to make it as easy as possible to contribute. If you need help at all with the contribution process, please let us know! +- **Give back to the community** -## Publishing and hosting + By contributing to the Livepatch documentation, you foster a supportive community and can help other users learn about Livepatch. Your contributions make a difference to other Livepatch users. -The documentation for _Livepatch_ is -[hosted in GitHub](https://github.com/canonical/livepatch-docs) and -rendered via [Read the Docs](https://about.readthedocs.com/). +- **Learn more about Livepatch** -We use the [Sphinx documentation generator](https://www.sphinx-doc.org/) to create our documentation, which is written in [MyST Markdown](https://mystmd.org/) and built from [Canonical's Sphinx Starter Pack](https://github.com/canonical/sphinx-docs-starter-pack). + Contributing to the Livepatch documentation can help you broaden your understanding of Livepatch and its related technologies. Writing documentation often involves exploring new features and investigating potential problems or challenges users may face, which can help you learn more about how Livepatch works and how users interact with it. -For further details, see the [Starter Pack documentation](https://canonical-starter-pack.readthedocs-hosted.com/stable/). +We believe that everyone has something valuable to contribute, no matter your level of experience, and we hope to make it as easy as possible to contribute. If you find any part of our process does not work well for you, please let us know. + +## Prerequisites + +There are some prerequisites to contributing to the Livepatch documentation. + +- **Code of Conduct**: You will need to read and agree to the Ubuntu [Code of Conduct](https://ubuntu.com/community/ethos/code-of-conduct). By participating, you implicitly agree to abide by the Code of Conduct. + +- **GitHub account**: You need a [GitHub account](https://github.com/) to create issues, comment, reply, or submit contributions. + + You do not need to know git before you start, and you definitely do not need to work on the command line if you do not want to. Many documentation tasks can be done using [GitHub's web interface](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files). On the command line, we use the standard "fork and pull" process. + +- **Licensing**: The first time you contribute to a Canonical project, you will need to sign the Canonical License agreement (CLA). If you have already signed it, for example when contributing to another Canonical project, you do not need to sign it again. + + This license protects your copyright over your contributions, including the right to use them elsewhere, but grants us (Canonical) permission to use them in our project. You can read [more about the CLA](https://ubuntu.com/legal/contributors) before you [sign the CLA](https://ubuntu.com/legal/contributors/agreement). + +## Livepatch Docs overview and Diátaxis + +The Livepatch documentation is [hosted in GitHub](https://github.com/canonical/livepatch-docs) and rendered on [Read the Docs](https://about.readthedocs.com/). You need to create a GitHub account to contribute, but you do not need a Read the Docs account. + +We use the [Sphinx documentation generator](https://www.sphinx-doc.org/) to create our documentation, which is written in [MyST Markdown](https://mystmd.org/) and built from [Canonical's Sphinx Starter Pack](https://github.com/canonical/sphinx-docs-starter-pack). For further details, see the [Starter Pack documentation](https://canonical-starter-pack.readthedocs-hosted.com/stable/). + +Our navigational structure, style, and the content of our documentation follows the [Diátaxis](https://diataxis.fr/) systematic framework for technical documentation authoring. This splits documentation pages into tutorials, how-to guides, reference material and explanatory text: + +- **Tutorials** are lessons that accomplish specific tasks through *doing*. They help with familiarity and place users in the safe hands of an instructor. +- **How-to guides** are recipes, showing users how to achieve something, helping them get something done. A *How-to guide* has no obligation to teach. +- **Reference** material is descriptive, providing facts about functionality that is isolated from what needs to be done. +- **Explanation** is discussion, helping users gain a deeper or better understanding of Livepatch, including *how* and *why* Livepatch functions the way it does. + +For further details on our Diátaxis strategy, see [Diátaxis, a new foundation for Canonical documentation](https://ubuntu.com/blog/diataxis-a-new-foundation-for-canonical-documentation). + +Improving our documentation and applying the principles of Diátaxis are on-going tasks. There is a lot to do, and we do not want to deter anyone from contributing to our docs. If you do not know whether something should be a tutorial, how-to guide, reference doc or explanatory text, either ask on the forum or publish what you are thinking. Changes are easy to make, and every contribution helps. + +## Ways to contribute + +Most Livepatch documentation contributions are made on GitHub. There are several ways you can contribute: + +- [Find an issue](https://github.com/canonical/livepatch-docs/issues) or [create your own issue](https://github.com/canonical/livepatch-docs/issues/new) to work on +- Fix an issue directly and [create a pull request (PR)](https://github.com/canonical/livepatch-docs/pulls) +- Report a bug or provide feedback by [creating an issue](https://github.com/canonical/livepatch-docs/issues/new) in GitHub +- Ask a question or help other Livepatch community members on [Discourse](https://discourse.ubuntu.com/) + +You can also use the "Give feedback" button at the top of every documentation page to report a problem. Please give us as much information as you can to help us address the problem. + +## How to contribute + +If you are new to contributing with Git/GitHub or the command line, see the [Getting Started guide](https://canonical-open-documentation-academy.readthedocs.io/en/latest/docs/howto/get-started/using_git/) from the Canonical Open Documentation Academy for an overview. + +This section provides basic instructions of how to contribute to our documentation and build locally using GitHub and the command line. + +### Prerequisites + +To build the documentation locally, you will first need to install some necessary dependencies on your system with the following commands: + +```bash +sudo apt update +sudo apt install make python3 python3-venv python3-pip +``` + +### Build, preview, and test the documentation + +We use `make` to build, preview, and test the documentation. You can see all the options in the Makefile, but here is the basic process: + +#### Build + +To build the docs: + +```bash +make html +``` + +The first time you run this command, it will build everything. This includes installing all of the Python dependencies into the Python virtual environment. When you run it again, it will only update the changed files. This is usually fine, but sometimes causes issues if you have made a lot of structural changes to the documentation. You can also run a clean build, which deletes the existing output files and the Python environment, and then builds the full documentation again. + +To run a clean build: + +```bash +make clean html +``` + +#### Preview + +After your build succeeds, preview it locally to see how the published documentation will look: + +```bash +make run +``` + +This command builds the documentation and serves it at `http://127.0.0.1:8000/`. When you change a documentation file and save it, the documentation will be automatically rebuilt and refreshed in the browser. + +Previewing the docs makes it easier to see how the finalized, published documentation will look. For most changes, you should preview your docs so you can make sure everything (especially the formatting) looks as you expected it to. + +#### Test + +You can do this before or after previewing the docs. We have two main tests which need to pass for our documentation: + +```bash +make spelling +make linkcheck +``` + +These tests make sure everything is spelled correctly and that all links go to a valid URL. Note that these tests will also be run automatically on your pull request in GitHub. + +### Submit a pull request + +Once you have finished creating and testing your changes, create a pull request against the [Livepatch documentation repository](https://github.com/canonical/livepatch-docs). + +Your submitted issues and pull requests will be reviewed in due time. If you submit a PR, we have some automatic checks that will run against your PR to check for consistent style and language. However, do not let this be a barrier to your contribution. You can still submit contributions to the best of your ability, and if something is inconsistent, we will help you fix it. ## Contributions we accept -We especially value contributions that improve the documentation's clarity, -accuracy, and usefulness. If you spot a problem, you can report it to us using -the "Give feedback" button at the top of every documentation page. Please give -us as much information as you can to help us address the problem. +We especially value contributions that improve the documentation's clarity, accuracy, and usefulness. -If the issue is one of the following very small issues, and you want to fix it -yourself, you can submit a pull request (PR) with your changes directly in the -[GitHub web interface](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files): +If the issue is one of the following small issues, and you want to fix it yourself, you can submit a pull request with your changes directly in the [GitHub web interface](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files): - Typo corrections - Minor technical corrections - Broken link fixes - Small clarifications -For changes larger than those, we require contributor PRs to be tied to an issue. -Examples of changes that require an issue are things like: +For changes larger than those, we require contributor PRs to be tied to an issue. Examples of changes that require an issue include: - Adding new sections or pages - Restructuring existing pages @@ -51,38 +149,36 @@ Examples of changes that require an issue are things like: - Significant technical corrections or updates - Feature additions or enhancements -## Contributions we don't accept +## Contributions we do not accept We reserve the right to reject any contribution at our own discretion where: -**The outline of proposed work has not already been agreed by a maintainer.** -: To protect maintainers' limited time, we do not accept unsolicited contributions. A PR must be tied to a valid and agreed issue unless it only makes a small change. Submitting an issue after a PR doesn't *guarantee* that we will then accept the PR. +The outline of proposed work has not already been agreed by a maintainer. +: To protect maintainers' limited time, we do not accept unsolicited contributions. A PR must be tied to a valid and agreed issue unless it only makes a small change. Submitting an issue after a PR does not guarantee that we will then accept the PR. -**The pull request far exceeds the scope of what was agreed.** +The pull request far exceeds the scope of what was agreed. : "Scope creep" makes it much harder to review and accept changes. If a pull request becomes too large, we may ask you to break it into multiple smaller PRs. Stick to the scope of the original issue as much as you can -- if you discover more changes need to be made, discuss them in the PR or the original issue. A new PR can be submitted with the extra fixes. -**The contribution makes changes without value.** -: To have value, changes must be a *specific and concrete improvement* over what already exists. We don't accept generic "polishing" (e.g. substituting synonyms, rewording without adding clarity). If your contribution contains *some* of these, we will ask you to undo them -- but will gladly accept the remaining parts of your pull request that are real improvements. If your contribution *only* contains low-value changes, it will be rejected. +The contribution makes changes without value. +: To have value, changes must be a *specific and concrete improvement* over what already exists. We do not accept generic "polishing" (for example, substituting synonyms, rewording without adding clarity). If your contribution contains *some* of these, we will ask you to undo them -- but will gladly accept the remaining parts of your pull request that are real improvements. If your contribution *only* contains low-value changes, it will be rejected. -**We deem the contribution to be AI generated.** -: We don't want any part of our documentation to look or feel like it was produced by AI. Therefore, if what you submitted cannot be easily distinguished from AI output, it does not meet our contribution requirements. +We deem the contribution to be AI generated. +: We do not want any part of our documentation to look or feel like it was produced by AI. Therefore, if what you submitted cannot be easily distinguished from AI output, it does not meet our contribution requirements. -**The issue the pull request is addressing was assigned to someone else.** -: We want to make this a safe place for contributors to work on issues in their own time and without pressure. Please treat others as you'd want to be treated. If you like an issue someone else is working on, let us know and we'll create a similar one for you. +The issue the pull request is addressing was assigned to someone else. +: We want to make this a safe place for contributors to work on issues in their own time and without pressure. Please treat others as you would want to be treated. If you like an issue someone else is working on, let us know and we will create a similar one for you. ## AI policy -The Livepatch documentation has been created by humans, for humans. The occasional "jagged edges" you might find (typos, slightly unconventional wording, humour) represent the very human voices of the people who collaborated -to create it. We don't want to average those away by passing the documentation through LLMs. +The Livepatch documentation has been created by humans, for humans. The occasional "jagged edges" you might find (typos, slightly unconventional wording, humour) represent the very human voices of the people who collaborated to create it. We do not want to average those away by passing the documentation through LLMs. -This policy exists to protect our readers, our community of contributors, and the project maintainers. -As AI continues to evolve, we will update these guidelines accordingly. +This policy exists to protect our readers, our community of contributors, and the project maintainers. As AI continues to evolve, we will update these guidelines accordingly. (contribute-acceptable-use-of-ai)= ### Acceptable use of AI -We don't ban our contributors from using AI. However, we do expect anyone contributing to this project to use it responsibly, as a helper, and not as something that replaces them. Some examples of acceptable usage include: +We do not ban our contributors from using AI. However, we do expect anyone contributing to this project to use it responsibly, as a helper, and not as something that replaces them. Some examples of acceptable usage include: - Using AI as a spellchecker or grammar helper - Using it to help with translation into English @@ -90,7 +186,7 @@ We don't ban our contributors from using AI. However, we do expect anyone contri - Using it adversarially, to point out missing sections - Ensuring formatting adheres to our style guide -We want to be open and transparent with our users about the way in which AI is or is not used in the our documentation. We (the maintainers) have been experimenting with the ways in which AI can be used to improve the experience for our readers, and we don't object to contributors doing the same -- with the following caveats: +We want to be open and transparent with our users about the way in which AI is or is not used in our documentation. We (the maintainers) have been experimenting with the ways in which AI can be used to improve the experience for our readers, and we do not object to contributors doing the same -- with the following caveats: 1. **Agreement**: Any such work you do *must* be tied to an issue, and be agreed as valid and necessary with the maintainers *before* you start. Only maintainers are exempt from this rule, since they are most familiar with the project and its scope. @@ -98,17 +194,15 @@ We want to be open and transparent with our users about the way in which AI is o 3. **Accessibility**: Issues marked as "good first issues" and "Open Documentation Academy" are *specifically* created and intended for people new to Open Source to get started in a safe place. These issues are easy to complete, well-described, and self-contained for new contributors to learn from. These issues are not for AI. -4. **Responsibility**: Make sure that even if you use AI, you are still adding value based on your own personal skills and competency. You must understand what you're submitting, even if you used an LLM to help you. +4. **Responsibility**: Make sure that even if you use AI, you are still adding value based on your own personal skills and competency. You must understand what you are submitting, even if you used an LLM to help you. -## Thank you! +## Thank you -Lastly, we would like to thank you for spending your time to help make the -Livepatch documentation better. Every step in the right direction is a step -worth taking, no matter how large or small. +Lastly, we would like to thank you for spending your time to help make the Livepatch documentation better. Every step in the right direction is a step worth taking, no matter how large or small. ```{toctree} :maxdepth: 1 :hidden: self -``` +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 1127e19..787ada8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,37 +1,20 @@ --- myst: html_meta: - description: "Livepatch documentation home." + description: "Livepatch documentation home. Comprehensive guides for Canonical's live kernel patching solution for Ubuntu." --- +```{include} ../README.md -# Livepatch Documentation +```` -[Canonical Livepatch](https://ubuntu.com/security/livepatch) patches high and critical Linux kernel vulnerabilities, removing the immediate need to reboot to upgrade the kernel, and instead allowing the downtime to be scheduled. It is a part of the [Ubuntu Pro](https://ubuntu.com/pro) offering. - -The Ubuntu Livepatch offering consists of the [client application](/client/index.md), the Livepatch service hosted by Canonical and an optional [on-prem server](/server/index.md). The client runs on machines, periodically checks for available patches, downloads, verifies and installs them. - -Canonical Livepatch is meant for critical infrastructure, where unscheduled downtime is to be avoided. By applying live kernel patches for high and critical kernel vulnerabilities, upgrades can be scheduled at a suitable time. - -If you're using [Ubuntu Pro](http://ubuntu.com/pro), then you'll have access to two additional Livepatch features. - -1. Delayed updates for your [Livepatch clients](/client/index.md), providing further security and protection. -2. Access to the [on-prem server](/server/index.md). - -## [Livepatch Client](/client/index.md) - -Livepatch is the client side software that runs on individual machines and periodically checks for the availability of kernel patches. Once a patch becomes available, it is downloaded, verified and applied to the current kernel. - -## [Livepatch On-prem](/server/index.md) - -Complex enterprise environments often follow policies that require a gradual roll-out of updates to reduce risk, or have high-security isolated environments that need to be updated. Livepatch on-prem allows an organization to define a rollout policy and remain in full control of which machines will get updated and when. To keep your machines up-to-date, the on-premises service regularly syncs with Livepatch hosted by Canonical and obtains the latest patches. It then deploys the patches gradually in as many stages as required. +--------- ```{toctree} -:titlesonly: -:maxdepth: 2 -:glob: :hidden: +:maxdepth: 2 +self Client Server ``` @@ -43,4 +26,4 @@ Server Release Notes Contribute Support -``` \ No newline at end of file +``` diff --git a/docs/redirects.txt b/docs/redirects.txt index e4225ef..f7e7241 100644 --- a/docs/redirects.txt +++ b/docs/redirects.txt @@ -8,7 +8,8 @@ # Redirects for the 3rd-level Diátaxis restructure -"client/explanation/how-livepatching-works.md" "client/explanation/architecture/how-livepatching-works.md" +"client/explanation/how-livepatching-works.md" "client/explanation/architecture/how-live-patching-works.md" +"client/explanation/architecture/how-livepatching-works.md" "client/explanation/architecture/how-live-patching-works.md" "client/explanation/what-are-livepatch-tiers.md" "client/explanation/architecture/what-are-livepatch-tiers.md" "client/explanation/what-kind-of-updates-are-not-provided-by-livepatch.md" "client/explanation/architecture/what-kind-of-updates-are-not-provided-by-livepatch.md" "client/explanation/what-kind-of-updates-are-provided-by-livepatch.md" "client/explanation/architecture/what-kind-of-updates-are-provided-by-livepatch.md" @@ -83,7 +84,7 @@ "livepatch/explanation/do-i-need-to-reboot.md" "client/explanation/troubleshooting/do-i-need-to-reboot.md" "livepatch/explanation/get-more-help.md" "support/get-more-help.md" "livepatch/explanation/how-cves-are-rated.md" "client/explanation/security/how-cves-are-rated.md" -"livepatch/explanation/how-livepatching-works.md" "client/explanation/architecture/how-livepatching-works.md" +"livepatch/explanation/how-livepatching-works.md" "client/explanation/architecture/how-live-patching-works.md" "livepatch/explanation/index.md" "client/explanation/index.md" "livepatch/explanation/livepatch-security-notices.md" "client/explanation/security/livepatch-security-notices.md" "livepatch/explanation/report-bugs.md" "support/report-bugs.md" diff --git a/docs/release-notes/client/index.md b/docs/release-notes/client/index.md index a51a6da..64251dd 100644 --- a/docs/release-notes/client/index.md +++ b/docs/release-notes/client/index.md @@ -1,10 +1,11 @@ --- myst: html_meta: - description: "Release Notes - technical reference for Livepatch client." + description: "Release notes for the Canonical Livepatch Client. Find new features, bug fixes, and changes for each client release." --- +(release-notes-client)= -(release-notes-client-release-notes-for-the-canonical-livepatch-client)= +# Livepatch Client release notes -# Release Notes for the Canonical Livepatch Client +The Canonical Livepatch Client runs on Ubuntu systems to apply live kernel patches without requiring a system reboot. The client checks for available patches, downloads them from the Livepatch Server, and applies them to the running kernel. diff --git a/docs/release-notes/index.md b/docs/release-notes/index.md index 9572972..4574ab7 100644 --- a/docs/release-notes/index.md +++ b/docs/release-notes/index.md @@ -1,23 +1,18 @@ --- myst: html_meta: - description: "Release notes for Livepatch client and server." + description: "Release notes for Canonical Livepatch, covering client and server components. Find new features, bug fixes, and changes across all releases." --- (release-notes)= # Release notes -Find release notes for both Livepatch components: - -- [Client release notes](/release-notes/client/index.md) -- [Server release notes](/release-notes/server/index.md) +Release notes documenting new features, bug fixes, and changes across all Livepatch Client and server releases. ```{toctree} :titlesonly: -:maxdepth: 2 -:glob: -:hidden: +:maxdepth: 1 Client Server diff --git a/docs/release-notes/server/index.md b/docs/release-notes/server/index.md index 5851117..f21be58 100644 --- a/docs/release-notes/server/index.md +++ b/docs/release-notes/server/index.md @@ -1,52 +1,48 @@ --- myst: html_meta: - description: "Release Notes - technical reference for Livepatch server." + description: "Release notes for the Canonical Livepatch Server K8s charm. Find new features, bug fixes, and changes for each server release." --- +(release-notes-server)= -(release-notes-server-release-notes-for-the-canonical-livepatch-server-k8s-charm)= +# Livepatch Server release notes -# Release Notes for the Canonical Livepatch Server (K8s charm) +The [Livepatch Server K8s charm](https://charmhub.io/canonical-livepatch-server-k8s) is the recommended method for deploying the Livepatch Server on Kubernetes. The charm configures and runs the Livepatch Server, which serves live kernel patches and associated metadata to clients. Use the `latest/stable` channel charm for production environments. -The [Livepatch Server K8s charm](https://charmhub.io/canonical-livepatch-server-k8s) is the easiest and the recommended way to deploy Livepatch Server on K8s. This charm configures and runs the Livepatch Server, which serves livepatches and associated metadata to clients. Use the latest/stable channel charm for production environments. +## v1.20.0 -## Releases +### New features -
v1.20.0 -What's New: - -- The server now returns excluded CVEs grouped by LSN ID when client configuration settings block patches. This is done with the help of the CVE service which now exposes LSN information. +- Excluded CVEs are now returned grouped by LSN ID when client configuration settings block patches. This integration uses the CVE service, which now exposes LSN information. - Database query optimizations for listing patches. -- A more robust set of input validation rules for APIs +- More robust input validation rules for API endpoints. -
-
v1.18.1 -What's New: +## v1.18.1 -- Scripts for migrating Livepatch server configuration from the old format used by the reactive machine charms to the new format. -- Patch ping data can now be configured to write into a different Influx bucket. A new configuration value `PingBucket`, determines the bucket for ping data. If left blank, the pings are sent to bucket based on the old `Bucket` value for backwards compatibility. This helps to maintain separate retention policies for Ping data and server KPI metrics. +### New features -Bug Fixes: +- Scripts for migrating Livepatch Server configuration from the old reactive machine charm format to the new format. +- A new configuration value, `PingBucket`, determines the Influx bucket for patch ping data. If left blank, pings are sent to the bucket specified by the existing `Bucket` value for backwards compatibility. This enables separate retention policies for ping data and server KPI metrics. -- Fixed race condition in PostgreSQL patch storage. +### Bug fixes -
-
v1.17.17 -What's New: +- Fixed a race condition in PostgreSQL patch storage. -- Facilitate UX improvements for patch-delay and cutoff-date features. +## v1.17.17 -Bug Fixes: +### New features -- Incorrect increment of the Patch Sync progress indicator, when patches are skipped due to errors, is fixed. +- UX improvements for the patch-delay and cutoff-date features. -
-
v1.17.12 -What’s New: +### Bug fixes -- Added caching support for CVE endpoints using hashes and `ETag` and `If-None-Match` headers. -- Timeout for the CVE sync client is now configurable. -- Security events (authentication, authorization, user and system related) are logged by the Livepatch server. +- Fixed an issue where the patch sync progress indicator incremented incorrectly when patches were skipped due to errors. + +## v1.17.12 -
+### New features + +- Added caching support for CVE endpoints using hashes and `ETag` and `If-None-Match` headers. +- The timeout for the CVE sync client is now configurable. +- Security events (authentication, authorization, user and system related) are now logged by the Livepatch Server. diff --git a/docs/server/explanation/architecture/access-control.md b/docs/server/explanation/architecture/access-control.md index 788e2c7..71257fe 100644 --- a/docs/server/explanation/architecture/access-control.md +++ b/docs/server/explanation/architecture/access-control.md @@ -1,16 +1,17 @@ --- myst: html_meta: - description: "Access Control - learn about this topic in Livepatch on-prem." + description: "Understand access control in the Livepatch on-premises server including token-based authentication, machine tiers, and rollout management." --- - (server-explanation-access-control)= -# Access Control +# Access control + +> See also: {ref}`Authentication and authorization `, {ref}`Use the Livepatch Client with the on-premises server ` -Access to a Livepatch on-prem instance is gated such that clients are authenticated before they can download patches. Access control is managed by means of generated tokens. These tokens act as a way of both authenticating client machines and assigning a tier to each machine, i.e. determining how and when patches get rolled out. +Access to a Livepatch on-premises instance is gated so that clients are authenticated before they can download patches. Access control is managed through generated tokens. These tokens authenticate client machines and assign a tier to each machine, determining how and when patches are rolled out. -See this [how-to](/server/how-to-guides/operations/use-livepatch-client-with-on-prem-server.md) to understand how to generate tokens. +See {ref}`Use the Livepatch Client with the on-premises server ` to learn how to generate tokens. -For a technical reference of all authentication mechanisms (Basic Auth, Macaroons, resource tokens, sync tokens) and the cryptographic technologies they use, see [Authentication and authorization](/server/reference/authentication/authentication.md). +For a technical reference of all authentication mechanisms -- Basic Auth, macaroons, resource tokens, and sync tokens -- and the cryptographic technologies they use, see {ref}`Authentication and authorization `. \ No newline at end of file diff --git a/docs/server/explanation/architecture/index.md b/docs/server/explanation/architecture/index.md index 28d82c6..c5b52ff 100644 --- a/docs/server/explanation/architecture/index.md +++ b/docs/server/explanation/architecture/index.md @@ -1,28 +1,24 @@ --- myst: html_meta: - description: "Security model, lifecycle, and access control of the server." + description: "Understand the Livepatch on-premises server architecture including its security model, lifecycle, and access control system." --- - (server-explanation-architecture)= # Architecture -Security model, lifecycle, and access control of the server. +The Livepatch on-premises server is designed around a clear security model with defined trust boundaries, an update lifecycle for distributing security patches, and a token-based access control system. This section explains each of these concepts. -## In this section +## Architecture concepts -- [Security Overview](/server/explanation/architecture/security-overview.md) -- [Security Lifecycle](/server/explanation/architecture/security-lifecycle.md) -- [Access Control](/server/explanation/architecture/access-control.md) +Learn about the security architecture, how updates are delivered, and how access is governed. ```{toctree} :titlesonly: :maxdepth: 1 -:hidden: -Security overview -Security lifecycle -Access control -``` +Security overview +Security lifecycle +Access control +``` \ No newline at end of file diff --git a/docs/server/explanation/architecture/security-lifecycle.md b/docs/server/explanation/architecture/security-lifecycle.md index 8227bf7..5a7ad9c 100644 --- a/docs/server/explanation/architecture/security-lifecycle.md +++ b/docs/server/explanation/architecture/security-lifecycle.md @@ -1,21 +1,22 @@ --- myst: html_meta: - description: "Security Lifecycle - learn about this topic in Livepatch on-prem." + description: "Understand the security lifecycle of the Livepatch on-premises server including update delivery for the charm, snap, and OCI image distribution channels." --- - (server-explanation-security-lifecycle)= -# Security Lifecycle +# Security lifecycle + +> See also: {ref}`Security overview `, {ref}`Report server vulnerabilities ` -The on-premises Livepatch Server is released as a Kubernetes charm and a snap. Releases are made ad-hoc as features and bug fixes are implemented. When a security vulnerability in an upstream dependency is detected, a best-case effort is made to upgrade the dependency to the latest version that fixes the vulnerability. This security fix is then included in the next ad-hoc release. +The on-premises Livepatch Server is released as a Kubernetes charm and a snap. Releases are made ad-hoc as features and bug fixes are implemented. When a security vulnerability in an upstream dependency is detected, a best-effort attempt is made to upgrade the dependency to the latest version that fixes the vulnerability. This security fix is then included in the next ad-hoc release. A fix for a reported security issue that is directly present in the on-premises Livepatch Server can be prioritized and released as a minor version upgrade for both the charm and snap. ## Charm -The Livepatch charm (`canonical-livepatch-server-k8s`) is published on [Charmhub](https://charmhub.io/canonical-livepatch-server-k8s). Security updates are delivered as new charm revisions on the `latest/stable` channel. Container image updates are bundled with charm revisions — each revision references specific OCI image versions. +The Livepatch charm (`canonical-livepatch-server-k8s`) is published on [Charmhub](https://charmhub.io/canonical-livepatch-server-k8s). Security updates are delivered as new charm revisions on the `latest/stable` channel. Container image updates are bundled with charm revisions -- each revision references specific OCI image versions. To check for and apply updates: @@ -35,7 +36,7 @@ Schema migrations are leader-only operations executed in a separate container (` ## Snap -The Livepatch Server snap is published on the [Snap Store](https://snapcraft.io/canonical-livepatch-server). It is recommended to install the snap from the `latest/stable` channel. +The Livepatch Server snap is published on the [Snap Store](https://snapcraft.io/canonical-livepatch-server). Install the snap from the `latest/stable` channel. By default, the snapd daemon checks for updates four times a day and applies them automatically. This default behavior can be modified using the `snap refresh` command to manually check for updates, postpone updates, schedule update windows, or roll back applied updates. For more information, see the [snap documentation on managing updates](https://snapcraft.io/docs/how-to-guides/manage-snaps/manage-updates/#refresh-update-control). @@ -45,11 +46,11 @@ Modifying the default auto-update behavior could leave systems vulnerable to sec sudo snap refresh canonical-livepatch-server --channel=latest/stable ``` -## OCI image (ROCK) +## OCI image The Livepatch Server OCI image is published for use in Kubernetes deployments managed by the charm. The image is built on a minimal `bare` base with the following properties: - Compiled with `CGO_ENABLED=0` (no C library dependencies) - Includes only `ca-certificates`, `logrotate`, `busybox-static`, and `base-files` -Container image updates are delivered through new charm revisions that reference updated image digests. +Container image updates are delivered through new charm revisions that reference updated image digests. \ No newline at end of file diff --git a/docs/server/explanation/architecture/security-overview.md b/docs/server/explanation/architecture/security-overview.md index 3ee6ae4..c8c5b56 100644 --- a/docs/server/explanation/architecture/security-overview.md +++ b/docs/server/explanation/architecture/security-overview.md @@ -1,60 +1,65 @@ --- myst: html_meta: - description: "Security Overview - learn about this topic in Livepatch on-prem." + description: "Explore the security architecture of the Livepatch on-premises server including trust boundaries, authentication, cryptographic mechanisms, and security recommendations." --- - (server-explanation-security-overview)= -# Security Overview +# Security overview + +> See also: {ref}`Authentication and authorization `, {ref}`Security lifecycle `, {ref}`Harden your deployment ` -This document provides an overview of the security features and practices implemented within the on-premises Livepatch Server. It aims to give operators a general perspective on how security is handled, outlining built-in protections, authentication mechanisms, and pointing to more detailed documentation for specific cryptographic approaches and operational guides. +The Livepatch on-premises server synchronizes kernel patches from Canonical's hosted Livepatch service and serves them to Livepatch Clients within the operator's infrastructure. It is distributed as a Kubernetes charm and a snap package. -The on-premises Livepatch Server is distributed as a Kubernetes charm and a snap package. It synchronizes kernel patches from Canonical's hosted Livepatch service and serves them to Livepatch clients within the operator's infrastructure. +This document provides an overview of the security features and practices implemented in the on-premises Livepatch Server. It describes the system from a security perspective, outlines built-in protections, and references more detailed documentation for specific cryptographic approaches and operational guidance. -## **System overview from the perspective of security** +## System overview -The on-premises Livepatch Server acts as the central component in an on-premises Livepatch deployment, coordinating between administrators, clients, Canonical's hosted service, and external services. The following components and trust boundaries are relevant to the security posture of the system: +The on-premises Livepatch Server acts as the central component in an on-premises Livepatch deployment, coordinating between administrators, clients, Canonical's hosted service, and external services. ### Components -- **On-premises Livepatch Server**: The core service that manages patches and serves them to clients within the operator's infrastructure. It exposes HTTP APIs for **Livepatch Client**, **Livepatch Admin Tool**:, and server-to-server communication. -- **PostgreSQL Database**: Stores all persistent data including authentication tokens, patch metadata, machine registrations, and macaroon root keys. -- **Patch Storage Backend**: Stores patch binary files. Supports multiple backends: filesystem, PostgreSQL, OpenStack Swift, and Amazon S3. +The following components are part of a Livepatch on-premises deployment: + +- **On-premises Livepatch Server**: The core service that manages patches and serves them to clients within the operator's infrastructure. It exposes HTTP APIs for the Livepatch Client, the Livepatch Admin Tool, and server-to-server communication. +- **PostgreSQL database**: Stores all persistent data including authentication tokens, patch metadata, machine registrations, and macaroon root keys. +- **Patch storage backend**: Stores patch binary files. Supports multiple backends: filesystem, PostgreSQL, OpenStack Swift, and Amazon S3. - **Livepatch Admin Tool**: CLI tool used by administrators to manage the server (tokens, tiers, patches, webhooks). - **Livepatch Client**: The endpoint agent that queries the server for patches and applies them to the running kernel. - **Canonical hosted Livepatch service**: Canonical's hosted Livepatch service from which the on-premises server synchronizes patch data. -- **Ubuntu Pro Service**: External service used to validate Ubuntu Pro resource tokens from clients. +- **Ubuntu Pro service**: External service used to validate Ubuntu Pro resource tokens from clients. ### Trust boundaries -- **Client network to Livepatch Server**: In on-premises deployments, Livepatch clients and the server typically reside on the same internal network. TLS between clients and the server is optional — operators may choose to forgo TLS if the internal network is trusted. When TLS is required, termination is handled by a reverse proxy or Kubernetes ingress controller in front of the server. The charm supports ingress via the `nginx-route` integration (legacy) or the `ingress` integration (modern, using Traefik or Gateway API Integrator). +The following trust boundaries are relevant to the security posture of the system: + +- **Client network to Livepatch Server**: In on-premises deployments, Livepatch Clients and the server typically reside on the same internal network. TLS between clients and the server is optional -- operators may choose to forgo TLS if the internal network is trusted. When TLS is required, termination is handled by a reverse proxy or Kubernetes ingress controller in front of the server. The charm supports ingress via the `nginx-route` integration (legacy) or the `ingress` integration (modern, using Traefik or the Gateway API Integrator). - **Admin network to Livepatch Server**: Admin API requests should originate from trusted networks. Authentication is enforced through macaroons obtained via Basic Auth. - **Livepatch Server to PostgreSQL**: Database connections cross a trust boundary. TLS is supported but optional for this connection. - **Livepatch Server to external services**: Connections to the Ubuntu Pro service enforce TLS. The charm supports configuring a custom CA certificate (`contracts.ca`) for verifying the Pro service certificate, which is installed into the container's system CA trust store. Connections to patch storage backends (S3, Swift) support TLS. - **Livepatch Server to Pro Airgapped Server**: For air-gapped environments, the charm can integrate with a Pro Airgapped Server via the `pro-airgapped-server` Juju relation to validate resource tokens without external network access. - **Patch synchronization with Canonical's hosted service**: The on-premises server synchronizes patches from Canonical's hosted Livepatch service using either a contract resource token or a sync token for authentication. Resource tokens are obtained from the Ubuntu Pro contracts service using the `get-resource-token` Juju action (charm) or by setting the contract token via `snap set canonical-livepatch-server token=` (snap), which triggers the configure hook to exchange it for a resource token automatically. Sync tokens are issued by the upstream server's admin tool. The active token is configured via `patch-sync.token`. Proxy support is available for environments where direct connectivity is restricted (`patch-sync.proxy.*` configuration). -- **Federation (hierarchical on-premises deployments)**: In federated deployments, a designated on-premises server pulls patches from Canonical's hosted service/ Downstream on-premises servers (for example, in different data centres) pull patches from this designated server. To authorize these connections, the administrator uses the admin tool to issue sync tokens from the upstream server to each downstream server. . +- **Federation (hierarchical on-premises deployments)**: In federated deployments, a designated on-premises server pulls patches from Canonical's hosted service. Downstream on-premises servers (for example, in different data centers) pull patches from this designated server. To authorize these connections, the administrator uses the admin tool to issue sync tokens from the upstream server to each downstream server. -## **Built-in protection** +## Built-in protections The Livepatch Server incorporates several mechanisms to ensure the security of its operations: -- **Multi-layered authentication**: The server supports multiple authentication methods depending on the API consumer: macaroons (Basic Auth-backed) for admin users, machine tokens and Ubuntu Pro resource tokens for clients, and contract resource tokens or sync tokens for patch synchronization with upstream servers. For more details, refer to the [Authentication reference](/server/reference/authentication/authentication.md). +- **Multi-layered authentication**: The server supports multiple authentication methods depending on the API consumer: macaroons (Basic Auth-backed) for admin users, machine tokens and Ubuntu Pro resource tokens for clients, and contract resource tokens or sync tokens for patch synchronization with upstream servers. For more details, refer to the {ref}`Authentication reference `. - **Request rate limiting**: An HTTP governor limits concurrent request processing and queues excess requests up to a configurable burst limit, protecting against overload and resource exhaustion. -- **Input validation**: All API inputs are validated using strict schemas with regex patterns, length limits, and type checks across 10 validation modules. This mitigates injection attacks and malformed request handling. +- **Input validation**: All API inputs are validated using strict schemas with regex patterns, length limits, and type checks across validation modules. This mitigates injection attacks and malformed request handling. - **Structured security event logging**: All authentication successes and failures, authorization decisions, token lifecycle events, admin activity, and system events are logged as structured JSON in compliance with OWASP logging standards. - **Prometheus monitoring**: The server exposes operational metrics including authentication durations, request latencies, database errors, queue depths, and overload counts through a `/metrics` endpoint. -- **(charm) Log redaction**: The Kubernetes charm includes a log redaction module that scrubs sensitive data from charm logs before they reach any handler. Redacted patterns include database connection URIs with embedded credentials, HTTP authorization headers, key-value pairs containing passwords/tokens/API keys, and specific environment variables carrying secrets (e.g., `LP_CONTRACTS_PASSWORD`, `LP_AUTH_BASIC_USERS`, `LP_DATABASE_CONNECTION_STRING`). +- **(charm) Log redaction**: The Kubernetes charm includes a log redaction module that scrubs sensitive data from charm logs before they reach any handler. Redacted patterns include database connection URIs with embedded credentials, HTTP authorization headers, key-value pairs containing passwords/tokens/API keys, and specific environment variables carrying secrets (for example, `LP_CONTRACTS_PASSWORD`, `LP_AUTH_BASIC_USERS`, `LP_DATABASE_CONNECTION_STRING`). - **(charm) Grafana dashboards**: The charm provides a `metrics-endpoint` integration for Prometheus scraping and a `grafana-dashboard` integration that ships a pre-built dashboard tracking authentication metrics, token usage by type, contracts service errors, and request performance. -- **(charm) Log forwarding**: The charm supports forwarding application logs to Loki via the `log-proxy` (with Promtail, for Juju < 3.4) or `logging` (direct log forwarding, for Juju >= 3.4) integrations, enabling centralized log collection. +- **(charm) Log forwarding**: The charm supports forwarding application logs to Loki via the `log-proxy` integration (with Promtail, for Juju < 3.4) or the `logging` integration (direct log forwarding, for Juju >= 3.4), enabling centralized log collection. - **(charm) Container health checks**: The charm configures a Pebble HTTP health check against the `/debug/info` endpoint, running every 60 seconds, to detect and recover from service failures. - **(snap) Strict snap confinement**: The snap package uses `strict` confinement, restricting the server to only the `network` and `network-bind` interfaces. This limits the impact of a potential compromise by preventing access to the host system beyond network operations. -## **Risks** +## Risks -While the Livepatch Server is designed with security in mind, it is important to be aware of potential risks: +While the Livepatch Server is designed with security in mind, the following risks should be considered: - **TLS not natively terminated**: The Livepatch Server does not terminate TLS itself. When TLS is required, it relies on an external reverse proxy, Kubernetes ingress controller, or load balancer for TLS termination. In on-premises deployments where clients and the server are on a trusted internal network, operators may choose to run without TLS. However, if the network is not fully trusted or admin API endpoints are exposed beyond the internal network, configuring TLS termination is strongly recommended to protect authentication credentials in transit. - **TLS optional for database and storage connections**: Connections between the server and PostgreSQL, S3, and Swift storage backends support TLS but do not enforce it. Running without TLS on these connections in environments with untrusted network segments increases the risk of credential or data interception. Enabling TLS for all backend connections is recommended. @@ -62,13 +67,13 @@ While the Livepatch Server is designed with security in mind, it is important to - **Configuration-based secret management**: Admin credentials and storage credentials are provided through configuration options or environment variables. All secrets are passed to the workload container as environment variables. Operators should use Juju secrets or Kubernetes secrets to protect sensitive configuration options. The charm's log redaction module mitigates the risk of secrets appearing in charm logs, but secrets may still be visible in Pebble plan output or container environment inspection. - **Privileged access to admin credentials**: Admin Basic Auth passwords are stored as bcrypt hashes in the server configuration. Access to the configuration file or environment variables grants the ability to reconfigure the server. Maintaining strict access controls on configuration files and environment variables is essential. -## **Security of data** +## Security of data ### Data collection and storage The Livepatch Server collects and stores the following categories of data: -- **Machine registration data**: Machine IDs, authentication tokens, and tier information for registered Livepatch clients. +- **Machine registration data**: Machine IDs, authentication tokens, and tier information for registered Livepatch Clients. - **Patch metadata**: Patch versions, checksums, distribution/architecture mappings, and storage references. - **Machine reports**: When enabled, the server collects machine status reports from clients. Machine IDs in reports are hashed using HMAC before storage to protect client identity. - **Admin credentials**: Bcrypt-hashed passwords for Basic Auth admin users. @@ -98,10 +103,10 @@ The following cryptographic technologies are used by the Livepatch Server: **External packages providing cryptographic functionality:** -- [gopkg.in/macaroon.v2](https://gopkg.in/macaroon.v2) — Macaroon creation and verification -- [github.com/go-macaroon-bakery/macaroon-bakery](https://github.com/go-macaroon-bakery/macaroon-bakery) — Higher-level macaroon bakery with public key cryptography -- [`golang.org/x/crypto`](http://golang.org/x/crypto) — bcrypt, NaCl box/secretbox, curve25519 -- Go standard library `crypto/*` — TLS, HMAC, SHA256, X.509 +- [`gopkg.in/macaroon.v2`](https://gopkg.in/macaroon.v2): Macaroon creation and verification +- [`github.com/go-macaroon-bakery/macaroon-bakery`](https://github.com/go-macaroon-bakery/macaroon-bakery): Higher-level macaroon bakery with public key cryptography +- [`golang.org/x/crypto`](https://golang.org/x/crypto): bcrypt, NaCl box/secretbox, curve25519 +- Go standard library `crypto/*`: TLS, HMAC, SHA256, X.509 ### Data in transit @@ -109,27 +114,27 @@ TLS encryption is supported for all communication channels but enforcement varie | Communication path | TLS | | :---- | :---- | -| Livepatch Server ↔ Livepatch Client | Optional (operator-configured) | -| Livepatch Server ↔ Livepatch Admin Tool | Optional (operator-configured) | -| Livepatch Server ↔ Canonical hosted Livepatch service | Optional (operator-configured) | -| Livepatch Server ↔ Ubuntu Pro Service | Enforced | -| Livepatch Server ↔ PostgreSQL | Optional (operator-configured) | -| Livepatch Server ↔ S3 | Optional (`s3_secure` flag) | -| Livepatch Server ↔ Swift | Optional (operator-configured) | +| Livepatch Server to Livepatch Client | Optional (operator-configured) | +| Livepatch Server to Livepatch Admin Tool | Optional (operator-configured) | +| Livepatch Server to Canonical hosted Livepatch service | Optional (operator-configured) | +| Livepatch Server to Ubuntu Pro service | Enforced | +| Livepatch Server to PostgreSQL | Optional (operator-configured) | +| Livepatch Server to S3 | Optional (`s3_secure` flag) | +| Livepatch Server to Swift | Optional (operator-configured) | TLS is implemented using Go's standard library (`crypto/tls` and `crypto/x509`). The minimum supported TLS version is 1.2. -## **Security support** +## Security support -The on-premises Livepatch Server is released as a Kubernetes charm and a snap for on-premises use. Releases are made ad-hoc as features and bug fixes are implemented. When a security vulnerability in an upstream dependency is detected, a best-case effort is made to upgrade the dependency to the latest version that fixes the vulnerability. This security fix is then included in the next ad-hoc release. +The on-premises Livepatch Server is released as a Kubernetes charm and a snap for on-premises use. Releases are made ad-hoc as features and bug fixes are implemented. When a security vulnerability in an upstream dependency is detected, a best-effort attempt is made to upgrade the dependency to the latest version that fixes the vulnerability. This security fix is then included in the next ad-hoc release. A fix for a reported security issue that is directly present in the on-premises Livepatch Server can be prioritized and released as a minor version upgrade for both the charm and snap. -## **Related security documentation** +## Related security documentation -- [Authentication reference](/server/reference/authentication/authentication.md): Technical details on all authentication and authorization mechanisms. -- [Harden your deployment](/server/how-to-guides/security/harden-your-deployment.md): How to securely configure the server for production deployments. -- [Configure logging and monitoring](/server/how-to-guides/operations/configure-logging-and-monitoring.md): How to use the security event logging and Prometheus monitoring features. -- [Decommission the server securely](/server/how-to-guides/operations/decommission.md): How to securely remove the server and its data. -- [Security lifecycle](/server/explanation/architecture/security-lifecycle.md): How security updates are delivered and applied. -- [Report server vulnerabilities](/server/how-to-guides/security/report-server-vulnerabilities.md): How to report security vulnerabilities. +- {ref}`Authentication reference `: Technical details on all authentication and authorization mechanisms. +- {ref}`Harden your deployment `: Guidance on securely configuring the server for production deployments. +- {ref}`Configure logging and monitoring `: How to use the security event logging and Prometheus monitoring features. +- {ref}`Decommission the server securely `: How to securely remove the server and its data. +- {ref}`Security lifecycle `: How security updates are delivered and applied. +- {ref}`Report server vulnerabilities `: How to report security vulnerabilities. \ No newline at end of file diff --git a/docs/server/explanation/index.md b/docs/server/explanation/index.md index 3718ed6..222c963 100644 --- a/docs/server/explanation/index.md +++ b/docs/server/explanation/index.md @@ -1,26 +1,33 @@ --- myst: html_meta: - description: "Explanation - learn about this topic in Livepatch on-prem." + description: "Explore explanatory and conceptual guides for the Livepatch on-premises server including architecture, security, access control, and observability." --- - (server-explanation)= # Explanation -Discussion and clarification of key topics related to Livepatch on-prem server. +These explanatory and conceptual guides provide a deeper understanding of how the Livepatch on-premises server works and the security principles underpinning its design. -## In this section +## Architecture -- [Architecture](/server/explanation/architecture/index.md) — Security model, lifecycle, and access control of the server. -- [Observability](/server/explanation/observability/index.md) — Logging and monitoring concepts. +Understand the security model, lifecycle, access control, and cryptographic technologies that govern the Livepatch on-premises server. ```{toctree} :titlesonly: :maxdepth: 2 -:hidden: -Architecture -Observability +Architecture ``` + +## Observability + +Learn about the logging and monitoring concepts available for the Livepatch on-premises server. + +```{toctree} +:titlesonly: +:maxdepth: 2 + +Observability +``` \ No newline at end of file diff --git a/docs/server/explanation/observability/index.md b/docs/server/explanation/observability/index.md index a5c4a1a..475fd2b 100644 --- a/docs/server/explanation/observability/index.md +++ b/docs/server/explanation/observability/index.md @@ -1,24 +1,22 @@ --- myst: html_meta: - description: "Logging and monitoring concepts." + description: "Understand the observability concepts for the Livepatch on-premises server including logging and monitoring capabilities." --- - (server-explanation-observability)= # Observability -Logging and monitoring concepts. +The Livepatch on-premises server provides logging and monitoring capabilities to help operators maintain visibility into the health and security of their deployment. -## In this section +## Observability concepts -- [Logging and monitoring](/server/explanation/observability/logging-and-monitoring.md) +Learn about the logging and monitoring features available for the server. ```{toctree} :titlesonly: :maxdepth: 1 -:hidden: -Logging and monitoring -``` +Logging and monitoring +``` \ No newline at end of file diff --git a/docs/server/explanation/observability/logging-and-monitoring.md b/docs/server/explanation/observability/logging-and-monitoring.md index 3512170..a926c3b 100644 --- a/docs/server/explanation/observability/logging-and-monitoring.md +++ b/docs/server/explanation/observability/logging-and-monitoring.md @@ -1,22 +1,38 @@ --- myst: html_meta: - description: "Logging and monitoring - learn about this topic in Livepatch on-prem." + description: "Understand logging and monitoring for the Livepatch on-premises server including debug endpoints, Prometheus metrics, Juju log management, and security event logging." --- - (server-explanation-logging-and-monitoring)= -# Logging and Monitoring +# Logging and monitoring + +> See also: {ref}`Configure logging and monitoring `, {ref}`Security overview ` + +The Livepatch on-premises server exposes several endpoints and mechanisms that operators can use to monitor the health and security of the deployment. + +## Health and version endpoints + +The Livepatch Server exposes two debug endpoints that provide information about the server's status: -Monitoring of the Livepatch server can be most easily done by setting up monitoring on one or more endpoints. Livepatch server exposes two endpoints, in particular, `/debug/info` and `/debug/status`, that provide information on the server’s version and the server’s database/related services, respectively. Any monitoring solution can periodically check `/debug/info` as a liveliness check to ensure the service is running. +- `/debug/info`: Returns the server's version information. Any monitoring solution can periodically check this endpoint as a liveness check to ensure the service is running. +- `/debug/status`: Returns information about the server's database and related services. -The on-prem server also exposes Prometheus text-based formatted metrics available from a /metrics endpoint which can be used to monitor the system. +## Prometheus metrics -When deploying with Juju, debug logs from all deployed applications can be obtained with the command `juju debug-logs`. Increasing the server’s log level can be configured with `juju config livepatch log_level=` A full list of log levels are available on the Configure logging and monitoring [page](/server/how-to-guides/operations/configure-logging-and-monitoring.md#configure-the-log-level). +The on-premises server exposes Prometheus text-formatted metrics at the `/metrics` endpoint. These metrics can be scraped by a Prometheus instance to monitor system performance, authentication activity, request latencies, and more. -Further information on the use of juju for logging can be obtained from Juju’s [documentation](https://documentation.ubuntu.com/juju/latest/reference/juju-cli/list-of-juju-cli-commands/debug-log/). +When deploying with the charm, the `metrics-endpoint` integration enables Prometheus scraping, and the `grafana-dashboard` integration ships a pre-built Grafana dashboard tracking authentication metrics, token usage by type, contracts service errors, and request performance. + +## Juju logging + +When deploying with Juju, debug logs from all deployed applications are available through the `juju debug-logs` command. The server's log level can be configured via the `log_level` configuration option. For a full list of log levels, see {ref}`Configure logging and monitoring `. + +For more information on using Juju for logging, see the [Juju documentation on debug-log](https://documentation.ubuntu.com/juju/latest/reference/juju-cli/list-of-juju-cli-commands/debug-log/). ## Security logging -For detailed guidance on configuring security event logging, Prometheus metrics, Grafana dashboards, log redaction, and centralized log forwarding, see [How to configure logging and monitoring](/server/how-to-guides/operations/configure-logging-and-monitoring.md). +The Livepatch Server logs all authentication successes and failures, authorization decisions, token lifecycle events, admin activity, and system events as structured JSON in compliance with OWASP logging standards. + +For detailed guidance on configuring security event logging, Prometheus metrics, Grafana dashboards, log redaction, and centralized log forwarding, see {ref}`How to configure logging and monitoring `. \ No newline at end of file diff --git a/docs/server/how-to-guides/deployment/deploy-cve-service-via-snap.md b/docs/server/how-to-guides/deployment/deploy-cve-service-via-snap.md index 742888e..a1d1d9c 100644 --- a/docs/server/how-to-guides/deployment/deploy-cve-service-via-snap.md +++ b/docs/server/how-to-guides/deployment/deploy-cve-service-via-snap.md @@ -1,83 +1,95 @@ --- myst: html_meta: - description: "How to deploy cve service via snap with Livepatch on-prem." + description: "How to deploy CVE service via snap with Livepatch on-premises." --- (server-how-to-guides-getting-started-with-the-cve-service-snap)= -# Getting Started with the CVE Service Snap +# How to deploy CVE service via Snap -> Please note that this guide assumes you’ve already set up the livepatch-server-snap +> This guide assumes the livepatch-server snap has already been set up. -The Canonical Livepatch CVE service runs a simple HTTP server that periodically fetches and provides information about CVEs fixed in Ubuntu kernels. In this guide we will set up the CVE service snap, and point the Livepatch server snap to the service. +The Canonical Livepatch CVE service runs a simple HTTP server that periodically fetches and serves information about CVEs fixed in Ubuntu kernels. This guide covers setting up the CVE service snap and pointing the Livepatch Server snap to the service. -## Installation +## Install the CVE service snap -Install the latest stable CVE service snap from the snap store with: +To install the latest stable CVE service snap from the Snap Store, run: -`sudo snap install canonical-livepatch-cve-service` +``` +sudo snap install canonical-livepatch-cve-service +``` -The HTTP service will automatically initialize and begin listening on localhost:8090 with the default parameters set. The service will also begin downloading CVE data from the default OSV source on startup. The CVE service supports both .zip and .tar files for OSV sources. +The HTTP service automatically initializes and begins listening on `localhost:8090` with the default parameters. The service also begins downloading CVE data from the default OSV source on startup. The CVE service supports both `.zip` and `.tar` files for OSV sources. -To change the port and other parameters, see the Usage section. +To change the port and other parameters, see the configuration section. -## Usage +## Configure the snap -### configuring the snap +The CVE service snap has several configuration options available. All configuration options are set with: -The CVE service snap has several configuration options available. All configuration options are set via: +``` +sudo snap set canonical-livepatch-cve-service = +``` -`sudo snap set canonical-livepatch-cve-service =` +To restore a default value after a custom value has been used, set the config value to an empty string `""`: -To use the default values after a custom value is used, set the config value to an empty string ””. For example : - -`sudo snap set canonical-livepatch-cve-service port=""` +``` +sudo snap set canonical-livepatch-cve-service port="" +``` The service automatically restarts on a configuration change, ensuring that the service runs with the latest configuration. -> Note: the default upstream OSV source is about 400MB, the CVE service will use eTags to check if the source has changed, and only download from the source if there is new CVE data. +> The default upstream OSV source is about 400MB. The CVE service uses eTags to check if the source has changed, and only downloads from the source if there is new CVE data. -### Configuration Options +## Configuration options -The following table shows all configuration options, useful information, and default values. +The following table lists all configuration options, their descriptions, examples, and default values. -| Config Option | Description | Example | Notes | +| Config option | Description | Example | Notes | |:----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `source` | URL or file path to fixed CVE information. | `"https://osv-vulnerabilities.storage.googleapis.com/Ubuntu/all.zip, https://security-metadata.canonical.com/osv/osv-all.tar.xz"` | When setting this option, you must also set the `source-type` config option.

The default option for this value is `"https://osv-vulnerabilities.storage.googleapis.com/Ubuntu/all.zip"`.

When using a filepath as the source, the file must be placed in `/var/snap/canonical-livepatch-cve-service/common`. | -| `source-type` | The format of the data source. | `"osv-bucket-zip"` | When setting this option, you must also set the `source` config option.

The default option for this value is `"osv-bucket-zip"`. | -| `fetch-freq` | When to fetch fixed CVE data.

If set to `""`, the CVE service will fetch data based on the interval configuration.

If set to `once`, the CVE service will fetch the data a single time at startup.

If set to `never`, the CVE service will not fetch data from the source. | `"", "once", "never"` | When setting the option to `once` or `never`, the `interval` config option is ignored.

When setting the option to `never`, the `source`, `source-type`, and `interval` options are ignored.

The default option for this value is `""`. | -| `interval` | The interval between CVE data fetches, in the format of `xxhxxmxxs`. | `"1h0m0s"` | The default option for this value is `"1h0m0s"`. The CVE service enforces a minimum of 30 minute intervals. If the provided option is less than 30 minutes, the CVE service will use a 30 minute interval. | -| `port` | The port to bind to and listen to requests on. | `"8090"` | The default option for this value is `"8090"`. | -| `write-timeout` | The write timeout for sending CVE data. | `"5m"` | The default option for this value is `"5m"`. | -| `read-timeout` | The read timeout for reading from the livepatch server. | `"30s"` | The default option for this value is `"30s"`. | +| `source` | URL or file path to fixed CVE information. | `"https://osv-vulnerabilities.storage.googleapis.com/Ubuntu/all.zip, https://security-metadata.canonical.com/osv/osv-all.tar.xz"` | When setting this option, the `source-type` config option must also be set.

The default value is `"https://osv-vulnerabilities.storage.googleapis.com/Ubuntu/all.zip"`.

When using a file path as the source, the file must be placed in `/var/snap/canonical-livepatch-cve-service/common`. | +| `source-type` | The format of the data source. | `"osv-bucket-zip"` | When setting this option, the `source` config option must also be set.

The default value is `"osv-bucket-zip"`. | +| `fetch-freq` | When to fetch fixed CVE data.

If set to `""`, the CVE service fetches data based on the interval configuration.

If set to `once`, the CVE service fetches the data a single time at startup.

If set to `never`, the CVE service does not fetch data from the source. | `"", "once", "never"` | When setting the option to `once` or `never`, the `interval` config option is ignored.

When setting the option to `never`, the `source`, `source-type`, and `interval` options are ignored.

The default value is `""`. | +| `interval` | The interval between CVE data fetches, in the format of `xxhxxmxxs`. | `"1h0m0s"` | The default value is `"1h0m0s"`. The CVE service enforces a minimum of 30 minute intervals. If the provided option is less than 30 minutes, the CVE service uses a 30 minute interval. | +| `port` | The port to bind to and listen for requests on. | `"8090"` | The default value is `"8090"`. | +| `write-timeout` | The write timeout for sending CVE data. | `"5m"` | The default value is `"5m"`. | +| `read-timeout` | The read timeout for reading from the Livepatch Server. | `"30s"` | The default value is `"30s"`. | + +## Point the Livepatch Server to the CVE service -## Pointing Livepatch Server To The CVE Service +When connected to the CVE service, the Livepatch Server serves fixed CVE information and periodically refreshes its CVE cache by fetching from the CVE service. By default, the Livepatch Server has these features disabled so configuration values can be supplied based on a certain deployment. -Livepatch server, when connected to the CVE service, will serve fixed CVE information, and periodically refresh its CVE cache by fetching from the CVE service. By default, Livepatch server has these features disabled so you can supply configuration values based on a certain deployment. +To point the Livepatch Server to the CVE service: -To point Livepatch Server to the CVE service, first enable the cve-lookup feature with: +1. Enable the CVE lookup feature: -`sudo snap set canonical-livepatch-server lp.cve-lookup.enabled="true"` + ``` + sudo snap set canonical-livepatch-server lp.cve-lookup.enabled="true" + ``` -Then, enable the cve-sync feature, and set the source-url to the url pointing to the CVE service: +1. Enable the CVE sync feature and set the source URL to point to the CVE service: -`sudo snap set canonical-livepatch-server lp.cve-sync.enabled="true"` -`sudo snap set canonical-livepatch-server lp.cve-sync.source-url="http://:port"` + ``` + sudo snap set canonical-livepatch-server lp.cve-sync.enabled="true" + sudo snap set canonical-livepatch-server lp.cve-sync.source-url="http://:port" + ``` -You can also set the refresh interval, and proxy information if required: +Optionally, set the refresh interval and proxy information: -`sudo snap set canonical-livepatch-server lp.cve-sync.interval="1h"` -`sudo snap set canonical-livepatch-server lp.cve-sync.proxy.enabled="true"` -`sudo snap set canonical-livepatch-server lp.cve-sync.proxy.http=""` -`sudo snap set canonical-livepatch-server lp.cve-sync.proxy.https=""` -`sudo snap set canonical-livepatch-server lp.cve-sync.proxy.no-proxy=""` +``` +sudo snap set canonical-livepatch-server lp.cve-sync.interval="1h" +sudo snap set canonical-livepatch-server lp.cve-sync.proxy.enabled="true" +sudo snap set canonical-livepatch-server lp.cve-sync.proxy.http="" +sudo snap set canonical-livepatch-server lp.cve-sync.proxy.https="" +sudo snap set canonical-livepatch-server lp.cve-sync.proxy.no-proxy="" +``` -By default, the refresh interval is 1 hour, and the proxy is disabled. +By default, the refresh interval is one hour and the proxy is disabled. -When the Livepatch server receives fixed CVE data from the CVE service, it also gets a digest computed by the CVE service. Upon requesting CVE data, the server provides the CVE service with the digest. If the digest hasn’t changed on the CVE service, the request is rejected with a "Not Modified" HTTP code, preventing the server from repeatedly downloading the same data. +When the Livepatch Server receives fixed CVE data from the CVE service, it also receives a digest computed by the CVE service. Upon requesting CVE data, the server provides the CVE service with the digest. If the digest has not changed on the CVE service, the request is rejected with a "Not Modified" HTTP code, preventing the server from repeatedly downloading the same data. -## Final words +## Next steps -Now you have the Livepatch server snap integrated with the CVE service snap, allowing client machines to receive fixed CVE information about their installed patches. +The Livepatch Server snap is now integrated with the CVE service snap, allowing client machines to receive fixed CVE information about their installed patches. diff --git a/docs/server/how-to-guides/deployment/deploy-via-juju.md b/docs/server/how-to-guides/deployment/deploy-via-juju.md index ce90ae3..db18e35 100644 --- a/docs/server/how-to-guides/deployment/deploy-via-juju.md +++ b/docs/server/how-to-guides/deployment/deploy-via-juju.md @@ -1,55 +1,57 @@ --- myst: html_meta: - description: "How to deploy via juju with Livepatch on-prem." + description: "How to deploy via Juju with Livepatch on-premises." --- -(server-how-to-guides-how-to-deploy-livepatch-on-prem)= -# How to deploy Livepatch on-prem +(server-how-to-guides-how-to-deploy-livepatch-on-prem)= -## Prerequisites +# How to deploy via Juju ```{warning} -This guide has been deprecated. Refer to our [tutorials](/server/tutorial/index.md) or [snap how-to](/server/how-to-guides/deployment/deploy-via-snap.md). +This guide has been deprecated. Refer to the [tutorials](/server/tutorial/index.md) or the [snap deployment how-to guide](/server/how-to-guides/deployment/deploy-via-snap.md). -If you have an existing deployment using this document, see our [migration guide](/server/how-to-guides/deployment/migrate-from-reactive-charm-to-operator-charm.md) to update your deployment. +If an existing deployment uses this document, see the [migration guide](/server/how-to-guides/deployment/migrate-from-reactive-charm-to-operator-charm.md) to update the deployment. ``` -We will deploy and configure the livepatch on-prem server using Juju and Charmed Operators. Juju is an Open Source Charmed Operator Framework that controls the whole lifecycle of an application - including machine applications. Please follow the [installation instructions](https://documentation.ubuntu.com/juju/latest/howto/manage-juju/#install-juju) for your system. +## Prerequisites -The livepatch on-prem bundle needs to be deployed on machines running Ubuntu focal. +This guide explains how to deploy and configure the Livepatch on-premises server using Juju and Charmed Operators. Juju is an Open Source Charmed Operator Framework that controls the full lifecycle of an application, including machine applications. Follow the [installation instructions](https://documentation.ubuntu.com/juju/latest/howto/manage-juju/#install-juju) for the target system. -You don’t need to have previous or advanced knowledge of Juju or Charmed Operators to follow this guide and deploy livepatch. +The Livepatch on-premises bundle must be deployed on machines running Ubuntu Focal. -## Livepatch authorization token +No previous or advanced knowledge of Juju or Charmed Operators is required to follow this guide and deploy Livepatch. -Since on-prem livepatch servers act as caching proxies for the livepatch service hosted by canonical, the subscription token is required to authorize the on-prem instance to pull patch information. +## Obtain the Livepatch authorization token + +On-premises Livepatch Servers act as caching proxies for the Livepatch service hosted by Canonical. The subscription token is required to authorize the on-premises instance to pull patch information. + +To obtain the Ubuntu Pro subscription token, visit https://ubuntu.com/pro. -To get your Ubuntu Pro subscription token, please go to https://ubuntu.com/pro. ![image1|690x373](/_static/images/9IhZmAFso5ufkbB8QyboWUoROad.png) -## Deployment Steps +## Deployment procedure -## 1. Initialize juju +### 1. Initialize Juju -Once you have Juju CLI installed, you will need to bootstrap a Juju controller to your cloud. The [Juju documentation](https://documentation.ubuntu.com/juju/latest/howto/manage-controllers/) has detailed instructions on how to do that for several clouds and machine types. +Once the Juju CLI is installed, bootstrap a Juju controller to the target cloud. The [Juju documentation](https://documentation.ubuntu.com/juju/latest/howto/manage-controllers/) provides detailed instructions for several clouds and machine types. -See[ resources topic ](/server/reference/platform/resource-requirements.md) for requirements for the virtual machines running livepatch on-premises services. +See the [resource requirements](/server/reference/platform/resource-requirements.md) for the virtual machines running Livepatch on-premises services. -## 2. Deploying the bundle +### 2. Deploy the bundle -The bundle and charmed operators necessary to deploy livepatch server are available in the charmstore at +The bundle and Charmed Operators necessary to deploy the Livepatch Server are available at: https://charmhub.io/canonical-livepatch-onprem -To start the deployment on a created juju model, run: +To start the deployment on a created Juju model, run: ``` juju deploy ch:canonical-livepatch-onprem ``` -## 3. Configuring livepatch +### 3. Configure Livepatch After the deployment completes, verify the status of the model by running: @@ -57,13 +59,11 @@ After the deployment completes, verify the status of the model by running: juju status ``` -The output should look like: ![screenshot_20210601_164245|648x159](/_static/images/z8RLGfl4BdhI501OBguUgqlpaKY.png) -At this point the livepatch unit is expected to be in a blocked state with the message: -"✘ sync_token not set" +At this point the Livepatch unit is expected to be in a blocked state with the message: `"✘ sync_token not set"`. -Provide the token (acquired by following instructions in the Livepatch authorization token section) by running: +Provide the token, acquired by following the instructions in the authorization token section above, by running: ``` juju config ubuntu-advantage token="" @@ -71,20 +71,21 @@ juju config ubuntu-advantage token="" juju run-action livepatch/leader get-resource-token --wait ``` -The output should indicate the token has successfully been acquired: +The output should indicate the token has been successfully acquired: + ![screenshot_20210601_164500|690x127](/_static/images/fboev1KPeCS41ZI0OUD6Zsde1vC.png) -After that, provide the url_template setting as follows: +After that, set the `url_template` setting as follows: ``` juju config livepatch url_template="http://10.94.227.82/v1/patches/{filename}" ``` -The url_template specifies the url where patch files can be downloaded by livepatch client agents. The url template should be of the form 'http(s)://{HOSTNAME}/v1/patches/{filename}'. The hostname is the only part that needs to be changed. The hostname can be just the ip address of the haproxy unit. If a DNS hostname is configured for the haproxy IP address, that can be used too. +The `url_template` specifies the URL where patch files can be downloaded by Livepatch Client agents. The URL template should be of the form `http(s)://{HOSTNAME}/v1/patches/{filename}`. The hostname is the only part that needs to be changed. The hostname can be the IP address of the HAProxy unit. If a DNS hostname is configured for the HAProxy IP address, that can also be used. -### Deploying with a config overlay (Optional) +#### Deploy with a config overlay (optional) -These settings can be configured at deploy-time by using a juju bundle overlay: +These settings can be configured at deploy time by using a Juju bundle overlay: ``` juju deploy ch:canonical-livepatch-onprem --overlay config.yaml @@ -102,11 +103,11 @@ applications: token: ``` -## 4. Setting up authentication +### 4. Set up authentication -To enable admin tool access to the livepatch server, authentication needs to be configured. The easiest way is to enable username/password authentication. +To enable admin tool access to the Livepatch Server, authentication must be configured. The simplest method is to enable username and password authentication. -Generate the password hash using: +Generate the password hash: ``` sudo apt-get install apache2-utils @@ -115,15 +116,15 @@ htpasswd -bnBC 10 username:$2y$10$74ZpDgHaxnUQo.AJZk1cMuSRfef5oK5xq5o/GLbUH/Bbw6W2bmctm ``` -Use the output of the previous command to configure livepatch: +Use the output of the previous command to configure Livepatch: ``` juju config livepatch auth_basic_users='username:$2y$10$74ZgHaxn...UH/Bbw6W2bmctm' ``` -See [Administration Tool](/server/how-to-guides/security/setup-administration-tool.md) topic for instructions on installing the administration tool and setting up authentication. +See the [Administration Tool guide](/server/how-to-guides/security/setup-administration-tool.md) for instructions on installing the administration tool and setting up authentication. -Once this has been done, the livepatch admin tool can be used to authenticate: +Once this has been done, the Livepatch admin tool can be used to authenticate: ``` export LIVEPATCH_URL=http(s)://{haproxy url} @@ -131,9 +132,9 @@ export LIVEPATCH_URL=http(s)://{haproxy url} livepatch-admin login -a [username:password] ``` -## 5. Downloading patches +### 5. Download patches -The final step before attaching client machines to the server is to download patches from Canonical servers. This can be done using the admin tool. See [How to setup administration tool](/server/how-to-guides/security/setup-administration-tool.md) for installation steps. +The final step before attaching client machines to the server is to download patches from Canonical servers. This can be done using the admin tool. See the [Administration Tool guide](/server/how-to-guides/security/setup-administration-tool.md) for installation steps. To download patches, run: @@ -141,21 +142,21 @@ To download patches, run: livepatch-admin sync trigger --wait ``` -## Enabling machine status reporting +## Enable machine status reporting -Each livepatch on-prem instance can optionally send information about the status of the machines it's serving back to Canonical. This functionality is opt-in. +Each Livepatch on-premises instance can optionally send information about the status of the machines it serves back to Canonical. This functionality is opt-in. The information sent back about each machine includes: -- Kernel version -- CPU model -- Architecture -- Boot time and uptime -- Livepatch client version -- Obfuscated machine id -- Status of the patch currently applied to the machine's kernel +* Kernel version +* CPU model +* Architecture +* Boot time and uptime +* Livepatch Client version +* Obfuscated machine ID +* Status of the patch currently applied to the machine's kernel -To enable this reporting, run the following juju command: +To enable this reporting, run the following Juju command: ``` juju config livepatch sync_send_machine_reports=true diff --git a/docs/server/how-to-guides/deployment/deploy-via-snap.md b/docs/server/how-to-guides/deployment/deploy-via-snap.md index 56ebc94..8a67f9a 100644 --- a/docs/server/how-to-guides/deployment/deploy-via-snap.md +++ b/docs/server/how-to-guides/deployment/deploy-via-snap.md @@ -1,163 +1,173 @@ --- myst: html_meta: - description: "How to deploy via snap with Livepatch on-prem." + description: "How to deploy via snap with Livepatch on-premises." --- + (server-how-to-guides-getting-started-with-the-livepatch-server-snap)= -# Getting started with the Livepatch Server Snap +# How to deploy via Snap + +The Canonical Livepatch Server enables the delivery of live kernel patches to Livepatch Clients, allowing reboots of critical infrastructure to be scheduled at a convenient time. -Canonical Livepatch Server enables the delivery of Livepatch's to Livepatch clients, allowing reboots of critical infrastructure to be scheduled at a convenient time. +This guide covers setting up the Livepatch Server snap. -In this tutorial we will setup the Livepatch Server snap. +> The server snap is not designed for high-availability setups. -> Please note, the server snap is not designed for high-availability setups! +## Prerequisites -**Requirements** -At minimum, the server requires a PostgreSQL (*At least version 12*) instance to persist data. For the sake of simplicity, we will use docker to illustrate this server setup. However, feel free to use an existing instance if you have one available to you! +At minimum, the server requires a PostgreSQL instance (at least version 12) to persist data. For simplicity, this guide uses Docker to illustrate the server setup. An existing PostgreSQL instance can also be used if one is available. -> **Note**: For a production environment take a look at this [tutorial](https://ubuntu.com/server/docs/databases-postgresql) to install PostgreSQL with persistent storage. +> For a production environment, follow the [PostgreSQL installation tutorial](https://ubuntu.com/server/docs/databases-postgresql) to install PostgreSQL with persistent storage. -Run the following to start a PostgreSQL instance in Docker: +To start a PostgreSQL instance in Docker, run: ``` - docker run \ - --name postgresql \ - -e POSTGRES_USER=livepatch \ - -e POSTGRES_PASSWORD=testing \ - -p 5432:5432 \ - -d postgres:12.11 +docker run \ + --name postgresql \ + -e POSTGRES_USER=livepatch \ + -e POSTGRES_PASSWORD=testing \ + -p 5432:5432 \ + -d postgres:12.11 ``` -**Installing the snap** -To install the server snap, simply run: +## Install the snap + +To install the server snap, run: ``` - sudo snap install canonical-livepatch-server +sudo snap install canonical-livepatch-server ``` -**Migrating the database** -Within the snap is an internal tool used to migrate a PostgreSQL database with the Livepatch Server schema, to migrate your database run: +## Migrate the database + +The snap includes an internal tool for migrating a PostgreSQL database with the Livepatch Server schema. To migrate the database, run: ``` - canonical-livepatch-server.schema-tool \ - postgresql://livepatch:testing@localhost:5432/livepatch +canonical-livepatch-server.schema-tool \ + postgresql://livepatch:testing@localhost:5432/livepatch ``` -**Pointing Livepatch at your database** -All of the configuration for the Livepatch Server snap is handled within the snap daemon, to update Livepatch to target the DSN of your PostgreSQL instance, run: +## Configure the database connection + +All configuration for the Livepatch Server snap is handled within the snap daemon. To update Livepatch to target the DSN of the PostgreSQL instance, run: ``` - sudo snap \ - set canonical-livepatch-server \ - lp.database.connection-string=postgresql://livepatch:testing@localhost:5432/livepatch +sudo snap set canonical-livepatch-server \ + lp.database.connection-string=postgresql://livepatch:testing@localhost:5432/livepatch ``` -**Validate the server is available** -To check the server is running successfully, you may run the following: +## Verify the server is running + +To check the server is running successfully, run: ``` - sudo snap logs \ - canonical-livepatch-server.livepatch -n 100 +sudo snap logs canonical-livepatch-server.livepatch -n 100 ``` -If you're a customer of Ubuntu Pro and have access to Livepatch on-premise, you can enable on-premise within the snap the same as you would for the charm. +## Obtain an Ubuntu Pro token -**Obtain a Ubuntu Pro token** -Given you are a customer of Ubuntu Pro, you will have Livepatch On-Premise available to you. +Customers of Ubuntu Pro with access to Livepatch on-premises can enable on-premises mode within the snap, in the same way as for the charm. -You can obtain your token from: https://ubuntu.com/pro/dashboard +The Ubuntu Pro token is available from: https://ubuntu.com/pro/dashboard -**Updating Livepatch to use your Ubuntu Pro token** -As previously stated, we can update the servers configuration through the snap daemon, so let's update the server to use this token and enable Livepatch On-Premise: +## Set the Ubuntu Pro token + +The server configuration can be updated through the snap daemon. To update the server to use the token and enable Livepatch on-premises, run: ``` - sudo snap set canonical-livepatch-server token= +sudo snap set canonical-livepatch-server token= ``` -**Managing the server** -To manage Livepatch, we have an administrator tool, also available as a snap. Install the administrator tool from: +## Install the administration tool + +To manage Livepatch, an administrator tool is available as a snap. Install it with: ``` - sudo snap install canonical-livepatch-server-admin +sudo snap install canonical-livepatch-server-admin ``` -The administrator tool needs to know where your Livepatch server is hosted, in an all-in-one setup within a single machine, this is simply `http://localhost:8080`. Export an environment variable like so: +The administrator tool needs to know where the Livepatch Server is hosted. In an all-in-one setup on a single machine, this is `http://localhost:8080`. Export an environment variable as follows: ``` - export LIVEPATCH_URL=http://localhost:8080 +export LIVEPATCH_URL=http://localhost:8080 ``` -Next, for the administrator tool to be able to login to the server, we will require some form of basic authentication, also set in the snap daemon. For the purpose of this tutorial, we have provided you one with the username as `admin` and password as `admin123`: +## Set up authentication + +For the administrator tool to log in to the server, basic authentication must be set up in the snap daemon. For the purpose of this guide, the username is `admin` and the password is `admin123`. -> Please note, special characters are escaped using single quotes and the password is/must be bcrypt hashed +> Special characters are escaped using single quotes. The password must be bcrypt hashed. ``` - sudo snap set canonical-livepatch-server\ - lp.auth.basic.users='admin:$2y$10$c25NVkdeIMqWdbgR4883YuE/s2CT1mCmGPm5Ma1XbUqGqM26ClTGe' +sudo snap set canonical-livepatch-server \ + lp.auth.basic.users='admin:$2y$10$c25NVkdeIMqWdbgR4883YuE/s2CT1mCmGPm5Ma1XbUqGqM26ClTGe' ``` -If you would like to generate your own, you can do so as follows: +To generate a custom password hash, run: ``` - sudo apt-get install apache2-utils - htpasswd -bnBC 10 +sudo apt-get install apache2-utils +htpasswd -bnBC 10 ``` -Next, we need to manually enable basic authentication: +Next, enable basic authentication: ``` - sudo snap set canonical-livepatch-server lp.auth.basic.enabled=true +sudo snap set canonical-livepatch-server lp.auth.basic.enabled=true ``` -Finally, we can login with the administrator tool like so presuming you have used the example user and password: +Finally, log in with the administrator tool, assuming the example username and password have been used: ``` - canonical-livepatch-server-admin.livepatch-admin login -a admin:admin123 +canonical-livepatch-server-admin.livepatch-admin login -a admin:admin123 ``` -**Synchronizing with hosted Livepatch** -Now you have a running, fully configured On-Premise Livepatch server, we can synchronise patches from hosted Livepatch into your server. Run the following within your administrator tool: +## Synchronize with hosted Livepatch + +Once the on-premises Livepatch Server is running and fully configured, synchronize patches from hosted Livepatch into the server. Run the following within the administrator tool: ``` - canonical-livepatch-server-admin.livepatch-admin sync trigger +canonical-livepatch-server-admin.livepatch-admin sync trigger ``` -To set the server to automatically sync patches from Canonical's servers every 12 hours, you can run the following commands, +To set the server to automatically sync patches from Canonical's servers every 12 hours, run: ``` - sudo snap set canonical-livepatch-server lp.patch-sync.enabled=true - sudo snap set canonical-livepatch-server lp.patch-sync.interval=12h +sudo snap set canonical-livepatch-server lp.patch-sync.enabled=true +sudo snap set canonical-livepatch-server lp.patch-sync.interval=12h ``` -The default configuration is set to store the patches on the local filesystem of the server, you can also view the patches on the filesystem here: +The default configuration stores patches on the local filesystem of the server. The patches can be viewed at: ``` - ls /var/snap/canonical-livepatch-server/common/patches/ +ls /var/snap/canonical-livepatch-server/common/patches/ ``` -**Exposing the server** -By default the Snap listens on localhost:8080 and so is not accessible to requests from external networks. To see this, run the following command: +## Expose the server + +By default the snap listens on `localhost:8080` and is not accessible to requests from external networks. To check the current setting, run: ``` sudo snap get canonical-livepatch-server lp.server.server-address localhost:8080 ``` -This can be changed to listen for all incoming connections on any port: +To listen for all incoming connections on a different port, run: ``` sudo snap set canonical-livepatch-server lp.server.server-address=0.0.0.0: ``` -Follow this up with the following change to ensure your admin tool can still access the server. If you would like to access the server from a remote machine, change `localhost` to the IP address of the machine running Livepatch-server On-prem: +Update the `LIVEPATCH_URL` environment variable to ensure the admin tool can still access the server. To access the server from a remote machine, replace `localhost` with the IP address of the machine running the Livepatch Server: ``` export LIVEPATCH_URL=http://localhost: ``` -**Final words** -And now you have an On-Premise Livepatch server configured to synchronise with hosted Livepatch! +## Next steps + +The on-premises Livepatch Server is now configured to synchronize with hosted Livepatch. -For further reading please consult the *how-to* guides! +For further reading, consult the how-to guides. diff --git a/docs/server/how-to-guides/deployment/index.md b/docs/server/how-to-guides/deployment/index.md index 29f4dd4..a3da38f 100644 --- a/docs/server/how-to-guides/deployment/index.md +++ b/docs/server/how-to-guides/deployment/index.md @@ -7,20 +7,20 @@ myst: (server-how-to-guides-deployment)= -# Deployment +# How to deploy Livepatch Server Deploy, upgrade, and migrate a Livepatch Server installation. -## In this section +## Available guides -- [Deploy via Juju](/server/how-to-guides/deployment/deploy-via-juju.md) -- [Deploy via Snap](/server/how-to-guides/deployment/deploy-via-snap.md) -- [Deploy CVE Service via Snap](/server/how-to-guides/deployment/deploy-cve-service-via-snap.md) -- [Upgrade a deployment](/server/how-to-guides/deployment/upgrade-a-deployment.md) -- [Migrate from Reactive charm to snap](/server/how-to-guides/deployment/migrate-from-reactive-charm-to-snap.md) -- [Migrate from Reactive charm to Operator charm](/server/how-to-guides/deployment/migrate-from-reactive-charm-to-operator-charm.md) -- [Migrate from Reactive Charm to K8s Operator charm](/server/how-to-guides/deployment/migrate-from-reactive-charm-to-k8s-operator-charm.md) -- [Deploying on public clouds](/server/how-to-guides/deployment/public-clouds/index.md) +* [Deploy via Juju](/server/how-to-guides/deployment/deploy-via-juju.md) +* [Deploy via Snap](/server/how-to-guides/deployment/deploy-via-snap.md) +* [Deploy CVE service via Snap](/server/how-to-guides/deployment/deploy-cve-service-via-snap.md) +* [Upgrade a deployment](/server/how-to-guides/deployment/upgrade-a-deployment.md) +* [Migrate from Reactive charm to snap](/server/how-to-guides/deployment/migrate-from-reactive-charm-to-snap.md) +* [Migrate from Reactive charm to Operator charm](/server/how-to-guides/deployment/migrate-from-reactive-charm-to-operator-charm.md) +* [Migrate from Reactive Charm to K8s Operator charm](/server/how-to-guides/deployment/migrate-from-reactive-charm-to-k8s-operator-charm.md) +* [Deploy on public clouds](/server/how-to-guides/deployment/public-clouds/index.md) ```{toctree} :titlesonly: diff --git a/docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-k8s-operator-charm.md b/docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-k8s-operator-charm.md index ab812fd..19c0410 100644 --- a/docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-k8s-operator-charm.md +++ b/docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-k8s-operator-charm.md @@ -1,19 +1,19 @@ --- myst: html_meta: - description: "How to migrate from reactive charm to k8s operator charm with Livepatch on-prem." + description: "How to migrate from reactive charm to K8s operator charm with Livepatch on-prem." --- (server-how-to-guides-migrating-from-the-livepatch-machine-charm-to-the-k8s-charm)= -# Migrating From The Livepatch Machine Charm to the K8s Charm +# Migrate from the Livepatch machine charm to the K8s charm -The Juju framework offered a way to write what were called [reactive charms](https://documentation.ubuntu.com/juju/3.6/reference/charm/#reactive-charm) using the [Reactive](https://charmsreactive.readthedocs.io/en/latest/) framework. Reactive charms have been deprecated and the Livepatch server reactive charm is no longer actively maintained. +The Juju framework offered a way to write what were called [reactive charms](https://documentation.ubuntu.com/juju/3.6/reference/charm/#reactive-charm) using the [Reactive](https://charmsreactive.readthedocs.io/en/latest/) framework. Reactive charms have been deprecated and the Livepatch Server reactive charm is no longer actively maintained. -The recommended way of deploying the Livepatch server is to use the [Kubernetes charm](https://charmhub.io/canonical-livepatch-server-k8s) or the [Livepatch server snap package](https://snapcraft.io/canonical-livepatch-server). This document describes how to migrate a Livepatch server instance deployed with a reactive charm to an instance deployed with the Livepatch server k8s operator. +The recommended way of deploying the Livepatch Server is to use the [Kubernetes charm](https://charmhub.io/canonical-livepatch-server-k8s) or the [Livepatch Server snap package](https://snapcraft.io/canonical-livepatch-server). This document describes how to migrate a Livepatch Server instance deployed with a reactive charm to an instance deployed with the Livepatch Server K8s operator. -To determine what charm is deployed in your environment, connect to your Juju controller via SSH, and run \`juju status\`. Confirm the charm name is "canonical-livepatch-server" and the channel the Livepatch server was installed from. The output will look like this +To determine what charm is deployed in the environment, connect to the Juju controller via SSH, and run `juju status`. Confirm the charm name is "canonical-livepatch-server" and the channel the Livepatch Server was installed from. The output will look like this ![|602x33](/_static/images/wKsSL6h98yOCxXan9YjZ81Dqg.png) View the table below from the reactive charm to snap migration guide to understand the charm type deployed and the status for that type. @@ -26,22 +26,22 @@ View the table below from the reactive charm to snap migration guide to understa ## Prerequisites -This guide assumes you have the following: +This guide assumes the following: -- A K8s JuJu model. +- A K8s Juju model. - Access to the machine charm model. -- The charmed livepatch k8s operator deployed in a Juju Model. -- A charmed k8s PostgreSQL deployment. -- The IP of the leader PostgreSQL unit for the old livepatch deployment. - - To acquire the IP, run **juju status** and look for the public IP under the **Public address** column. -- The jq and yq utility. -- The canonical-livepatch-server-admin snap. +- The charmed Livepatch K8s operator deployed in a Juju Model. +- A charmed K8s PostgreSQL deployment. +- The IP of the leader PostgreSQL unit for the old Livepatch deployment. + - To acquire the IP, run `juju status` and look for the public IP under the **Public address** column. +- The `jq` and `yq` utility. +- The `canonical-livepatch-server-admin` snap. -To ensure a clean database migration, do not relate the k8s livepatch operator to the Postgresql charm. +To ensure a clean database migration, do not relate the K8s Livepatch operator to the PostgreSQL charm. ## Migrate configuration -The livepatch server operator charms use a simplified and better organized configuration schema. The configuration schema change means the reactive charm configuration is incompatible with the operator charms and needs to be converted. +The Livepatch Server operator charms use a simplified and better organized configuration schema. The configuration schema change means the reactive charm configuration is incompatible with the operator charms and needs to be converted. The K8s operator charms provide an action to convert from the legacy config format to the new format. First, acquire the reactive charm configuration with: @@ -49,13 +49,13 @@ The K8s operator charms provide an action to convert from the legacy config form juju config canonical-livepatch-server > old-config.yaml ``` -Next, switch to the livepatch server K8s deployment and generate the migrated configuration: +Next, switch to the Livepatch Server K8s deployment and generate the migrated configuration: ```bash juju run canonical-livepatch-server-k8s/0 emit-updated-config config-file="$(jq -Rs . old-config.yaml)" ``` -Where `old-config.yaml` is your reactive charm configuration. +Where `old-config.yaml` is the reactive charm configuration. The output for this action will look like the following: @@ -90,7 +90,7 @@ result: The K8s charm compatible configuration is in the `new-config` field, with deprecated and unknown configuration keys listed in `removed-keys` and `unrecognized-keys` respectively. -You can also take the whole output for the action and write the new configuration portion into a new YAML file with: +The whole output for the action can also be taken and the new configuration portion written into a new YAML file with: ```bash juju run canonical-livepatch-server-k8s/0 emit-updated-config config-file="$(jq -Rs . old-config.yaml)" | yq ".result"."new-config" > config.yaml @@ -122,7 +122,7 @@ canonical-livepatch-server-k8s: server.url-template: ``` -Now you can configure the livepatch K8s operator with your converted reactive charm configuration values: +Now configure the Livepatch K8s operator with the converted reactive charm configuration values: ```bash juju config canonical-livepatch-server-k8s --file new-config.yaml @@ -130,9 +130,9 @@ juju config canonical-livepatch-server-k8s --file new-config.yaml This only updates configuration values set in the file; any configuration not specified remains at its default. -## Database migration +## Migrate database -> NOTE: This guide assumes the PostgreSQL database was deployed using the machine charm to interact with the livepatch server charm. For the livepatch K8s charm, deploy a K8s PostgreSQL charm in a Juju model (the same model as the livepatch K8s charm or a different model). In this section, the PostgreSQL 14 charm is deployed on the same model as the livepatch K8s charm. +> NOTE: This guide assumes the PostgreSQL database was deployed using the machine charm to interact with the Livepatch Server charm. For the Livepatch K8s charm, deploy a K8s PostgreSQL charm in a Juju model (the same model as the Livepatch K8s charm or a different model). In this section, the PostgreSQL 14 charm is deployed on the same model as the Livepatch K8s charm. ### Dump the machine charm database @@ -154,17 +154,17 @@ Finally, dump the database using the IP address from earlier: pg_dump -Fc livepatch -h -U operator > dump-file ``` -You now have a data dump of the machine charm PostgreSQL instance. The next steps are to restore the contents on the K8s PostgreSQL charm. +A data dump of the machine charm PostgreSQL instance is now available. The next steps are to restore the contents on the K8s PostgreSQL charm. ### Restore into the K8s PostgreSQL instance -Before attempting the restoration to the K8s database, ensure the deployment has been scaled down to 1 unit: +Before attempting the restoration to the K8s database, ensure the deployment has been scaled down to one unit: ```bash juju scale-application postgresql-k8s 1 ``` -> Once the restoration is done, you can scale the deployment back to however many units you require. +> Once the restoration is done, the deployment can be scaled back to however many units are required. Once the deployment is scaled down, copy the machine charm PostgreSQL dump file into the PostgreSQL container in the leader unit: @@ -184,14 +184,14 @@ Finally, restore the database from the dump file: pg_restore -h localhost -U operator -d postgres --no-owner --clean --if-exists /tmp/dump-file ``` -Once the database has been restored, relate the database to the canonical livepatch server K8s operator and apply the database migrations: +Once the database has been restored, relate the database to the Canonical Livepatch Server K8s operator and apply the database migrations: ```bash juju integrate canonical-livepatch-server-k8s:database postgresql-k8s:database juju run canonical-livepatch-server-k8s/leader schema-upgrade ``` -After the restore, the roles need to be updated as the names differ from charm deployments. Specifically, the role that has access to the livepatch database needs to be given access to each table, since the restore sets all ownership to the `operator` role. +After the restore, the roles need to be updated as the names differ from charm deployments. Specifically, the role that has access to the Livepatch database needs to be given access to each table, since the restore sets all ownership to the `operator` role. SSH back into the leader unit and log in to `psql`: @@ -225,38 +225,38 @@ SELECT format('ALTER TABLE %I OWNER TO "relation_id_22";', tablename) FROM pg_ta This SQL switches the owner of all tables in the public schema from `operator` to `relation_id_22`. -You have now successfully migrated the database from the machine charm PostgreSQL to the K8s charm PostgreSQL, and can now use it with the livepatch server K8s charm. +The database has now been successfully migrated from the machine charm PostgreSQL to the K8s charm PostgreSQL, and can now be used with the Livepatch Server K8s charm. -## Patch migration +## Migrate patches The procedure for migrating patches depends on the patch storage configuration set for the machine charm. -> Note: The filesystem storage option is not recommended as it prevents running multiple livepatch server pods, the filesystem cannot be shared across pods, and will be lost on pod restart. Instead, use PostgreSQL or swift/s3 buckets and resync the patch storage. +> Note: The filesystem storage option is not recommended as it prevents running multiple Livepatch Server pods, the filesystem cannot be shared across pods, and will be lost on pod restart. Instead, use PostgreSQL or swift/s3 buckets and resync the patch storage. ### PostgreSQL For migrating the database, follow the same steps provided in the Database migration section, but with the patch storage database. -Once you migrate the database, update the charm config to use PostgreSQL for patch storage and provide the connection string: +Once the database is migrated, update the charm config to use PostgreSQL for patch storage and provide the connection string: ```bash juju config canonical-livepatch-k8s patch-storage.type=postgres juju config canonical-livepatch-k8s patch-storage.postgres-connection-string= ``` -If you are using the same database for patch storage as you are for the main livepatch server database, you only need to set the `patch-storage.type` key; Juju handles the connection string via the `livepatch-postgres` integration. +If the same database is being used for patch storage as for the main Livepatch Server database, only the `patch-storage.type` key needs to be set; Juju handles the connection string via the `livepatch-postgres` integration. -After migrating the database, ensure you have access to your patches by querying for available patches via the admin tool: +After migrating the database, ensure access to the patches by querying for available patches via the admin tool: ```bash canonical-livepatch-server-admin.livepatch-admin storage patches ``` -If the migration was successful, you will see a list of patch payloads for each patch version. +If the migration was successful, a list of patch payloads for each patch version will be displayed. ### Object storage -The `swift` and `s3` patch storage types imply that the patches are stored in a remote AWS S3 or Swift bucket. This means that the migration of the configuration values and database migration from the reactive charm to the K8s charm is sufficient. Only the network connectivity between the livepatch K8s charm units and the remote bucket should be verified. This might require modification of firewall rules depending on the setup. +The `swift` and `s3` patch storage types imply that the patches are stored in a remote AWS S3 or Swift bucket. This means that the migration of the configuration values and database migration from the reactive charm to the K8s charm is sufficient. Only the network connectivity between the Livepatch K8s charm units and the remote bucket should be verified. This might require modification of firewall rules depending on the setup. When using object storage, such as AWS S3 or a Swift bucket, relevant connection parameters have been copied over with the configuration migration. The only required action is to refresh the patch storage: @@ -264,4 +264,4 @@ When using object storage, such as AWS S3 or a Swift bucket, relevant connection canonical-livepatch-server-admin.livepatch-admin storage refresh ``` -This adds patches found in storage to the distribution records in the livepatch database. +This adds patches found in storage to the distribution records in the Livepatch database. \ No newline at end of file diff --git a/docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-operator-charm.md b/docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-operator-charm.md index 6a09687..eac7258 100644 --- a/docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-operator-charm.md +++ b/docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-operator-charm.md @@ -6,21 +6,21 @@ myst: (server-how-to-guides-migrating-from-the-old-livepatch-charm)= -# Migrating from the old livepatch charm +# Migrate from the old Livepatch charm The Juju framework offered a, now deprecated, way to write charms called [reactive charms](https://documentation.ubuntu.com/juju/3.6/reference/charm/#reactive-charm). The modern framework is known as the [operator framework](https://documentation.ubuntu.com/juju/latest/reference/charm/#ops-charm). -Below we explain how to identify which type of charm you are running. +Below, the process to identify which type of charm is running is explained. Run `juju status` and observe the charm name and channel. The output will resemble the following. ![livepatch-status|800x31](/_static/images/2uNc2yggCQnxXj7gfkmcBVE0j2H.png) -**Machine Charm:** +**Machine Charm** - Charm name = [canonical-livepatch-server](https://charmhub.io/canonical-livepatch-server) - Channel = `latest/*` - Reactive charm (deprecated) - Channel = `ops1.x/*` - Operator charm (recommended for new deployments) -**Kubernetes Charm:** +**Kubernetes Charm** - Charm name = [canonical-livepatch-server-k8s](https://charmhub.io/canonical-livepatch-server-k8s) - Channel = `latest/*` - Operator charm (recommended for new deployments) @@ -30,11 +30,11 @@ Run `juju status` and observe the charm name and channel. The output will resemb Currently there is no way to migrate existing data to a new deployment. Existing deployments will continue to function but will no longer receive new features. It is recommended that new deployments use the operator charms. -To migrate an existing reactive charm deployment, it is suggested that you setup a new deployment and follow the steps below to migrate your configuration. +To migrate an existing reactive charm deployment, set up a new deployment and follow the steps below to migrate the configuration. -## Migrate Configuration +## Migrate configuration -The new Livepatch charms have different configuration keys. Additionally, some options were removed in favour of a simpler structure. To migrate your old config to the new one, you can use this [script](https://github.com/canonical/livepatch-machine-charm/blob/main/scripts/migrate_config.py). +The new Livepatch charms have different configuration keys. Additionally, some options were removed in favour of a simpler structure. To migrate the old configuration to the new one, use this [script](https://github.com/canonical/livepatch-machine-charm/blob/main/scripts/migrate_config.py). To run the script: @@ -42,19 +42,19 @@ To run the script: python3 ./converter.py -i input.yaml -o converted.yaml ``` -Where the `input.yaml` is the old configuration that you want to convert. To extract it from your deployment, you can use this command: +Where the `input.yaml` is the old configuration to convert. To extract it from the deployment, use this command: ``` juju config livepatch-server > input.yaml ``` -The script would create/overwrite the output file specified by the `-o` parameter. +The script creates or overwrites the output file specified by the `-o` parameter. | | | | | :---------------------------------: | :----------------------------------------: | :------------------------------------------------------------------------------------------------------------: | | **Old config** | **New config** | **Notes** | -| log_level | server.log-level | Possible values:'debug', 'info', 'warn', 'error'.Default is ‘info’ | -| url_template | server.url-template | Must be in the form:“http(s)://\:\/v1/patches/{filename}" | +| log_level | server.log-level | Possible values:'debug', 'info', 'warn', 'error'.Default is 'info' | +| url_template | server.url-template | Must be in the form:"http(s)://\:\/v1/patches/{filename}" | | psql_dbname | **NA** | | | psql_roles | **NA** | | | blocklist_cache_refresh | patch-blocklist.refresh-interval | Make sure that patch-blocklist.enabled is set to true | @@ -126,4 +126,4 @@ The script would create/overwrite the output file specified by the `-o` paramete | profiler_profile_inuse | profiler.profile_inuse | | | profiler_profile_mutexes | profiler.profile_mutexes | | | profiler_profile_blocks | profiler.profile_blocks | | -| profiler_profile_goroutines | profiler.profile_goroutine | | +| profiler_profile_goroutines | profiler.profile_goroutine | | \ No newline at end of file diff --git a/docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-snap.md b/docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-snap.md index 6e19c38..f7b7f29 100644 --- a/docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-snap.md +++ b/docs/server/how-to-guides/deployment/migrate-from-reactive-charm-to-snap.md @@ -7,30 +7,31 @@ myst: (server-how-to-guides-migration-from-livepatch-server-reactive-machine-charm-to-the-on-prem-snap)= -# Migration from Livepatch Server Reactive Machine charm to the On-prem snap +# Migrate from the Livepatch Server reactive machine charm to the on-premises snap -The Juju framework offered a way to write charms using the [Reactive](https://charmsreactive.readthedocs.io/en/latest/) framework and these were called [reactive charms](https://documentation.ubuntu.com/juju/3.6/reference/charm/#reactive-charm). Reactive charms have been deprecated and the Livepatch server reactive charm that allowed users to run an On-prem deployment of the Livepatch server is no longer actively maintained. The recommended way of deploying the Livepatch server currently, is to use the [Kubernetes charm](https://charmhub.io/canonical-livepatch-server-k8s) or the [Livepatch server snap package](https://snapcraft.io/canonical-livepatch-server). This document describes how to migrate a Livepatch server instance deployed with a reactive charm, to an instance deployed with the Livepatch server snap package. +The Juju framework offered a way to write charms using the [Reactive](https://charmsreactive.readthedocs.io/en/latest/) framework and these were called [reactive charms](https://documentation.ubuntu.com/juju/3.6/reference/charm/#reactive-charm). Reactive charms have been deprecated and the Livepatch Server reactive charm that allowed running an on-premises deployment of the Livepatch Server is no longer actively maintained. The recommended way of deploying the Livepatch Server currently is to use the [Kubernetes charm](https://charmhub.io/canonical-livepatch-server-k8s) or the [Livepatch Server snap package](https://snapcraft.io/canonical-livepatch-server). This document describes how to migrate a Livepatch Server instance deployed with a reactive charm to an instance deployed with the Livepatch Server snap package. -Validate the details of your charmed Livepatch server deployment by connecting to your Juju controller via SSH, and running `juju status`. Confirm the charm name is "canonical-livepatch-server" and the channel the Livepatch server was installed from. The output will look like this: +Validate the details of the charmed Livepatch Server deployment by connecting to the Juju controller via SSH, and running `juju status`. Confirm the charm name is "canonical-livepatch-server" and the channel the Livepatch Server was installed from. The output will look like this: |App|Status|Scale|Charm|Channel|Rev| |------|----------|--------|----------|-------------|------| |livepatch|active|1|canonical-livepatch-server|latest/stable|51| View the table below to understand the charm type deployed and the status for that type. + | Charm Type | Charm Name | Channel | Status/Recommendation | | ----- | ----- | ----- | ----- | | **Machine Charm - Reactive** | [canonical-livepatch-server](https://charmhub.io/canonical-livepatch-server) | `latest/*` | Reactive charm (deprecated) | | **Machine Charm - Operator** | [canonical-livepatch-server](https://charmhub.io/canonical-livepatch-server) | `ops1.x/*` | Operator charm (deprecated) | | **Kubernetes Charm - Operator** | [canonical-livepatch-server-k8s](https://charmhub.io/canonical-livepatch-server-k8s) | `latest/*` | Operator charm (recommended for new deployments) | -This guide specifically describes how to migrate from the Reactive charm (in channel `latest/*`) to the Livepatch server snap package. For simplicity, this guide uses the same host instance as the juju deployment, to deploy the Livepatch server snap. +This guide specifically describes how to migrate from the Reactive charm (in channel `latest/*`) to the Livepatch Server snap package. For simplicity, this guide uses the same host instance as the Juju deployment to deploy the Livepatch Server snap. -## Migrate Configuration +## Migrate configuration -The new Livepatch server operator charms and snaps have different configuration keys when compared to the reactive charms. The configuration was restructured to be simple and easy to read. As a result, migrating the configuration from the reactive charm to the snap is not straightforward. However, we provide a tool with the Livepatch server snap that simplifies the process. [Refer to the "Migrate Configuration" table](/server/how-to-guides/deployment/migrate-from-reactive-charm-to-operator-charm.md) to understand how the configuration keys have changed. +The new Livepatch Server operator charms and snaps have different configuration keys when compared to the reactive charms. The configuration was restructured to be simple and easy to read. As a result, migrating the configuration from the reactive charm to the snap is not straightforward. However, a tool is provided with the Livepatch Server snap that simplifies the process. Refer to the [Migrate configuration table](/server/how-to-guides/deployment/migrate-from-reactive-charm-to-operator-charm.md) to understand how the configuration keys have changed. -1. To access the migration tool, install the [canonical-livepatch-server snap](https://snapcraft.io/canonical-livepatch-server). This is the same snap that will be used later to set up the Livepatch server. +1. To access the migration tool, install the [canonical-livepatch-server snap](https://snapcraft.io/canonical-livepatch-server). This is the same snap that will be used later to set up the Livepatch Server. ```shell sudo snap install canonical-livepatch-server --channel=latest/stable @@ -42,21 +43,21 @@ The new Livepatch server operator charms and snaps have different configuration snap list | grep canonical-livepatch-server ``` -2. Save the reactive machine charm configuration of the Livepatch server deployment in a yaml file. +2. Save the reactive machine charm configuration of the Livepatch Server deployment in a YAML file. ```shell juju config > old-config.yaml ``` -3. Move the configuration file to the $SNAP_COMMON directory of the Livepatch server snap. This needs to be done because the Livepatch server snap is strictly confined and cannot access files outside of its snap specific directories. +3. Move the configuration file to the `$SNAP_COMMON` directory of the Livepatch Server snap. This needs to be done because the Livepatch Server snap is strictly confined and cannot access files outside of its snap specific directories. ```shell sudo mv old-config.yaml /var/snap/canonical-livepatch-server/common/ ``` -4. Use the migrate-config tool available with the Livepatch server snap. You can use this command to display the migrated configuration, dry-run the application of the configuration and to apply the migrated configuration to the Livepatch server snap deployment. All the configuration values that were set in the reactive charm will be migrated to the snap. Configuration options with empty values will not be migrated to prevent overwriting the default configuration values present in the snap configuration. +4. Use the `migrate-config` tool available with the Livepatch Server snap. This command can be used to display the migrated configuration, dry-run the application of the configuration, and to apply the migrated configuration to the Livepatch Server snap deployment. All the configuration values that were set in the reactive charm will be migrated to the snap. Configuration options with empty values will not be migrated to prevent overwriting the default configuration values present in the snap configuration. - - Display the migrated configuration and save the new configuration to a file. This step requires sudo/root user access to be able to create a new output file in the $SNAP_COMMON directory of the Livepatch server snap. This can be used to verify the configuration before applying. (Optional) + - Display the migrated configuration and save the new configuration to a file. This step requires sudo/root user access to be able to create a new output file in the `$SNAP_COMMON` directory of the Livepatch Server snap. This can be used to verify the configuration before applying. (Optional) ```shell # Use this to display the new configuration in the terminal @@ -82,7 +83,7 @@ The new Livepatch server operator charms and snaps have different configuration -i /var/snap/canonical-livepatch-server/common/old-config.yaml --set-config ``` - 5. Review the new configuration of the Livepatch server snap and make modifications where needed. Refer to the [configuration documentation](/server/reference/platform/configuration.md) for more information. +5. Review the new configuration of the Livepatch Server snap and make modifications where needed. Refer to the [configuration documentation](/server/reference/platform/configuration.md) for more information. - To view the new configuration run: @@ -98,12 +99,12 @@ The new Livepatch server operator charms and snaps have different configuration (server-how-to-guides-database-migration)= -## Database Migration +## Migrate database -Data migration from the [PostgreSQL database machine charm](https://charmhub.io/postgresql) used by the Livepatch server reactive charm, to the database used by the Livepatch server snap is essential to preserve the machine and patch data that has already been stored. There are however, a few nuances in migrating this data from the charm to the snap. We do not want to preserve the roles and ownership created by the PostgreSQL charm, because these roles only make sense in the context of charms and Juju. This is taken into account when describing the steps for data migration below. +Data migration from the [PostgreSQL database machine charm](https://charmhub.io/postgresql) used by the Livepatch Server reactive charm to the database used by the Livepatch Server snap is essential to preserve the machine and patch data that has already been stored. There are, however, a few nuances in migrating this data from the charm to the snap. The roles and ownership created by the PostgreSQL charm do not need to be preserved, because these roles only make sense in the context of charms and Juju. This is taken into account when describing the steps for data migration below. ````{note} -It is assumed that the PostgreSQL database was deployed using the [machine charm](https://charmhub.io/postgresql) to interact with the Livepatch server charm. For the Livepatch server snap, deploy PostgreSQL in a suitable production environment. **For simplicity, in this guide, the Livepatch server snap connects to a PostgreSQL instance running in a Docker container. This is not recommended for using PostgreSQL in production environments.** +It is assumed that the PostgreSQL database was deployed using the [machine charm](https://charmhub.io/postgresql) to interact with the Livepatch Server charm. For the Livepatch Server snap, deploy PostgreSQL in a suitable production environment. **For simplicity, in this guide, the Livepatch Server snap connects to a PostgreSQL instance running in a Docker container. This is not recommended for using PostgreSQL in production environments.** ```shell docker run \ @@ -119,16 +120,18 @@ This setup can differ on a case by case basis and would result in slightly diffe ```` 1. Download the tools necessary for PostgreSQL database migration. + ```shell sudo apt install postgresql-client postgresql-client-common ``` 2. Obtain the IP address of the primary PostgreSQL database unit using the output of `juju status`. + |Unit|Workload|Machine|Public address|Ports| Message| |------|----------|--------------|----------------------|--------|------------| |postgresql/0\*| active| 1 | 10.239.140.105| 5432/tcp | Primary -3. Get the system user’s password for the PostgreSQL database charm unit. The password is obtained by using the [\`get-password\` action](https://charmhub.io/postgresql/actions#get-password) defined by the PostgreSQL machine charm. The action gets the password for the `operator` username by default. The action must be run for the unit configured to be the primary database. +3. Get the system user's password for the PostgreSQL database charm unit. The password is obtained by using the [`get-password` action](https://charmhub.io/postgresql/actions#get-password) defined by the PostgreSQL machine charm. The action gets the password for the `operator` username by default. The action must be run for the unit configured to be the primary database. ```shell juju run postgresql/0 get-password @@ -141,16 +144,16 @@ This setup can differ on a case by case basis and would result in slightly diffe ``` ```{note} -If the reactive charm deployment of the Livepatch server uses the \`filesystem\` patch storage type, the database dump step might be a little different. Refer the [Patch Migration section](#server-how-to-guides-patch-migration) below for more information on a different command to run for the database dump. +If the reactive charm deployment of the Livepatch Server uses the `filesystem` patch storage type, the database dump step might be a little different. Refer to the [Patch migration section](#server-how-to-guides-patch-migration) below for more information on a different command to run for the database dump. ``` -5. Copy the dump file to an environment accessible by the new PostgreSQL database deployment. In our case, the dump file will be copied to the docker container running the database i.e. container with name `postgresql`. +5. Copy the dump file to an environment accessible by the new PostgreSQL database deployment. In this scenario, the dump file will be copied to the Docker container running the database, that is, the container with name `postgresql`. ```shell docker cp dump-file postgresql:/dump_file ``` -6. Restore the data from the dump file to the new database, using the [pg_restore tool](https://www.postgresql.org/docs/14/app-pgrestore.html). Here, we use the no-owner (-O) and no-privileges (-x) options to prevent restoration of owners and privileges from the old postgres database. This is done to avoid migrating over owners that only make sense in the context of charms and Juju. The pg_restore is done within the docker container. +6. Restore the data from the dump file to the new database, using the [pg_restore tool](https://www.postgresql.org/docs/14/app-pgrestore.html). Here, the `--no-owner` (`-O`) and `--no-privileges` (`-x`) options are used to prevent restoration of owners and privileges from the old PostgreSQL database. This is done to avoid migrating over owners that only make sense in the context of charms and Juju. The `pg_restore` is done within the Docker container. ```shell docker exec -it postgresql bash @@ -158,75 +161,80 @@ If the reactive charm deployment of the Livepatch server uses the \`filesystem\` pg_restore dump-file -d livepatch -U livepatch -Ox ``` -7. The final step involves running schema upgrades on the database, as the database used by the new Livepatch server versions have a different schema than the one used by the Livepatch server reactive charm. This is a very important step, without which the Livepatch server snap will fail. This command uses the schema-tool provided by the Livepatch server snap, which accepts the database connection string as the argument and applies the schema upgrades. +7. The final step involves running schema upgrades on the database, as the database used by the new Livepatch Server versions have a different schema than the one used by the Livepatch Server reactive charm. This is a very important step, without which the Livepatch Server snap will fail. This command uses the `schema-tool` provided by the Livepatch Server snap, which accepts the database connection string as the argument and applies the schema upgrades. ```shell canonical-livepatch-server.schema-tool \ postgresql://livepatch:testing@localhost:5432/livepatch ``` -After successfully completing these steps, the new PostgreSQL database will contain all the data present in the PostgreSQL charm. The next section explains how the patches synced from the upstream Livepatch server can be migrated to be used by the Livepatch server snap. +After successfully completing these steps, the new PostgreSQL database will contain all the data present in the PostgreSQL charm. The next section explains how the patches synced from the upstream Livepatch Server can be migrated to be used by the Livepatch Server snap. (server-how-to-guides-patch-migration)= -## Patch Migration +## Migrate patches -Data and Patch Migration are closely related because the type of patch storage used by the Livepatch server, running as a reactive machine charm, would define which migration steps are necessary (or not), so that these patches and their corresponding data are effectively migrated to the Livepatch server snap. Note that, only the patch data migration would need additional steps depending on the type of patch storage used. All other data stored by the Livepatch server in the PostgreSQL database can be directly migrated to the new database used by the Livepatch server snap. +Data and patch migration are closely related because the type of patch storage used by the Livepatch Server, running as a reactive machine charm, defines which migration steps are necessary (or not), so that these patches and their corresponding data are effectively migrated to the Livepatch Server snap. Note that only the patch data migration would need additional steps depending on the type of patch storage used. All other data stored by the Livepatch Server in the PostgreSQL database can be directly migrated to the new database used by the Livepatch Server snap. -Let us consider the different patch storage types and the migration steps necessary to migrate the patches and data. +Consider the different patch storage types and the migration steps necessary to migrate the patches and data. 1. **PostgreSQL** - The `postgres` patch storage type implies that the patches were stored in a postgres database in the `patch_file_data` table. In this case, patch migration does not need any extra steps. Migrating the data from the PostgreSQL database used by the reactive charm to the PostgreSQL database used by the snap is sufficient, for patch migration. If a dedicated PostgreSQL database is being used for patch storage, follow the exact steps for database migration as mentioned above, to also migrate the database containing the patches.\ - The `patch-storage.postgres-connection-string` configuration of the Livepatch server snap, needs to be set with the connection string of the PostgreSQL database containing the migrated patches. + + The `postgres` patch storage type implies that the patches were stored in a PostgreSQL database in the `patch_file_data` table. In this case, patch migration does not need any extra steps. Migrating the data from the PostgreSQL database used by the reactive charm to the PostgreSQL database used by the snap is sufficient for patch migration. If a dedicated PostgreSQL database is being used for patch storage, follow the exact steps for database migration as mentioned above, to also migrate the database containing the patches. + + The `patch-storage.postgres-connection-string` configuration of the Livepatch Server snap needs to be set with the connection string of the PostgreSQL database containing the migrated patches. ```shell sudo snap set canonical-livepatch-server \ lp.patch-storage.postgres-connection-string= ``` -2. **Swift and S3**\ - The `swift` and `s3` patch storage types imply that the patches are stored in a remote AWS S3 or Swift bucket. This means that the migration of the configuration values and database migration from the reactive charm to the server snap is sufficient. Only the network connectivity between the machine running the Livepatch server snap and the remote bucket should be verified. This might require modification of firewall rules depending on the setup. +2. **Swift and S3** -3. **Filesystem**\ - The `filesystem` patch storage type implies that the patch files were stored in a filesystem accessible by the Livepatch server reactive charm. Migrating patches stored in a filesystem could be slightly more complex depending on the permissions and accessibility of the filesystem. + The `swift` and `s3` patch storage types imply that the patches are stored in a remote AWS S3 or Swift bucket. This means that the migration of the configuration values and database migration from the reactive charm to the server snap is sufficient. Only the network connectivity between the machine running the Livepatch Server snap and the remote bucket should be verified. This might require modification of firewall rules depending on the setup. -- If the filesystem where the patches are stored is accessible, and the patches can be easily moved from the machine on which the Livepatch server is running as a reactive charm, to the machine running the Livepatch server snap, the patch migration process is straightforward. This method saves us the time, resources and effort of redownloading all the patches from the upstream Livepatch server. +3. **Filesystem** - - For this example, we will consider that the Livepatch server reactive charm is running on an LXD container and the Livepatch server snap runs on the host machine running the LXD container. The patches are stored in the /livepatch directory of the LXD container. The patch migration process involves copying the patches to the Livepatch server snap machine, and then moving the patches to the snap’s [$SNAP_COMMON](https://snapcraft.io/docs/reference/development/environment-variables/#snap-common) directory. - ```shell - # Pull patch files from the LXD container - sudo lxc file pull /livepatch/ \ - /var/snap/canonical-livepatch-server/common/ -pr + The `filesystem` patch storage type implies that the patch files were stored in a filesystem accessible by the Livepatch Server reactive charm. Migrating patches stored in a filesystem could be slightly more complex depending on the permissions and accessibility of the filesystem. - # Move the files from /livepatch to /patches (default file system path for the snap) - sudo mv /var/snap/canonical-livepatch-server/common/livepatch/* \ - /var/snap/canonical-livepatch-server/common/patches - ``` + - If the filesystem where the patches are stored is accessible, and the patches can be easily moved from the machine on which the Livepatch Server is running as a reactive charm to the machine running the Livepatch Server snap, the patch migration process is straightforward. This method saves the time, resources and effort of redownloading all the patches from the upstream Livepatch Server. -- If the filesystem where the patches are stored is inaccessible and cannot be moved to the new machine, the patch migration process gets a little more complicated. The process involves preventing the migration of the patch data during the database migration, and instead syncing the patches from the upstream Livepatch server. + For this example, consider that the Livepatch Server reactive charm is running on an LXD container and the Livepatch Server snap runs on the host machine running the LXD container. The patches are stored in the `/livepatch` directory of the LXD container. The patch migration process involves copying the patches to the Livepatch Server snap machine, and then moving the patches to the snap's [`$SNAP_COMMON`](https://snapcraft.io/docs/reference/development/environment-variables/#snap-common) directory. - - To prevent the migration of the patch data, run the following command in place of the pg_dump command shown in the database migration section. + ```shell + # Pull patch files from the LXD container + sudo lxc file pull /livepatch/ \ + /var/snap/canonical-livepatch-server/common/ -pr - ```shell - pg_dump -Fc livepatch -h -U operator \ - --exclude-table-data="patch" --exclude-table-data="patch_file" \ - --exclude-table-data="patch_file_tier" --exclude-table-data="kernel" \ - > dump-file - ``` + # Move the files from /livepatch to /patches (default file system path for the snap) + sudo mv /var/snap/canonical-livepatch-server/common/livepatch/* \ + /var/snap/canonical-livepatch-server/common/patches + ``` - - This command will ensure that the patch file data in specific tables is not migrated. The rest of the steps for database migration are the same as described in the [Database migration section](#server-how-to-guides-database-migration). + - If the filesystem where the patches are stored is inaccessible and cannot be moved to the new machine, the patch migration process gets a little more complicated. The process involves preventing the migration of the patch data during the database migration, and instead syncing the patches from the upstream Livepatch Server. - - This enables users to sync patches from the upstream Livepatch server and fill the patch file data in the database. The steps for patch synchronization and populating patch file data are described in the next section. + To prevent the migration of the patch data, run the following command in place of the `pg_dump` command shown in the database migration section. -## Using the livepatch-admin tool for patch file and storage synchronization + ```shell + pg_dump -Fc livepatch -h -U operator \ + --exclude-table-data="patch" --exclude-table-data="patch_file" \ + --exclude-table-data="patch_file_tier" --exclude-table-data="kernel" \ + > dump-file + ``` + + This command will ensure that the patch file data in specific tables is not migrated. The rest of the steps for database migration are the same as described in the [Database migration section](#server-how-to-guides-database-migration). -The livepatch-admin tool is useful for syncing patches from the upstream Livepatch server and populating the database with the synced patch data. Follow the how-to guides mentioned below to set up the livepatch-admin tool and synchronize patches from the hosted Livepatch server. + This enables syncing patches from the upstream Livepatch Server and filling the patch file data in the database. The steps for patch synchronization and populating patch file data are described in the next section. -1. [How to set up the livepatch-admin tool](/server/how-to-guides/security/setup-administration-tool.md) -2. [How to fetch patches from the hosted Livepatch server](/server/how-to-guides/patch-management/fetch-patches.md) +## Use the livepatch-admin tool for patch file and storage synchronization + +The `livepatch-admin` tool is useful for syncing patches from the upstream Livepatch Server and populating the database with the synced patch data. Follow the how-to guides mentioned below to set up the `livepatch-admin` tool and synchronize patches from the hosted Livepatch Server. + +1. [Set up the livepatch-admin tool](/server/how-to-guides/security/setup-administration-tool.md) +2. [Fetch patches from the hosted Livepatch Server](/server/how-to-guides/patch-management/fetch-patches.md) Once the patches have been downloaded, run `livepatch-admin storage refresh` to sync the patch storage and patch data in the database. ```{note} It is recommended to run `livepatch-admin storage refresh` after the database and patch migration, irrespective of the type of patch storage and how the migration was done, as it helps confirm that both the patch data in the database and the patches in the storage are in sync. -``` +``` \ No newline at end of file diff --git a/docs/server/how-to-guides/deployment/public-clouds/deploying-on-aws.md b/docs/server/how-to-guides/deployment/public-clouds/deploying-on-aws.md index 38d860a..a99548d 100644 --- a/docs/server/how-to-guides/deployment/public-clouds/deploying-on-aws.md +++ b/docs/server/how-to-guides/deployment/public-clouds/deploying-on-aws.md @@ -1,44 +1,45 @@ --- myst: html_meta: - description: "How to deploying on aws on public clouds with Livepatch server." + description: "How to deploy the Livepatch Server snap on AWS." --- (server-how-to-guides-deploying-the-livepatch-server-snap-on-aws)= -# Deploying the Livepatch Server Snap on AWS +# How to deploy on AWS This section details how to deploy the Livepatch Server snap in auto-scaling configuration on AWS. -## Required Resources +## Required resources -To set up Livepatch server on AWS using an S3 bucket for patch storage, you will need: +To set up the Livepatch Server on AWS using an S3 bucket for patch storage, the following are required: -- An RDS instance with PostgreSQL 12 or 14 using password authentication. - - DSN string with User and password should be stored in the AWS secrets vault. -- A Launch template with an instance type of at least T3.Medium (2 vCPU, 4 GB RAM) -- An Ubuntu Pro token stored in the AWS secrets vault. -- S3 bucket with the `s3:GetObject` policy (bucket must be public for clients to download patches, but you can restrict the policy to a range of ip addresses). -- An IAM role with the `AWSSecretsManagerClientReadOnlyAccess` role and `AmazonS3ReadOnlyAccess` role. -- An IAM user with Allow effects for the actions `s3:PutObject`, `s3:ListBucket`, and `s3:GetObject` roles for the S3 bucket. -- A secret entry for the IAM user with Key value pairs `S3AccessKey` (for the S3 access key), and `SecretAccessKey` (for the S3 secret key). -- A Load balancer set to internet-facing. -- An auto-scaling group using the launch template. -- A security group to allow all internet access for HTTP and HTTPS. -- A security group to allow access to only traffic from within AWS (for the server instances and PostgreSQL). +* An RDS instance with PostgreSQL 12 or 14 using password authentication. The DSN string with username and password should be stored in the AWS Secrets Vault. +* A launch template with an instance type of at least T3.Medium (two vCPUs, 4 GB RAM). +* An Ubuntu Pro token stored in the AWS Secrets Vault. +* An S3 bucket with the `s3:GetObject` policy. The bucket must be public for clients to download patches, but the policy can be restricted to a range of IP addresses. +* An IAM role with the `AWSSecretsManagerClientReadOnlyAccess` role and `AmazonS3ReadOnlyAccess` role. +* An IAM user with Allow effects for the actions `s3:PutObject`, `s3:ListBucket`, and `s3:GetObject` roles for the S3 bucket. +* A secret entry for the IAM user with key-value pairs `S3AccessKey` (for the S3 access key) and `SecretAccessKey` (for the S3 secret key). +* A load balancer set to internet-facing. +* An auto-scaling group using the launch template. +* A security group to allow all internet access for HTTP and HTTPS. +* A security group to allow access only from traffic within AWS (for the server instances and PostgreSQL). -## Creating The Deployment +## Create the deployment -With AWS, you can set up an auto-scaling group and a load balancer with an EC2 launch template configured to install and set up a Livepatch server instance. +With AWS, an auto-scaling group and a load balancer can be set up with an EC2 launch template configured to install and set up a Livepatch Server instance. + +### Create the launch template To create a launch template, log in to the AWS console and navigate to the Launch Templates section in the EC2 overview page. -You want to select an instance type that has sufficient CPU and memory capacity. The minimum instance type for Livepatch server to run efficiently is the t3.medium instance type, with 2 vCPU and 4 GB memory. For the storage options, the default volume size of 8 GB will be sufficient. +Select an instance type with sufficient CPU and memory capacity. The minimum instance type for the Livepatch Server to run efficiently is `t3.medium`, with two vCPUs and 4 GB memory. For storage options, the default volume size of 8 GB is sufficient. -For the network settings, select a security group that only allows network traffic from within AWS. We will set up a load balancer with internet access and redirect to our server instances later. For debugging purposes, you can create an SSH Key Pair to connect to the instance. +For network settings, select a security group that only allows network traffic from within AWS. Set up a load balancer with internet access later to redirect traffic to the server instances. For debugging purposes, create an SSH key pair to connect to the instance. -In the advanced details section, set the IAM instance profile to the profile with the `AWSSecretsManagerClientReadOnlyAccess` role and `AmazonS3ReadOnlyAccess` role. Also in the Advanced Details section, scroll down to the user data field. This is where you can upload or copy and paste the cloud-init module. The following example shows the cloud-init template from earlier configured to run on AWS using S3 buckets as patch storage. +In the Advanced Details section, set the IAM instance profile to the profile with the `AWSSecretsManagerClientReadOnlyAccess` role and `AmazonS3ReadOnlyAccess` role. Also in the Advanced Details section, scroll down to the User Data field to upload or paste the cloud-init module. The following example shows the cloud-init template configured to run on AWS using S3 buckets as patch storage: ```yaml #cloud-config @@ -147,31 +148,35 @@ runcmd: - | rm /etc/livepatch/* -final_message: The system is up, up to date, and Livepatch server is active after $UPTIME second +final_message: The system is up, up to date, and Livepatch Server is active after $UPTIME second ``` -Where the blanked out values will be where you put your relevant resource information. For this template, the S3 and database secrets are assumed to be stored in a JSON object, while the Ubuntu Pro token and admin user string are plaintext. +Replace the blanked-out values with the relevant resource information. For this template, the S3 and database secrets are assumed to be stored in a JSON object, while the Ubuntu Pro token and admin user string are plaintext. + +### Test the deployment -Once you have a launch template created, test the deployment by going to **Launch Instances** and then to **Launch Instance from Template**. On the launch page, make sure to set the template version to the correct version if you have multiple versions. The instance will take a few minutes to create and configure Livepatch server. Once the instance is ready, you can check if the deployment is complete by running: +Once a launch template is created, test the deployment by going to **Launch Instances** and then to **Launch Instance from Template**. On the launch page, ensure the template version is set to the correct version if multiple versions exist. The instance takes a few minutes to create and configure the Livepatch Server. Once the instance is ready, check if the deployment is complete by running: ```bash sudo snap logs canonical-livepatch-server ``` -If there are no error logs, then the server has successfully initialized. If there are errors, check the status of `cloud-init` with: +If there are no error logs, the server has initialized successfully. If there are errors, check the status of `cloud-init` with: ```bash cloud-init status --long ``` -If the status shows: **error**, then something went wrong during the cloud-init procedure. You can view the command output logs at `/var/log/cloud-init-output.log`. +If the status shows **error**, something went wrong during the cloud-init procedure. The command output logs can be viewed at `/var/log/cloud-init-output.log`. + +### Create the auto-scaling group -With the server launch template ready, next navigate to the auto-scaling groups section and head to **Create Auto Scaling Group**. Give it a name and select the launch template we just created in the previous step. For optimal availability, set the number of instances to be between two and four. +With the server launch template ready, navigate to the Auto Scaling Groups section and select **Create Auto Scaling Group**. Provide a name and select the launch template created in the previous step. For optimal availability, set the number of instances to between two and four. -Next, select the region and availability zones you want instances to be created in. Give the auto-scaling group a security group that has access to inside AWS (for the server instances), but allow all HTTP and HTTPS traffic so a load balancer can route incoming traffic. The default VPC will suffice for a multi-unit deployment. +Next, select the region and availability zones where instances should be created. Assign a security group that has access to inside AWS (for the server instances), but allow all HTTP and HTTPS traffic so a load balancer can route incoming traffic. The default VPC is sufficient for a multi-unit deployment. -If you already have a load balancer set up, you can link the auto-scaling group to it. If not, select Attach to a new load balancer. Set the default routing (forward to) option to Create a target group, which will set the load balancer to forward traffic to all instances created by the auto scaling group. +If a load balancer is already set up, the auto-scaling group can be linked to it. If not, select **Attach to a new load balancer**. Set the default routing (forward to) option to **Create a target group**, which configures the load balancer to forward traffic to all instances created by the auto-scaling group. On the next page, configure the group size and scaling options, and optionally an automatic scaling policy and maintenance policy. -Once the auto-scaling group is created, it will begin to provision Livepatch server instances based on the given launch template. You can then log in with the admin tool (assuming you defined an admin user in the cloud-init config) by setting the endpoint URL to the public URL of the load balancer. Make sure the security settings for the load balancer allow external traffic so you can login and run administrative duties with the admin tool. +Once the auto-scaling group is created, it begins provisioning Livepatch Server instances based on the given launch template. The admin tool can then be used to log in (assuming an admin user was defined in the cloud-init configuration) by setting the endpoint URL to the public URL of the load balancer. Ensure the security settings for the load balancer allow external traffic so administrative duties can be performed with the admin tool. diff --git a/docs/server/how-to-guides/deployment/public-clouds/deploying-on-azure.md b/docs/server/how-to-guides/deployment/public-clouds/deploying-on-azure.md index 54984ad..17f4de5 100644 --- a/docs/server/how-to-guides/deployment/public-clouds/deploying-on-azure.md +++ b/docs/server/how-to-guides/deployment/public-clouds/deploying-on-azure.md @@ -1,44 +1,57 @@ --- myst: html_meta: - description: "How to deploying on azure on public clouds with Livepatch server." + description: "How to deploy the Livepatch Server snap on Azure." --- (server-how-to-guides-deploying-the-livepatch-server-snap-on-azure)= -# Deploying the Livepatch Server snap on Azure +# How to deploy on Azure This section details how to deploy the Livepatch Server snap in auto-scaling configuration on Azure. -## Required Resources +## Required resources -To set up Livepatch server on Azure using an Filesystem or PostgreSQL (Azure Blob Store is not yet supported) for patch storage, you will need: +To set up the Livepatch Server on Azure using a filesystem or PostgreSQL (Azure Blob Storage is not yet supported) for patch storage, the following are required: -- A VNet with subnets for VMSS, Application Gateway and PostgreSQL DB. -- An Azure Key Vault with access enabled for the VMSS subnet of the VNet. -- An Azure-managed PostgreSQL instance with PostgreSQL 14 or above using password authentication. - - Username and password stored in Azure Key Vault as a JSON object. -- A Virtual Machine ScaleSet (VMSS) with an instance type with at least 2 vCPUs, 4 GB RAM with cloud-init config file as custom data. -- An Ubuntu Pro token stored as a secret in Azure Key Vault. -- Livepatch server admin credentials stored in Azure Key Vault Secrets in `:` format. -- A Managed Identity with the `Key Vault Secrets User` role in Azure Key Vault. -- An Application Gateway with a public IP address as an entry point for accessing Livepatch server. -- A VMSS as backend pool with the corresponding Managed Identity attached to it. +* A VNet with subnets for VMSS, Application Gateway, and PostgreSQL DB. +* An Azure Key Vault with access enabled for the VMSS subnet of the VNet. +* An Azure-managed PostgreSQL instance with PostgreSQL 14 or above using password authentication. The username and password stored in Azure Key Vault as a JSON object. +* A Virtual Machine Scale Set (VMSS) with an instance type with at least two vCPUs and 4 GB RAM, with a cloud-init configuration file as custom data. +* An Ubuntu Pro token stored as a secret in Azure Key Vault. +* Livepatch Server admin credentials stored in Azure Key Vault Secrets in `:` format. +* A Managed Identity with the `Key Vault Secrets User` role in Azure Key Vault. +* An Application Gateway with a public IP address as an entry point for accessing the Livepatch Server. +* A VMSS as a backend pool with the corresponding Managed Identity attached. -## Creating The Deployment +## Create the deployment -In Azure, Livepatch can be deployed on VMSS behind an Application Gateway with autoscaling configured on VMSS instances. The VMSS instances can be configured to auto-install Livepatch server snap at startup using cloud-init configuration file in a Standard Ubuntu Server image. This guide uses PostgreSQL server as patch storage. +In Azure, Livepatch can be deployed on VMSS behind an Application Gateway with autoscaling configured on VMSS instances. The VMSS instances can be configured to auto-install the Livepatch Server snap at startup using a cloud-init configuration file in a Standard Ubuntu Server image. This guide uses a PostgreSQL server for patch storage. -Configure a VNet with 3 different subnets, one for each: Application Gateway, VMSS, DB. The Application Gateway subnet should have at least 256 addresses. +### Configure the VNet -Create an Azure-managed PostgreSQL DB with PostgreSQL password authentication. Disable public access and use the DB subnet from the VNet to provision the DB. Create a database in this PostgreSQL server for Livepatch Server to use (this can be done from Azure UI). +Configure a VNet with three different subnets, one for each: Application Gateway, VMSS, and DB. The Application Gateway subnet should have at least 256 addresses. + +### Create the PostgreSQL database + +Create an Azure-managed PostgreSQL DB with PostgreSQL password authentication. Disable public access and use the DB subnet from the VNet to provision the database. Create a database in this PostgreSQL server for the Livepatch Server to use. This can be performed from the Azure UI. + +### Create the Managed Identity Create a Managed Identity. This will be assigned to the VMSS to allow access to Azure Key Vault. -Create an Azure Key Vault with Public Access disabled. Allow access from the VMSS subnet of the VNet. Store the DB credentials (JSON format), admin credentials (`:` format) and pro token (raw string) in the Key vault. Assign “Key Vault Secrets User” role for this Vault to the Managed Identity. +### Create the Azure Key Vault + +Create an Azure Key Vault with public access disabled. Allow access from the VMSS subnet of the VNet. Store the DB credentials (JSON format), admin credentials (`:` format), and Pro token (raw string) in the Key Vault. Assign the `Key Vault Secrets User` role for this Vault to the Managed Identity. -For VMSS, Select an instance type that has sufficient CPU and memory capacity. The minimum resources required for Livepatch server to run efficiently are 2 vCPU and 4 GB memory. Avoid using B-series instances. For the storage options, the default volume size of 30GB will be sufficient. Assign the Managed Identity to the VMSS to allow access to Azure Key Vault. Configure the VMSS NSG to allow traffic on port 80 from within the VNet. It is recommended to not have public IP addresses assigned to the VMSS VMs. This will ensure that VMs can be accessed only via Application Gateway. Provision a jumpbox in the same VNet with public IP to access VMs, if and when required. Add the following cloud-init config file to the CustomData field: +### Configure the VMSS + +For VMSS, select an instance type with sufficient CPU and memory capacity. The minimum resources required for the Livepatch Server to run efficiently are two vCPUs and 4 GB memory. Avoid using B-series instances. For storage options, the default volume size of 30 GB is sufficient. Assign the Managed Identity to the VMSS to allow access to Azure Key Vault. + +Configure the VMSS NSG to allow traffic on port 80 from within the VNet. It is recommended not to have public IP addresses assigned to the VMSS VMs. This ensures that VMs can be accessed only through the Application Gateway. Provision a jumpbox in the same VNet with a public IP to access VMs when required. + +Add the following cloud-init configuration file to the Custom Data field: ```yaml #cloud-config @@ -154,27 +167,29 @@ runcmd: - | rm /etc/livepatch/* -final_message: The system is up, up to date, and Livepatch server is active after $UPTIME second +final_message: The system is up, up to date, and Livepatch Server is active after $UPTIME second ``` -Ensure that correct ENV var values are filled in the `write-files` section of the config. +Ensure the correct environment variable values are filled in the `write_files` section of the configuration. + +### Provision the Application Gateway -Provision a Standard V2 (or WAF V2) Application Gateway in the subnet created in the VNet with autoscaling enabled. The minimum instance count for the same should be set according to the expected traffic. Add the VMSS to the backend pool of the Application Gateway and route all traffic to this pool. Use port 80 with `GET /` as the health check endpoint for the VMSS. +Provision a Standard V2 (or WAF V2) Application Gateway in the subnet created in the VNet with autoscaling enabled. The minimum instance count should be set according to the expected traffic. Add the VMSS to the backend pool of the Application Gateway and route all traffic to this pool. Use port 80 with `GET /` as the health check endpoint for the VMSS. Autoscaling on VMSS should be configured based on both CPU and RAM metrics. ## Troubleshooting -You can ssh into VMSS instances to check livepatch server status. You can check if Livepatch server snap logs by running: +SSH into VMSS instances to check the Livepatch Server status. Check the Livepatch Server snap logs by running: ```shell sudo snap logs canonical-livepatch-server ``` -If there are no error logs, then the server has successfully initialized. If there are errors, check the status of +If there are no error logs, the server has initialized successfully. If there are errors, check the status of `cloud-init`: ```shell cloud-init status --long ``` -If the status shows: **error**, then something went wrong during the cloud-init procedure. You can view the command output logs at `/var/log/cloud-init-output.log`. +If the status shows **error**, something went wrong during the cloud-init procedure. The command output logs can be viewed at `/var/log/cloud-init-output.log`. diff --git a/docs/server/how-to-guides/deployment/public-clouds/index.md b/docs/server/how-to-guides/deployment/public-clouds/index.md index d49bd02..8e5ba0b 100644 --- a/docs/server/how-to-guides/deployment/public-clouds/index.md +++ b/docs/server/how-to-guides/deployment/public-clouds/index.md @@ -1,34 +1,34 @@ --- myst: html_meta: - description: "How to deploying-the-livepatch-server-snap-on-public-clouds on public clouds with Livepatch server." + description: "How to deploy the Livepatch Server snap on public clouds." --- (server-how-to-guides-deployment-public-clouds)= -# Deploying The Livepatch Server Snap On Public Clouds +# How to deploy on public clouds -This section details how to launch the Livepatch server snap on public clouds, with single or multi unit deployments using an auto scaling solution from the cloud provider. +This section details how to launch the Livepatch Server snap on public clouds, with single-unit or multi-unit deployments using an auto-scaling solution from the cloud provider. ## Prerequisites -Before deploying the server snap, you will need the following: +Before deploying the server snap, the following are required: -- Two or more VMs with at least Ubuntu 22.04 LTS, with at least 2 CPU cores and at least 4GB of RAM (between two and four VMs will suffice). -- A PostgreSQL DNS for an instance with a database ready to be initialized. -- A secure vault for storing secrets (via an AWS IAM role, or Azure Key Vault) -- A storage solution: S3, Ceph, or PostgreSQL connection string. -- An Ubuntu Pro token from [ubuntu.com/pro/dashboard](https://ubuntu.com/pro/dashboard). -- Optional: the [CVE service](https://snapcraft.io/canonical-livepatch-cve-service) deployed and ready for connections. +* Two or more VMs with at least Ubuntu 22.04 LTS, with at least two CPU cores and at least 4 GB of RAM. Between two and four VMs are sufficient. +* A PostgreSQL DNS for an instance with a database ready to be initialized. +* A secure vault for storing secrets: an AWS IAM role or Azure Key Vault. +* A storage solution: S3, Ceph, or a PostgreSQL connection string. +* An Ubuntu Pro token from [ubuntu.com/pro/dashboard](https://ubuntu.com/pro/dashboard). +* Optional: the [CVE service](https://snapcraft.io/canonical-livepatch-cve-service) deployed and ready for connections. -> Note: This setup is incompatible with Ubuntu core. +> This setup is incompatible with Ubuntu Core. -Sensitive data such as connection strings, and the pro token, should be stored in a vault we will access later during the installation. +Sensitive data such as connection strings and the Pro token should be stored in a vault that is accessed later during the installation. -## Livepatch server installation with cloud-init +## Install Livepatch Server with cloud-init -You can easily create VMs and initialize Livepatch with [cloud-init](https://docs.cloud-init.io/en/latest/): create a `cloud-config.yaml` file with the following template including setup steps to install Livepatch server: +VMs can be created and Livepatch can be initialized with [cloud-init](https://docs.cloud-init.io/en/latest/). Create a `cloud-config.yaml` file with the following template, including setup steps to install the Livepatch Server: ```yaml #cloud-config @@ -93,33 +93,35 @@ runcmd: rm /etc/livepatch/* -final_message: The system is up, up to date, and Livepatch server is active after $UPTIME second +final_message: The system is up, up to date, and Livepatch Server is active after $UPTIME second ``` -This template config performs the following commands: +This template configuration performs the following operations: -- Waits until snapd is ready. -- Installs the canonical-livepatch-server snap and stops the server temporarily for configuration. -- Initializes the provided database with the latest schema (if the database schema is up to date, this operation won’t perform updates). -- Points Livepatch server to the configured database -- Enables the server with an Ubuntu Pro token. -- Sets up an admin user. -- Sets the server for all traffic on port 80. -- Starts the server with the provided configuration. -- Cleans up temporary files used in configuration. +* Waits until snapd is ready. +* Installs the `canonical-livepatch-server` snap and stops the server temporarily for configuration. +* Initializes the provided database with the latest schema. If the database schema is already up to date, no updates are performed. +* Points the Livepatch Server to the configured database. +* Enables the server with an Ubuntu Pro token. +* Sets up an admin user. +* Configures the server for all traffic on port 80. +* Starts the server with the provided configuration. +* Cleans up temporary files used in configuration. -This cloud-init module expects to find required parameters (secrets, user strings, database DNS) in root-only files located at `/etc/livepatch/` during boot time. Specifics on getting required secrets are unique to the cloud environment. We recommend using the cloud’s vault provider to securely access the secrets and write them to the required locations. The files are deleted during the last step of the cloud-init setup. +This cloud-init module expects to find required parameters (secrets, user strings, database DNS) in root-only files located at `/etc/livepatch/` during boot time. The method for obtaining the required secrets is unique to the cloud environment. The recommended approach is to use the cloud's vault provider to securely access the secrets and write them to the required locations. The files are deleted during the final step of the cloud-init setup. -In the config, you may also want to setup basic authentication, and add a user for the admin tool with these commands: +## Set up authentication + +In the configuration, basic authentication can be set up and a user can be added for the admin tool with these commands: ```bash snap set canonical-livepatch-server lp.auth.basic.enabled=true snap set canonical-livepatch-server lp.auth.basic.users="$(cat /etc/livepatch/livepatch_admin_user)" ``` -Where the user and hashed password in the form of _**username:hashedpassword**_ are fetched from a secure vault and written to a root-only file `/etc/livepatch/livepatch_admin_user`. +Where the user and hashed password in the form of `username:hashedpassword` are fetched from a secure vault and written to a root-only file at `/etc/livepatch/livepatch_admin_user`. -Make sure to make this file root accessible only by adding a field in the write_files section: +To ensure the file is root-accessible only, add a field in the `write_files` section: ```yaml - path: /etc/livepatch/livepatch_admin_user @@ -127,18 +129,20 @@ Make sure to make this file root accessible only by adding a field in the write_ owner: root:root ``` -> Note: Livepatch server requires the pro token, database connection string, and storage connection string to operate, but do not put these values in the configuration file as plain text, use your cloud provider's secrets manager. +> The Livepatch Server requires the Pro token, database connection string, and storage connection string to operate. Do not put these values in the configuration file as plain text. Use the cloud provider's secrets manager. + +## Set up periodic patch sync -Additionally, you can set up periodic patch syncs with the hosted Livepatch server with: +Periodic patch syncs with the hosted Livepatch Server can be configured with: ```bash snap set canonical-livepatch-server lp.patch-sync.enabled=true snap set canonical-livepatch-server lp.patch-sync.interval=12h ``` -All configuration can be done with a single snap set command by putting all configuration values in a single line, as done in the template cloud-init module. +All configuration can be performed with a single `snap set` command by placing all configuration values in a single line, as shown in the template cloud-init module. -With all the configurations written in the cloud-config.yaml you can easily create VM instances by passing in the config with Livepatch server installed and ready to receive traffic. +With all configurations written in the `cloud-config.yaml`, VM instances can be created by passing in the configuration. The Livepatch Server is installed and ready to receive traffic. ```{toctree} :titlesonly: diff --git a/docs/server/how-to-guides/deployment/upgrade-a-deployment.md b/docs/server/how-to-guides/deployment/upgrade-a-deployment.md index c0efe57..3af3f3b 100644 --- a/docs/server/how-to-guides/deployment/upgrade-a-deployment.md +++ b/docs/server/how-to-guides/deployment/upgrade-a-deployment.md @@ -1,14 +1,15 @@ --- myst: html_meta: - description: "How to upgrade a deployment with Livepatch on-prem." + description: "How to upgrade a Livepatch on-premises deployment." --- + (server-how-to-guides-how-to-upgrade-a-livepatch-on-prem-deployment)= -# How to upgrade a Livepatch on-prem deployment +# How to upgrade a deployment -To upgrade the livepatch on-prem deployment, each application needs to be upgraded separately: +To upgrade the Livepatch on-premises deployment, each application must be upgraded separately: ``` juju refresh haproxy @@ -26,17 +27,17 @@ juju refresh ubuntu-advantage juju refresh livepatch ``` -After upgrading the livepatch application, a schema upgrade may be required. This will be indicated in the application's status in juju status. In such a case, run the command: +After upgrading the Livepatch application, a schema upgrade may be required. This is indicated in the application's status when running `juju status`. In such a case, run: ``` juju run-action livepatch/leader schema-upgrade --wait ``` -One can also restart the livepatch application with the following command: +The Livepatch application can also be restarted with the following command: ``` juju run-action livepatch/ restart --wait ``` -> Note: `juju run-action` has been renamed to `juju run` from Juju v3 -> See https://documentation.ubuntu.com/juju/latest/howto/manage-actions/#run-an-action for more details. +> `juju run-action` has been renamed to `juju run` from Juju v3. +> See the [Juju documentation on managing actions](https://documentation.ubuntu.com/juju/latest/howto/manage-actions/#run-an-action) for more details. diff --git a/docs/server/how-to-guides/index.md b/docs/server/how-to-guides/index.md index ea0951d..5a9cc24 100644 --- a/docs/server/how-to-guides/index.md +++ b/docs/server/how-to-guides/index.md @@ -7,16 +7,16 @@ myst: (server-how-to-guides)= -# How-To-Guides +# How-to guides -Step-by-step guides covering key operations and common tasks related to Livepatch on-prem server. +Step-by-step guides covering key operations and common tasks for the Livepatch on-premises server. ## In this section -- [Deployment](/server/how-to-guides/deployment/index.md) — Deploy, upgrade, and migrate a Livepatch Server installation. -- [Patch management](/server/how-to-guides/patch-management/index.md) — Fetch, download, proxy, and chain patches across servers. -- [Operations](/server/how-to-guides/operations/index.md) — Run, scale, monitor, and decommission a deployment. -- [Security](/server/how-to-guides/security/index.md) — Secure the server with TLS, hardening, admin tooling, and vulnerability reporting. +* [Deployment](/server/how-to-guides/deployment/index.md): Deploy, upgrade, and migrate a Livepatch Server installation. +* [Patch management](/server/how-to-guides/patch-management/index.md): Fetch, download, proxy, and chain patches across servers. +* [Operations](/server/how-to-guides/operations/index.md): Run, scale, monitor, and decommission a deployment. +* [Security](/server/how-to-guides/security/index.md): Secure the server with TLS, hardening, admin tooling, and vulnerability reporting. ```{toctree} :titlesonly: @@ -27,4 +27,4 @@ Deployment Patch management Operations Security -``` +``` \ No newline at end of file diff --git a/docs/server/how-to-guides/operations/configure-logging-and-monitoring.md b/docs/server/how-to-guides/operations/configure-logging-and-monitoring.md index 868e60e..9f7ad68 100644 --- a/docs/server/how-to-guides/operations/configure-logging-and-monitoring.md +++ b/docs/server/how-to-guides/operations/configure-logging-and-monitoring.md @@ -7,9 +7,9 @@ myst: (server-how-to-guides-configure-logging-and-monitoring-for-livepatch-server)= -# Configure logging and monitoring for Livepatch server +# Configure logging and monitoring for the Livepatch Server -The Livepatch Server provides structured security event logging and Prometheus metrics for monitoring. This document describes how to configure and consume these security-relevant features. For general monitoring concepts and debug endpoints, see the existing [Logging and Monitoring explanation](/server/explanation/observability/logging-and-monitoring.md). +The Livepatch Server provides structured security event logging and Prometheus metrics for monitoring. The following sections describe how to configure and consume these security-relevant features. For general monitoring concepts and debug endpoints, see the [Logging and Monitoring explanation](/server/explanation/observability/logging-and-monitoring.md). (server-how-to-guides-configure-the-log-level)= @@ -39,11 +39,11 @@ juju config canonical-livepatch-server-k8s server.log-level=info All security events are emitted to the standard logger output as structured JSON. Each event includes a `type: "security"` field for filtering. The following categories of security events are logged: -- **Authentication successes and failures** for all authentication methods (Basic Auth, Macaroons, machine tokens, resource tokens, sync tokens, webhook tokens) -- **Authorization failures** (tier mismatches, invalid affordances, unauthorized access attempts) -- **Token lifecycle events** (creation, deletion, and updates of authentication tokens) -- **Administrative activity** (all admin API requests with identity and endpoint information) -- **System events** (startup, shutdown, crash, and OS signal handling) +* **Authentication successes and failures** for all authentication methods (Basic Auth, Macaroons, machine tokens, resource tokens, sync tokens, webhook tokens) +* **Authorization failures** (tier mismatches, invalid affordances, unauthorized access attempts) +* **Token lifecycle events** (creation, deletion, and updates of authentication tokens) +* **Administrative activity** (all admin API requests with identity and endpoint information) +* **System events** (startup, shutdown, crash, and OS signal handling) ## Configure Prometheus monitoring @@ -112,21 +112,21 @@ Container logs are available through standard Kubernetes log collection: kubectl logs -n | grep '"type":"security"' ``` -The server also writes logs to `/var/log/livepatch` inside the container, with logrotate configured for daily rotation (3 files retained, 10MB size trigger, compression enabled). +The server also writes logs to `/var/log/livepatch` inside the container, with logrotate configured for daily rotation (three files retained, 10MB size trigger, compression enabled). When integrated with Loki via the `logging` or `log-proxy` relations, logs are forwarded automatically and can be queried through Grafana. ## Charm log redaction -The charm itself (not the server binary) includes a log redaction module that scrubs sensitive data from charm operator logs. The following patterns are redacted before logs reach any handler: +The charm (not the server binary) includes a log redaction module that scrubs sensitive data from charm operator logs. The following patterns are redacted before logs reach any handler: -- Database connection URIs with embedded credentials (e.g., `postgresql://user:password@host/db`) -- HTTP Authorization headers (`Bearer` and `Basic` tokens) -- Key-value pairs where the key implies a secret (e.g., `password=`, `token=`, `api-key=`, `credentials=`) -- Specific environment variables: `LP_CONTRACTS_PASSWORD`, `LP_PATCH_SYNC_TOKEN`, `LP_PATCH_STORAGE_S3_SECRET_KEY`, `LP_PATCH_STORAGE_S3_ACCESS_KEY`, `LP_PATCH_STORAGE_SWIFT_API_KEY`, `LP_AUTH_BASIC_USERS`, `LP_AUTH_SSO_PUBLIC_KEY`, `LP_DATABASE_CONNECTION_STRING`, and others +* Database connection URIs with embedded credentials (e.g., `postgresql://user:password@host/db`) +* HTTP Authorization headers (`Bearer` and `Basic` tokens) +* Key-value pairs where the key implies a secret (e.g., `password=`, `token=`, `api-key=`, `credentials=`) +* Specific environment variables: `LP_CONTRACTS_PASSWORD`, `LP_PATCH_SYNC_TOKEN`, `LP_PATCH_STORAGE_S3_SECRET_KEY`, `LP_PATCH_STORAGE_S3_ACCESS_KEY`, `LP_PATCH_STORAGE_SWIFT_API_KEY`, `LP_AUTH_BASIC_USERS`, `LP_AUTH_SSO_PUBLIC_KEY`, `LP_DATABASE_CONNECTION_STRING`, and others All redacted values are replaced with `***REDACTED***` in log output. ## Risks of disabling logging -Reducing the log level to `error` or `fatal` will suppress security event logs at the `info` and `warn` levels, which includes authentication successes, token lifecycle events, and administrative activity. This significantly reduces visibility into security-relevant operations and is not recommended for production deployments. +Reducing the log level to `error` or `fatal` suppresses security event logs at the `info` and `warn` levels, which includes authentication successes, token lifecycle events, and administrative activity. This significantly reduces visibility into security-relevant operations and is not recommended for production deployments. \ No newline at end of file diff --git a/docs/server/how-to-guides/operations/decommission.md b/docs/server/how-to-guides/operations/decommission.md index f3a8788..b23db66 100644 --- a/docs/server/how-to-guides/operations/decommission.md +++ b/docs/server/how-to-guides/operations/decommission.md @@ -7,9 +7,9 @@ myst: (server-how-to-guides-decommission-livepatch-server-securely)= -# Decommission Livepatch server securely +# Decommission a Livepatch Server securely -This document provides guidance on securely removing the Livepatch Server and all associated data from the environment. +The following procedures describe how to securely remove the Livepatch Server and all associated data from the environment. ## Decommission a snap deployment @@ -50,16 +50,16 @@ DROP USER livepatch; ### Remove application logs -Snap application logs are captured by systemd-journald and cannot be removed independently without impacting other system logs. These logs will be automatically removed when the journal rotates according to the system's journald configuration. See the [journald configuration manpage](https://man7.org/linux/man-pages/man5/journald.conf.5.html) for details on configuring rotation and retention. +Snap application logs are captured by systemd-journald and cannot be removed independently without impacting other system logs. These logs are automatically removed when the journal rotates according to the system's journald configuration. See the [journald configuration manpage](https://man7.org/linux/man-pages/man5/journald.conf.5.html) for details on configuring rotation and retention. ### Remove patch storage data Remove patch files from the configured storage backend: -- **Filesystem**: Delete the patches directory (default: `/var/lib/livepatch/patches`). -- **S3**: Delete the configured S3 bucket or its contents. -- **Swift**: Delete the configured Swift container or its contents. -- **PostgreSQL**: Patch data is removed when the database is dropped. +* **Filesystem**: Delete the patches directory (default: `/var/lib/livepatch/patches`). +* **S3**: Delete the configured S3 bucket or its contents. +* **Swift**: Delete the configured Swift container or its contents. +* **PostgreSQL**: Patch data is removed when the database is dropped. ## Decommission a charm deployment @@ -83,7 +83,7 @@ juju destroy-model --destroy-storage --force After decommissioning, ensure that any secrets stored outside the deployment are also removed: -- Juju secrets created for the application -- Environment variable files or shell history containing credentials -- Backup copies of configuration files containing admin passwords or database connection strings -- Admin tool token files stored at `~/snap/canonical-livepatch-server-admin/common/tokens` on any machine where the admin tool was used +* Juju secrets created for the application +* Environment variable files or shell history containing credentials +* Backup copies of configuration files containing admin passwords or database connection strings +* Admin tool token files stored at `~/snap/canonical-livepatch-server-admin/common/tokens` on any machine where the admin tool was used \ No newline at end of file diff --git a/docs/server/how-to-guides/operations/generate-patch-health-report.md b/docs/server/how-to-guides/operations/generate-patch-health-report.md index 62da187..6e68d10 100644 --- a/docs/server/how-to-guides/operations/generate-patch-health-report.md +++ b/docs/server/how-to-guides/operations/generate-patch-health-report.md @@ -6,10 +6,10 @@ myst: (server-how-to-guides-how-to-generate-livepatch-on-prem-patch-health-report)= -# How to generate Livepatch on-prem patch health report +# Generate a Livepatch on-premises patch health report To generate a report of how many machines applied (or failed to apply) a specific patch, run: ``` livepatch-admin report patch-health -``` +``` \ No newline at end of file diff --git a/docs/server/how-to-guides/operations/index.md b/docs/server/how-to-guides/operations/index.md index ff7e4fb..c5c7999 100644 --- a/docs/server/how-to-guides/operations/index.md +++ b/docs/server/how-to-guides/operations/index.md @@ -13,12 +13,12 @@ Run, scale, monitor, and decommission a deployment. ## In this section -- [Manage fleet of machines](/server/how-to-guides/operations/manage-fleet-of-machines.md) -- [Generate patch health report](/server/how-to-guides/operations/generate-patch-health-report.md) -- [Scale out](/server/how-to-guides/operations/scale-out.md) -- [Configure logging and monitoring](/server/how-to-guides/operations/configure-logging-and-monitoring.md) -- [Decommission](/server/how-to-guides/operations/decommission.md) -- [Use Livepatch client with on-prem server](/server/how-to-guides/operations/use-livepatch-client-with-on-prem-server.md) +* [Manage a fleet of machines](/server/how-to-guides/operations/manage-fleet-of-machines.md) +* [Generate a patch health report](/server/how-to-guides/operations/generate-patch-health-report.md) +* [Scale out](/server/how-to-guides/operations/scale-out.md) +* [Configure logging and monitoring](/server/how-to-guides/operations/configure-logging-and-monitoring.md) +* [Decommission](/server/how-to-guides/operations/decommission.md) +* [Use a Livepatch Client with an on-premises server](/server/how-to-guides/operations/use-livepatch-client-with-on-prem-server.md) ```{toctree} :titlesonly: @@ -30,5 +30,5 @@ Generate patch health report Scale out Configure logging and monitoring Decommission -Use livepatch client with on prem server -``` +Use Livepatch Client with on prem server +``` \ No newline at end of file diff --git a/docs/server/how-to-guides/operations/manage-fleet-of-machines.md b/docs/server/how-to-guides/operations/manage-fleet-of-machines.md index 17aaa38..1236480 100644 --- a/docs/server/how-to-guides/operations/manage-fleet-of-machines.md +++ b/docs/server/how-to-guides/operations/manage-fleet-of-machines.md @@ -6,30 +6,30 @@ myst: (server-how-to-guides-how-to-manage-livepatch-on-prem-fleet)= -# How to manage Livepatch on-prem fleet +# Manage a Livepatch on-premises fleet -Livepatch server stores information about the status of machines attached to it. This can be used to identify machines which failed to apply patches. +The Livepatch Server stores information about the status of machines attached to it. This information can be used to identify machines that failed to apply patches. ``` livepatch-admin report machines [] [] ``` -The output of this command will contain a list of machines, along with their machine IDs and additional information. +The output of this command contains a list of machines, along with their machine IDs and additional information. - is one of: +`` is one of: -- applied -- apply-failed -- unapplied -- needs-check -- nothing-to-apply -- unknown -- check-failed -- applied-with-bug -- Kernel-upgrade-required +* applied +* apply-failed +* unapplied +* needs-check +* nothing-to-apply +* unknown +* check-failed +* applied-with-bug +* Kernel-upgrade-required -Note that the machine IDs correspond to unique livepatch clients. To associate each client system with the machine ID you can run the command below on the client. +The machine IDs correspond to unique Livepatch Clients. To associate each client system with its machine ID, run the following command on the client: ``` cat /etc/machine-id -``` +``` \ No newline at end of file diff --git a/docs/server/how-to-guides/operations/scale-out.md b/docs/server/how-to-guides/operations/scale-out.md index b9444be..1dac991 100644 --- a/docs/server/how-to-guides/operations/scale-out.md +++ b/docs/server/how-to-guides/operations/scale-out.md @@ -6,14 +6,14 @@ myst: (server-how-to-guides-how-to-scale-out-a-livepatch-on-prem-deployment)= -# How to scale out a Livepatch on-prem deployment +# Scale out a Livepatch on-premises deployment -There are several possible scenarios where scaling out a livepatch deployment could be necessary: +Scaling out a Livepatch deployment may be necessary in the following scenarios: -1. High traffic due to large amount of machines being serviced +1. High traffic due to a large number of machines being serviced 2. High availability setups -The livepatch on-prem deployment consists of 3 main components: the `haproxy` reverse-proxying requests, `postgresql` storing livepatch data and `livepatch server` itself. Any one (or all) of these components can be scaled out with additional units by running the `juju` command with the following syntax: +The Livepatch on-premises deployment consists of three main components: `haproxy` reverse-proxying requests, `postgresql` storing Livepatch data, and the `Livepatch Server` itself. Any or all of these components can be scaled out with additional units by running the `juju` command with the following syntax: ``` juju add-unit -n @@ -23,31 +23,31 @@ Where `` is `haproxy`, `postgresql` or `livepatch` and ` ``` -The tier parameter is one of the tiers available on the server. The client will download patches as they become available in that tier. See [this page](/server/reference/patch-management/patch-management.md) on how to manage tiers and patches in your on-prem server. +The tier parameter is one of the tiers available on the server. The client downloads patches as they become available in that tier. See [Patch management](/server/reference/patch-management/patch-management.md) for details on managing tiers and patches in the on-premises server. -The id parameter bears no significance in an on-prem deployment. It can be set to a value identifying the group of livepatch clients that will be enabled using the same token (a single authorization token can be used to enable multiple client instances). +The id parameter bears no significance in an on-premises deployment. It can be set to a value identifying the group of Livepatch Clients that will be enabled using the same token. A single authorization token can be used to enable multiple client instances. -## Configuring livepatch client +## Configure the Livepatch Client -To start applying livepatches to a machine, it is necessary to install the livepatch client on it. Livepatch client is currently distributed as a snap. On the machine run: +To start applying live kernel patches to a machine, install the Livepatch Client on it. The Livepatch Client is distributed as a snap. On the machine, run: ``` sudo snap install canonical-livepatch ``` -Once the client is installed, it needs to be configured to pull patches from the on-prem server: +After the client is installed, configure it to pull patches from the on-premises server: ``` canonical-livepatch config remote-server="http(s)://" ``` -The authorization token returned can be then used to attach any number of machines to the on-prem livepatch server: +The authorization token can then be used to attach any number of machines to the on-premises Livepatch Server: ``` canonical-livepatch enable -``` +``` \ No newline at end of file diff --git a/docs/server/how-to-guides/patch-management/chain-livepatch-servers.md b/docs/server/how-to-guides/patch-management/chain-livepatch-servers.md index 629e2cf..b6d543d 100644 --- a/docs/server/how-to-guides/patch-management/chain-livepatch-servers.md +++ b/docs/server/how-to-guides/patch-management/chain-livepatch-servers.md @@ -1,34 +1,34 @@ --- myst: html_meta: - description: "How to chain livepatch servers with Livepatch on-prem." + description: "How to chain Livepatch Servers." --- (server-how-to-guides-chain-on-prem-servers)= -# Chain On-Prem Servers +# Chain on-premises servers -As your Livepatch deployment grows, you may want to scale out beyond a single deployment. -This how-to document shows you how to chain multiple Livepatch on-prem servers together. +As a Livepatch deployment grows, scaling out beyond a single deployment may be desirable. +This how-to document describes how to chain multiple Livepatch on-premises servers together. This is useful in a few scenarios: - Running the server in multiple availability zones or regions. -- Isolating machines to a specific on-prem instance. +- Isolating machines to a specific on-premises instance. - Increasing the scale of a deployment without HA. -In order to chain on-prem server you need: +To chain on-premises servers, the following are needed: -- An existing Livepatch on-prem server. -- A new deployment of the Livepatch on-prem server. -- The Livepatch admin tool [setup](/server/how-to-guides/security/setup-administration-tool.md) against the existing server. +- An existing Livepatch on-premises server. +- A new deployment of the Livepatch on-premises server. +- The Livepatch admin tool [set up](/server/how-to-guides/security/setup-administration-tool.md) against the existing server. -When deploying an instance of the Livepatch server (see our existing [guides](/server/how-to-guides/index.md)) you will normally use an Ubuntu Pro token to configure the on-premise server to sync with Canonical's hosted Livepatch server. +When deploying an instance of the Livepatch Server (see the existing [guides](/server/how-to-guides/index.md)), an Ubuntu Pro token is normally used to configure the on-premises server to sync with Canonical's hosted Livepatch Server. -In this scenario, we can skip that step as we will use a token provided by our existing Livepatch server. +In this scenario, skip that step and use a token provided by the existing Livepatch Server. -Below we refer to the "upstream" server as the original Livepatch server and the "downstream" server as the new deployment that will sync from the "upstream". +Below, the "upstream" server is referred to as the original Livepatch Server and the "downstream" server as the new deployment that will sync from the "upstream". ## On the upstream server @@ -38,42 +38,42 @@ Using the admin tool: livepatch-admin sync-tokens add edge my-token ``` -This will return a token that another on-prem server can use to sync patches. +This will return a token that another on-premises server can use to sync patches. Sync tokens, by default, do not expire but the `--valid-until` flag can be used to set an expiry date. -Change `edge` if you would like to sync from a different tier. +Change `edge` if syncing from a different tier is desired. ```{note} -See our [reference doc](/server/reference/patch-management/patch-management.md) to better understand how tiers work and how patches are synced. +See the [reference doc](/server/reference/patch-management/patch-management.md) to better understand how tiers work and how patches are synced. ``` ## On the downstream server -Configure the following values on your charm/snap deployment: +Configure the following values on the charm or snap deployment: - Set `patch-sync.token` using the previously obtained token. - Set `patch-sync.upstream-url` to the upstream server URL. -You are now done configuring your downstream Livepatch server to sync from your upstream server. +The downstream Livepatch Server is now configured to sync from the upstream server. This process can be repeated as many times as desired. -## Syncing tiers (Optional) +## Sync tiers (optional) -Conventionally, each Livepatch on-prem server provides its own patch management using local tiers. +Conventionally, each Livepatch on-premises server provides its own patch management using local tiers. Patches can be promoted between tiers to provide phased rollouts. -To cater for scenarios where patch management should only be done in one place and synced to various downstream server, we offer the ability to sync tiers. +To cater for scenarios where patch management should only be done in one place and synced to various downstream servers, the ability to sync tiers is offered. Enabling this feature will do the following: - Match a server's tier structure to its upstream. This is a **destructive** operation and will remove any tiers that currently exist. -- Sync patch tier info from the upstream server. A patch e.g. 100.1 promoted to the "stable" tier upstream will automatically be reflected in the downstream server. +- Sync patch tier info from the upstream server. A patch, for example, 100.1 promoted to the "stable" tier upstream will automatically be reflected in the downstream server. -- Disables local patch management i.e. patches cannot be promoted between tiers and tiers cannot be created or destroyed through the admin tool. +- Disable local patch management, that is, patches cannot be promoted between tiers and tiers cannot be created or destroyed through the admin tool. This feature only needs to be enabled on the downstream server. No changes are needed on the upstream server. -Enable this functionality by setting the `patch-sync.sync-tiers` config value to `true`. +Enable this functionality by setting the `patch-sync.sync-tiers` config value to `true`. \ No newline at end of file diff --git a/docs/server/how-to-guides/patch-management/configure-proxy-for-fetching-patches.md b/docs/server/how-to-guides/patch-management/configure-proxy-for-fetching-patches.md index e8a734a..5a7f7fa 100644 --- a/docs/server/how-to-guides/patch-management/configure-proxy-for-fetching-patches.md +++ b/docs/server/how-to-guides/patch-management/configure-proxy-for-fetching-patches.md @@ -8,13 +8,13 @@ myst: # Use a proxy when fetching patches -Livepatch on-prem server can fetch patches through an HTTP proxy. The configuration steps vary depending on the deployment platform. +The Livepatch on-premises server can fetch patches through an HTTP proxy. The configuration steps vary depending on the deployment platform. -See our [patch-sync config](/server/reference/platform/configuration.md) for more details. +See the [patch-sync config](/server/reference/platform/configuration.md) for more details. ## Juju deployments (latest charms) -If Livepatch on-prem has been deployed using Juju, run the following Juju configuration command: +If Livepatch on-premises has been deployed using Juju, run the following Juju configuration command: ```bash juju config livepatch \ @@ -25,7 +25,7 @@ juju config livepatch \ ## Juju deployments (deprecated charm) -If Livepatch on-prem has been deployed using Juju with our older reactive charm (see our migration guide [here](/server/how-to-guides/deployment/migrate-from-reactive-charm-to-operator-charm.md)), run the following Juju configuration command: +If Livepatch on-premises has been deployed using Juju with the older reactive charm (see the [migration guide](/server/how-to-guides/deployment/migrate-from-reactive-charm-to-operator-charm.md)), run the following Juju configuration command: ```bash juju config livepatch \ @@ -35,7 +35,7 @@ juju config livepatch \ ## Snap deployments -If Livepatch on-prem has been deployed using Snap, users can run the following commands to configure a proxy: +If Livepatch on-premises has been deployed using Snap, run the following commands to configure a proxy: ```bash sudo snap set canonical-livepatch-server lp.patch-sync.proxy.enabled=true @@ -43,7 +43,7 @@ sudo snap set canonical-livepatch-server lp.patch-sync.proxy.http=http://proxy.e sudo snap set canonical-livepatch-server lp.patch-sync.proxy.https=http://proxy.example.com ``` -You can see the applied configuration by running the following: +The applied configuration can be viewed by running the following: ```bash sudo snap get canonical-livepatch-server lp.patch-sync.proxy @@ -51,4 +51,4 @@ Key Value lp.patch-sync.proxy.enabled true lp.patch-sync.proxy.http http://proxy.example.com lp.patch-sync.proxy.https http://proxy.example.com -``` +``` \ No newline at end of file diff --git a/docs/server/how-to-guides/patch-management/fetch-patches.md b/docs/server/how-to-guides/patch-management/fetch-patches.md index bbbb024..da005f3 100644 --- a/docs/server/how-to-guides/patch-management/fetch-patches.md +++ b/docs/server/how-to-guides/patch-management/fetch-patches.md @@ -6,9 +6,9 @@ myst: (server-how-to-guides-how-to-fetch-patches-to-livepatch-on-prem-server)= -# How to fetch patches to livepatch on-prem server +# Fetch patches to the Livepatch on-premises server -The livepatch application is configured to fetch patch updates every 24 hours. This setting is [configurable](/server/reference/platform/configuration.md). +The Livepatch application is configured to fetch patch updates every 24 hours. This setting is [configurable](/server/reference/platform/configuration.md). Patch snapshot downloads can also be manually triggered: @@ -16,12 +16,12 @@ Patch snapshot downloads can also be manually triggered: livepatch-admin sync trigger --wait ``` -We recommend triggering a patch snapshot download once the server is successfully set up. +It is recommended to trigger a patch snapshot download once the server is successfully set up. -## Verifying that server is up to date +## Verify that the server is up to date -To verify that the server is receiving the latest patches from the livepatch server hosted by Canonical use the following command. +To verify that the server is receiving the latest patches from the Livepatch Server hosted by Canonical, use the following command. ``` livepatch-admin sync reports -``` +``` \ No newline at end of file diff --git a/docs/server/how-to-guides/patch-management/index.md b/docs/server/how-to-guides/patch-management/index.md index 5b6937c..27b80b7 100644 --- a/docs/server/how-to-guides/patch-management/index.md +++ b/docs/server/how-to-guides/patch-management/index.md @@ -14,7 +14,7 @@ Fetch, download, proxy, and chain patches across servers. ## In this section - [Fetch patches](/server/how-to-guides/patch-management/fetch-patches.md) -- [Use the Patch Downloader Tool](/server/how-to-guides/patch-management/use-the-patch-downloader-tool.md) +- [Use the patch downloader tool](/server/how-to-guides/patch-management/use-the-patch-downloader-tool.md) - [Configure proxy for fetching patches](/server/how-to-guides/patch-management/configure-proxy-for-fetching-patches.md) - [Chain Livepatch Servers](/server/how-to-guides/patch-management/chain-livepatch-servers.md) @@ -26,5 +26,5 @@ Fetch, download, proxy, and chain patches across servers. Fetch patches Use the patch downloader tool Configure proxy for fetching patches -Chain livepatch servers -``` +Chain Livepatch Servers +``` \ No newline at end of file diff --git a/docs/server/how-to-guides/patch-management/use-the-patch-downloader-tool.md b/docs/server/how-to-guides/patch-management/use-the-patch-downloader-tool.md index 5d9ca44..526cb36 100644 --- a/docs/server/how-to-guides/patch-management/use-the-patch-downloader-tool.md +++ b/docs/server/how-to-guides/patch-management/use-the-patch-downloader-tool.md @@ -6,35 +6,33 @@ myst: (server-how-to-guides-how-to-use-the-canonical-livepatch-downloader)= -# How to use the Canonical Livepatch Downloader +# Use the Canonical Livepatch Downloader -The Canonical Livepatch downloader tool is a CLI application that provides basic commands to query and download patch files. +The Canonical Livepatch Downloader tool is a CLI application that provides basic commands to query and download patch files. -Please note that this tool is not a replacement for the [Canonical Livepatch client](https://snapcraft.io/canonical-livepatch). Instead it provides some basic patch download and query functionality which may be particularly desirable in the following scenarios: +Note that this tool is not a replacement for the [Canonical Livepatch Client](https://snapcraft.io/canonical-livepatch). Instead it provides some basic patch download and query functionality which may be particularly desirable in the following scenarios: -- If the Livepatch client cannot be used and patches must be inserted manually. -- To downloaded patches before transferring them into an airgapped on-premise deployment of the Livepatch Server. -- To download patch tarballs before moving them to the configured patch storage, in case a patch sync with the hosted Livepatch server cannot be performed. +- If the Livepatch Client cannot be used and patches must be inserted manually. +- To download patches before transferring them into an airgapped on-premises deployment of the Livepatch Server. +- To download patch tarballs before moving them to the configured patch storage, in case a patch sync with the hosted Livepatch Server cannot be performed. -## Using the Canonical Livepatch Downloader +## Set up the Downloader -### Setup the Downloader - -Install the snap with +Install the snap with: ``` sudo snap install canonical-livepatch-downloader ``` -Enable the tool by running the following command with an Ubuntu Pro token obtained from the [Ubuntu Pro dashboard](https://ubuntu.com/pro/dashboard), note that the token must be entitled to Livepatch and belong to the `stable` tier. +Enable the tool by running the following command with an Ubuntu Pro token obtained from the [Ubuntu Pro dashboard](https://ubuntu.com/pro/dashboard). Note that the token must be entitled to Livepatch and belong to the `stable` tier. ``` canonical-livepatch-downloader enable ``` -### Downloading single patches +## Download single patches -For this section we will list and download patches for a specific kernel release. Using the host system's kernel and assuming an `amd64` architecture. +For this section, list and download patches for a specific kernel release, using the host system's kernel and assuming an `amd64` architecture. ``` KERNEL_VERSION=$(cat /proc/version_signature | cut -d ' ' -f 2) @@ -55,13 +53,13 @@ canonical-livepatch-downloader list --kernel=5.15.0-107.117-generic --architectu hash: a603d9c7448d874625a95a2c06cbf554d3184868e803fb98b310a5722e9f359b ``` -Next we will download the latest patch for your kernel. +Next, download the latest patch for the kernel. ``` canonical-livepatch-downloader get-latest --kernel=$KERNEL_VERSION --architecture=amd64 ``` -An example output is provided below +An example output is provided below: ``` canonical-livepatch-downloader get-latest --kernel=5.15.0-107.117-generic --architecture=amd64 @@ -69,30 +67,30 @@ Downloading patch 1/1 Patch livepatch-5.15.0-107.117-generic-107.1-amd64 downloaded and extracted to /home/demo/snap/canonical-livepatch-downloader/common/patches/livepatch-5.15.0-107.117-generic-107.1-amd64 ``` -Note that the path the patch was downloaded to is shown. Unfortunately the downloaded file path cannot currently be changed due to [snap confinement](https://snapcraft.io/docs/snap-confinement). +Note that the path the patch was downloaded to is shown. The downloaded file path cannot currently be changed due to [snap confinement](https://snapcraft.io/docs/snap-confinement). -If a specific patch from the list is desired instead of the latest, use the `get-files` command as follows. +If a specific patch from the list is desired instead of the latest, use the `get-files` command as follows: ``` canonical-livepatch-downloader get-files livepatch-5.15.0-107.117-generic-105.1-amd64.tar.bz2 ``` -### Syncing groups of patches +## Sync groups of patches -Syncing a group of patches is useful when you want to manually transfer patches from into an airgapped environment. +Syncing a group of patches is useful when patches need to be manually transferred into an airgapped environment. -To sync a group of patches we will utilise the `list` and `get-files` commands. Note that, again, because of snap confinement we must place the output of the `list` command in a location that the snap can access. +To sync a group of patches, use the `list` and `get-files` commands. Note that, again, because of snap confinement, place the output of the `list` command in a location that the snap can access. -The list command provides filtering based on the following parameters: +The `list` command provides filtering based on the following parameters: -- Architecture: Specify a fixed architecture string, e.g. "amd64" or "s390x" -- Flavour: Specify a kernel flavour, e.g. "generic", "lowlatency", etc. -- Kernel: A prefix match on kernel versions. E.g. 6.2 will match kernel versions 6.2.\* -- Tier: Specify the tier from which to download patches, defaults to "Proposed". See [here](/client/explanation/architecture/what-are-livepatch-tiers.md) for more info on tiers. +- Architecture: Specify a fixed architecture string, for example, "amd64" or "s390x" +- Flavour: Specify a kernel flavour, for example, "generic", "lowlatency", etc. +- Kernel: A prefix match on kernel versions. For example, 6.2 will match kernel versions 6.2.\* +- Tier: Specify the tier from which to download patches, defaults to "Proposed". See the [tiers documentation](/client/explanation/architecture/what-are-livepatch-tiers.md) for more information on tiers. The same flag cannot be passed multiple times. If multiple kernel versions, flavours or architectures are desired, run the following commands with each combination. -Assuming that we want to sync all patches for architecture `amd64`, kernel `4.4.0-1100` and flavour `aws`: +Assuming that all patches need to be synced for architecture `amd64`, kernel `4.4.0-1100` and flavour `aws`: ``` canonical-livepatch-downloader list --architecture=amd64 --flavour=aws --kernel=4.4.0-1100 > ~/snap/canonical-livepatch-downloader/common/patch-list.txt @@ -106,13 +104,13 @@ The output will indicate the download progress and specify the final download lo Patches downloaded and extracted to /home/demo/snap/canonical-livepatch-downloader/common/patches ``` -### Saving the downloaded patch tarballs +## Save the downloaded patch tarballs -The default behavior of the patch-downloader is to download the patch tarball served by the hosted Livepatch server to a temporary location, perform file checksum checks, extract the patch files from the tarball and then delete the downloaded patch tarball from the temporary location. +The default behavior of the patch downloader is to download the patch tarball served by the hosted Livepatch Server to a temporary location, perform file checksum checks, extract the patch files from the tarball and then delete the downloaded patch tarball from the temporary location. -This behaviour can be overridden to save the downloaded patch tarballs in a permanent location for further use, by using the `-K` or `--keep-tarball` option with the `get-latest` or `get-files` commands. A potential use-case for doing this could be to move the patch tarballs to the configured on-prem patch storage, when a patch sync with the hosted Livepatch server cannot be performed. +This behaviour can be overridden to save the downloaded patch tarballs in a permanent location for further use, by using the `-K` or `--keep-tarball` option with the `get-latest` or `get-files` commands. A potential use-case for doing this could be to move the patch tarballs to the configured on-premises patch storage, when a patch sync with the hosted Livepatch Server cannot be performed. -For example, if we want to store the downloaded patch tarballs and the extracted patch files for the architecture `amd64`, kernel `5.15.0-25` and flavour `generic`: +For example, to store the downloaded patch tarballs and the extracted patch files for the architecture `amd64`, kernel `5.15.0-25` and flavour `generic`: ``` canonical-livepatch-downloader list --kernel 5.15.0-25 --architecture amd64 --flavour generic > ~/snap/canonical-livepatch-downloader/common/patch-list.txt @@ -127,9 +125,9 @@ Patches downloaded and extracted to /home/prinson/snap/canonical-livepatch-downl Patch tarballs saved to /home/prinson/snap/canonical-livepatch-downloader/common/tarballs ``` -### Removing downloaded patches +## Remove downloaded patches -Because patches are downloaded to `~/canonical-livepatch-downloader/common/patches` to remove all downloads simply run +Because patches are downloaded to `~/canonical-livepatch-downloader/common/patches`, to remove all downloads run: ``` rm -r ~/snap/canonical-livepatch-downloader/common/patches/* @@ -141,10 +139,10 @@ To also remove any saved patch tarballs, run: rm -r ~/snap/canonical-livepatch-downloader/common/tarballs ``` -### Removing the Downloader +## Remove the Downloader -When removing the tool, Snap [snapshots](https://snapcraft.io/docs/snapshots) may result in the removal taking a long time because a backup of the downloaded patches are being made. To avoid this, uninstall the tool with the following command to skip the creation of a snapshot. +When removing the tool, Snap [snapshots](https://snapcraft.io/docs/snapshots) may result in the removal taking a long time because a backup of the downloaded patches is being made. To avoid this, uninstall the tool with the following command to skip the creation of a snapshot. ``` sudo snap remove canonical-livepatch-downloader --purge -``` +``` \ No newline at end of file diff --git a/docs/server/how-to-guides/security/harden-your-deployment.md b/docs/server/how-to-guides/security/harden-your-deployment.md index cb792bb..29cdd88 100644 --- a/docs/server/how-to-guides/security/harden-your-deployment.md +++ b/docs/server/how-to-guides/security/harden-your-deployment.md @@ -7,9 +7,9 @@ myst: (server-how-to-guides-harden-your-livepatch-server-deployment)= -# Harden your Livepatch server deployment +# Harden a Livepatch Server deployment -The Livepatch Server is available as a Kubernetes charm and a strict-confinement snap for on-premises deployment. This document provides guidance on securing the server in production deployments. +The Livepatch Server is available as a Kubernetes charm and a strict-confinement snap for on-premises deployment. The following sections provide guidance on securing the server in production deployments. ## Enable TLS termination @@ -17,8 +17,8 @@ The Livepatch Server does not natively terminate TLS. In on-premises deployments For **charm deployments**, TLS termination is configured through an ingress integration. The charm supports two ingress interfaces: -- **`nginx-route`** (legacy): Integration with the [Nginx Ingress Integrator charm](https://charmhub.io/nginx-ingress-integrator). Set `ingress-interface=legacy-nginx-route` (default). -- **`ingress`** (modern): Integration with the [Traefik K8s charm](https://charmhub.io/traefik-k8s) or [Gateway API Integrator charm](https://charmhub.io/gateway-api-integrator). Set `ingress-interface=ingress`. +* **`nginx-route`** (legacy): Integration with the [Nginx Ingress Integrator charm](https://charmhub.io/nginx-ingress-integrator). Set `ingress-interface=legacy-nginx-route` (default). +* **`ingress`** (modern): Integration with the [Traefik K8s charm](https://charmhub.io/traefik-k8s) or [Gateway API Integrator charm](https://charmhub.io/gateway-api-integrator). Set `ingress-interface=ingress`. Example using the modern ingress integration: @@ -29,25 +29,25 @@ juju integrate canonical-livepatch-server-k8s traefik-k8s For **snap deployments**, a reverse proxy (for example, Nginx or HAProxy) can be configured with TLS certificates to terminate HTTPS before forwarding traffic to the server. -Without TLS termination, all communication — including authentication credentials — is transmitted in plaintext. This is acceptable on a fully trusted internal network, but not recommended when any network segment is untrusted. +Without TLS termination, all communication -- including authentication credentials -- is transmitted in plaintext. This is acceptable on a fully trusted internal network, but not recommended when any network segment is untrusted. For step-by-step TLS setup instructions, see the [TLS configuration guide](/server/how-to-guides/security/setup-tls.md). ### Federation (chained servers) -In [federated deployments](/server/how-to-guides/patch-management/chain-livepatch-servers.md) where multiple on-premises servers are chained, TLS should also be enabled between them to protect the exchange of tier and patch data. Configure TLS termination on the upstream server just as you would for client-facing traffic. +In [federated deployments](/server/how-to-guides/patch-management/chain-livepatch-servers.md) where multiple on-premises servers are chained, TLS should also be enabled between them to protect the exchange of tier and patch data. Configure TLS termination on the upstream server just as for client-facing traffic. ## Encrypt database connections TLS for PostgreSQL connections is supported through the connection string. Include `sslmode=verify-full` (or at minimum `sslmode=require`) in the database connection string to encrypt traffic between the server and PostgreSQL. -For charm deployments, database credentials are obtained through Juju relations (`database` interface with the [PostgreSQL K8s Charm](https://charmhub.io/postgresql-k8s)). TLS for the database connection is managed by the PostgreSQL charm's [TLS integration](https://canonical-charmed-postgresql-k8s.readthedocs-hosted.com/14/tutorial/index.html#enable-encryption-with-tls). The Livepatch charm does not expose separate database credential configuration — all credentials are exchanged through the Juju relation protocol. +For charm deployments, database credentials are obtained through Juju relations (`database` interface with the [PostgreSQL K8s Charm](https://charmhub.io/postgresql-k8s)). TLS for the database connection is managed by the PostgreSQL charm's [TLS integration](https://canonical-charmed-postgresql-k8s.readthedocs-hosted.com/14/tutorial/index.html#enable-encryption-with-tls). The Livepatch charm does not expose separate database credential configuration -- all credentials are exchanged through the Juju relation protocol. ## Encrypt patch storage connections -- **S3**: Set `patch-storage.s3-secure` to `true` to enforce HTTPS for all S3 communication. -- **Swift**: Configure `patch-storage.swift-auth-url` to use an HTTPS endpoint. -- **Filesystem/PostgreSQL**: No additional configuration needed as storage is local to the server or database. +* **S3**: Set `patch-storage.s3-secure` to `true` to enforce HTTPS for all S3 communication. +* **Swift**: Configure `patch-storage.swift-auth-url` to use an HTTPS endpoint. +* **Filesystem/PostgreSQL**: No additional configuration needed as storage is local to the server or database. ## Configure a custom CA certificate for the contracts service @@ -119,8 +119,8 @@ For snap deployments, ensure that the configuration file (typically at `$SNAP_CO The HTTP governor protects the server from overload. Configure appropriate limits for the deployment: -- `server.concurrency-limit` (default: 1000): Maximum number of requests processed simultaneously. -- `server.burst-limit` (default: 500): Maximum number of concurrently incoming requests. Requests exceeding this are queued up to `concurrency-limit - burst-limit` (default: 500), and rejected beyond that. +* `server.concurrency-limit` (default: 1000): Maximum number of requests processed simultaneously. +* `server.burst-limit` (default: 500): Maximum number of concurrently incoming requests. Requests exceeding this are queued up to `concurrency-limit - burst-limit` (default: 500), and rejected beyond that. For charm deployments: @@ -135,15 +135,15 @@ These values should be tuned based on the expected load and available resources. In production deployments: -- Admin API endpoints should only be accessible from trusted networks. -- The `/metrics` endpoint (Prometheus) should be restricted to monitoring infrastructure. -- Database ports should not be exposed to the public network. +* Admin API endpoints should only be accessible from trusted networks. +* The `/metrics` endpoint (Prometheus) should be restricted to monitoring infrastructure. +* Database ports should not be exposed to the public network. ## Maintain strict privileged access ### Snap -The snap uses `strict` confinement, restricting the server to only the `network` and \`network-bind\` interfaces. +The snap uses `strict` confinement, restricting the server to only the `network` and `network-bind` interfaces. All server data is stored under the `$SNAP_COMMON` and `$SNAP_DATA` directories. Maintain strict privileged access controls on the host machine to prevent unauthorized access to this data. @@ -155,8 +155,8 @@ When a Livepatch Client is registered with the on-premises server, an authentica The charm deploys the server as a container. The server listens on port 8080 internally. Apply Kubernetes security best practices: -- Use `NetworkPolicy` resources to restrict pod-to-pod communication. -- Use Kubernetes RBAC to limit access to the server's namespace and secrets. +* Use `NetworkPolicy` resources to restrict pod-to-pod communication. +* Use Kubernetes RBAC to limit access to the server's namespace and secrets. The charm stores its internal state (including the database connection string) in the Juju peer relation data. Access to the Juju controller and model should be restricted to authorized operators. @@ -170,7 +170,7 @@ To reset the snap configuration to its default state: sudo snap set canonical-livepatch-server key= ``` -Alternatively, remove and reinstall the snap (see [decommissioning](/server/how-to-guides/operations/decommission.md)). +Alternatively, remove and reinstall the snap. See [Decommission](/server/how-to-guides/operations/decommission.md) for details. ### Charm @@ -180,4 +180,4 @@ To reset the charm to its default configuration: juju config canonical-livepatch-server-k8s --reset ``` -To fully reset, remove the application and redeploy. +To fully reset, remove the application and redeploy. \ No newline at end of file diff --git a/docs/server/how-to-guides/security/index.md b/docs/server/how-to-guides/security/index.md index 942e550..80fa4ac 100644 --- a/docs/server/how-to-guides/security/index.md +++ b/docs/server/how-to-guides/security/index.md @@ -13,10 +13,10 @@ Secure the server with TLS, hardening, admin tooling, and vulnerability reportin ## In this section -- [Setup TLS](/server/how-to-guides/security/setup-tls.md) -- [Harden your deployment](/server/how-to-guides/security/harden-your-deployment.md) -- [Setup administration tool](/server/how-to-guides/security/setup-administration-tool.md) -- [Report server vulnerabilities](/server/how-to-guides/security/report-server-vulnerabilities.md) +* [Set up TLS](/server/how-to-guides/security/setup-tls.md) +* [Harden the deployment](/server/how-to-guides/security/harden-your-deployment.md) +* [Set up the administration tool](/server/how-to-guides/security/setup-administration-tool.md) +* [Report server vulnerabilities](/server/how-to-guides/security/report-server-vulnerabilities.md) ```{toctree} :titlesonly: @@ -27,4 +27,4 @@ Setup tls Harden your deployment Setup administration tool Report server vulnerabilities -``` +``` \ No newline at end of file diff --git a/docs/server/how-to-guides/security/report-server-vulnerabilities.md b/docs/server/how-to-guides/security/report-server-vulnerabilities.md index 4d2193f..6d8a776 100644 --- a/docs/server/how-to-guides/security/report-server-vulnerabilities.md +++ b/docs/server/how-to-guides/security/report-server-vulnerabilities.md @@ -9,8 +9,8 @@ myst: # Report a Livepatch Server vulnerability -To report a security issue, file a [Private/Embargoed Security Bug](https://bugs.launchpad.net/livepatch-onprem/+filebug) on Launchpad with a description of the issue, the steps you took to reproduce the issue, affected versions, and, if known, mitigations for the issue. See [this](https://blog.launchpad.net/general/reimagining-the-nature-of-privacy-in-launchpad-part-1) for more information on how to file a private security bug on Launchpad. +To report a security issue, file a [Private/Embargoed Security Bug](https://bugs.launchpad.net/livepatch-onprem/+filebug) on Launchpad with a description of the issue, the steps taken to reproduce the issue, affected versions, and, if known, mitigations for the issue. See the [Launchpad blog](https://blog.launchpad.net/general/reimagining-the-nature-of-privacy-in-launchpad-part-1) for more information on filing a private security bug. -The Livepatch team will be notified of the issue and will work with you to determine whether the issue qualifies as a security issue. We will then handle figuring out a fix, getting a CVE assigned and coordinating the release of the fix. +The Livepatch team is notified of the issue and works to determine whether the issue qualifies as a security issue. The team then handles identifying a fix, getting a CVE assigned, and coordinating the release of the fix. -The [Ubuntu Security disclosure and embargo policy](https://ubuntu.com/security/disclosure-policy) contains more information about what you can expect when you contact us, and what we expect from you. +The [Ubuntu Security disclosure and embargo policy](https://ubuntu.com/security/disclosure-policy) contains more information about what to expect when contacting the team, and what is expected in return. \ No newline at end of file diff --git a/docs/server/how-to-guides/security/setup-administration-tool.md b/docs/server/how-to-guides/security/setup-administration-tool.md index 236888d..1b10edc 100644 --- a/docs/server/how-to-guides/security/setup-administration-tool.md +++ b/docs/server/how-to-guides/security/setup-administration-tool.md @@ -6,15 +6,15 @@ myst: (server-how-to-guides-how-to-setup-livepatch-on-prem-server-administration-tool)= -# How to setup Livepatch on-prem server administration tool +# Set up the Livepatch on-premises server administration tool -To perform operations such as promoting patches to tiers and issuing tokens for machines to attach to the livepatch server, an administration tool is provided as a snap: +To perform operations such as promoting patches to tiers and issuing tokens for machines to attach to the Livepatch Server, an administration tool is provided as a snap: ``` sudo snap install canonical-livepatch-server-admin ``` -For ease of use, it's recommended to alias the admin command: +For ease of use, alias the admin command: ``` sudo snap alias canonical-livepatch-server-admin.livepatch-admin livepatch-admin @@ -22,19 +22,19 @@ sudo snap alias canonical-livepatch-server-admin.livepatch-admin livepatch-admin ## Authentication -There are two ways for the livepatch administration tool to authenticate with the livepatch server: +The Livepatch administration tool can authenticate with the Livepatch Server in two ways: -- Ubuntu SSO -- Username/password +* Ubuntu SSO +* Username and password (server-how-to-guides-password-authentication)= ## Password authentication -To configure password authentication, username/password hash pairs will need to be generated using the `htpasswd` tool available in the `apache2-utils` package. +To configure password authentication, username and password hash pairs must be generated using the `htpasswd` tool available in the `apache2-utils` package. ````{note} -The `apache2-utils` package can be installed by using the following commands: +The `apache2-utils` package can be installed using the following commands: ``` sudo apt-get update @@ -42,20 +42,20 @@ sudo apt-get install apache2-utils ``` ```` -This will generate a username/password hash pair: +Generate a username and password hash pair: ``` htpasswd -bnBC 10 username:$2y$10$74ZpDgHaxnUQo.AJZk1cMuSRfef5oK5xq5o/GLbUH/Bbw6W2bmctm ``` -Multiple such pairs can be provided as a comma-separated list: +Multiple pairs can be provided as a comma-separated list: ``` juju config livepatch auth_basic_users="::" ``` -When logging in with the client, the username and password will need to be provided: +When logging in with the client, provide the username and password: ``` export LIVEPATCH_URL={haproxy URL or unit IP} @@ -65,7 +65,7 @@ livepatch-admin login --auth : ## Ubuntu SSO authentication -Ubuntu SSO authentication utilizes membership in public launchpad groups to gate access. The launchpad groups that will have administrator privileges are specified using charmed operator configuration: +Ubuntu SSO authentication uses membership in public Launchpad groups to gate access. The Launchpad groups that have administrator privileges are specified using charmed operator configuration: ``` juju config livepatch auth_lp_teams='https://launchpad.net/~' @@ -73,7 +73,7 @@ juju config livepatch auth_lp_teams='https://launchpad.net/~' Multiple teams can be specified as a comma-separated list. -When logging in, user interaction will be necessary: +When logging in, user interaction is required: ``` export LIVEPATCH_URL={haproxy URL} @@ -81,4 +81,4 @@ export LIVEPATCH_URL={haproxy URL} livepatch-admin login To login please visit http://127.0.0.1:44035 -``` +``` \ No newline at end of file diff --git a/docs/server/how-to-guides/security/setup-tls.md b/docs/server/how-to-guides/security/setup-tls.md index f25f00f..00f9a44 100644 --- a/docs/server/how-to-guides/security/setup-tls.md +++ b/docs/server/how-to-guides/security/setup-tls.md @@ -6,17 +6,17 @@ myst: (server-how-to-guides-how-to-setup-tls-for-livepatch-on-prem)= -# How to setup TLS for Livepatch on-prem +# Set up TLS for Livepatch on-premises -The security of livepatching depends not only on the signed kernel modules but also on the secure TLS channel between the livepatch client and the on-prem server. It is thus paramount to setup the necessary TLS keys and certificates for the on-prem service to provide the necessary security. +The security of live kernel patching depends not only on the signed kernel modules but also on the secure TLS channel between the Livepatch Client and the on-premises server. Setting up the necessary TLS keys and certificates for the on-premises service is therefore essential. -There are several ways to set up TLS for livepatch on-prem. One way is to use a dedicated TLS terminating reverse proxy in front of the haproxy service. Another way is to configure the appropriate TLS certificate and key on the haproxy instance directly. +There are several ways to set up TLS for Livepatch on-premises. One approach is to use a dedicated TLS-terminating reverse proxy in front of the haproxy service. Another approach is to configure the appropriate TLS certificate and key on the haproxy instance directly. -## Configuring TLS for haproxy +## Configure TLS for haproxy -These are the steps to configure TLS on the haproxy service directly: +The following steps configure TLS on the haproxy service directly: -1.Create a `tls-overlay.yaml` file with the following content: +1. Create a `tls-overlay.yaml` file with the following content: ``` applications: @@ -38,26 +38,27 @@ applications: ``` 2. Rename the certificate and key files to `cert.pem` and `key.pem` and place them in the same directory as the downloaded overlay file. -3. Run the following juju command +3. Run the following Juju command: ``` juju deploy ch:canonical-livepatch-onprem --overlay ./tls-overlay.yaml ``` -4. Run `juju status` to verify that the haproxy service is now exposing port 443 +4. Run `juju status` to verify that the haproxy service is now exposing port 443. + ![screenshot_20210603_165758|690x55](/_static/images/nuS5aGmo44qwv5vagLczO0tnfog.png) (server-how-to-guides-configuring-livepatch-admin-tool-with-tls)= -## Configuring livepatch admin tool with TLS +## Configure the Livepatch admin tool with TLS -If the TLS certificate used for livepatch originates from a trusted CA, there should be no further configuration necessary - the livepatch admin tool will use the configured system certificates to verify the server's responses. +If the TLS certificate used for Livepatch originates from a trusted CA, no further configuration is required. The Livepatch admin tool uses the configured system certificates to verify the server's responses. -If, however, a self-signed certificate is used, the administration tool will need to be configured to use the certificate. There are several ways to do that. +If a self-signed certificate is used, the administration tool must be configured to use the certificate. There are several ways to do this. ### Command line option -The command line option for the livepatch admin tool accepts either the path to a certificate chain PEM file, or the contents of the certificate chain: +The command line option for the Livepatch admin tool accepts either the path to a certificate chain PEM file, or the contents of the certificate chain: ``` livepatch-admin --ca ./cert.pem login -a (...) @@ -79,12 +80,14 @@ export LIVEPATCH_CA_CRT='/temp/cert.pem' export LIVEPATCH_CA_CRT="$(cat ./cert.pem)" ``` -## Configuring livepatch client with TLS +(configuring-livepatch-client-with-tls)= + +## Configure the Livepatch Client with TLS -If a self-signed certificate is used for the livepatch on-prem service, livepatch client instances will also need to be configured with that certificate to be able to verify responses coming from the on-prem server: +If a self-signed certificate is used for the Livepatch on-premises service, Livepatch Client instances must also be configured with that certificate to verify responses from the on-premises server: ``` sudo canonical-livepatch config ca-certs=@stdin < ./cert.pem ``` -For more information on how to configure an HTTPS proxy on the Livepatch Client, please check out [this](/client/how-to-guides/configuration/configure-proxy.md) guide. +For more information on configuring an HTTPS proxy on the Livepatch Client, see the [proxy configuration guide](/client/how-to-guides/configuration/configure-proxy.md). \ No newline at end of file diff --git a/docs/server/index.md b/docs/server/index.md index 8ec18bc..492af19 100644 --- a/docs/server/index.md +++ b/docs/server/index.md @@ -1,32 +1,29 @@ --- myst: html_meta: - description: "Livepatch on-premises server documentation home." + description: "Reference and how-to documentation for the Livepatch on-premises server, including deployment, configuration, authentication, patch management, and telemetry." --- - (server)= # Server -Livepatch on-prem is an on-premises deployment of the Livepatch server. - -Its purpose is to pull in patch updates from Canonical and allow more fine-grained control of patch rollout to the machines running on your infrastructure. +Livepatch on-prem is an on-premises deployment of the Livepatch Server. It pulls live kernel patch updates from Canonical and allows fine-grained control over patch rollout to the machines in your infrastructure. ## In this documentation -| | | -|-|-| -| [Tutorials](/server/tutorial/index.md)
Get started with a hands-on introduction for new users deploying Livepatch. | [How-to guides](/server/how-to-guides/index.md)
Step-by-step guides covering key operations and common tasks
| -| [Explanation](/server/explanation/index.md)
Discussion and clarification of key topics | [Reference](/server/reference/index.md)
Technical information - specifications, APIs, architecture | +| | | +| --- | --- | +| [Tutorial](/server/tutorial/index.md)
Get started with a hands-on introduction to deploying Livepatch. | [How-to guides](/server/how-to-guides/index.md)
Step-by-step guides covering key operations and common tasks. | +| [Reference](/server/reference/index.md)
Technical reference for the Livepatch Server, including platform requirements, authentication, and patch management. | [Explanation](/server/explanation/index.md)
Discussion and clarification of key Livepatch Server topics. | ## Getting support -Canonical customers can receive support and report issues on the Ubuntu Livepatch service, Livepatch client or Livepatch on-prem, on Canonical's [support portal](https://portal.support.canonical.com/). +Canonical customers can receive support and report issues with the Ubuntu Livepatch service, the Livepatch Client, or Livepatch on-prem through the [Canonical support portal](https://portal.support.canonical.com/). -The projects maintain bug trackers at +The projects maintain bug trackers at: -- [Livepatch client bug tracker](https://bugs.launchpad.net/canonical-livepatch-client/+filebug) +- [Livepatch Client bug tracker](https://bugs.launchpad.net/canonical-livepatch-client/+filebug) - [Livepatch on-prem bug tracker](https://bugs.launchpad.net/livepatch-onprem/+filebug) ```{toctree} @@ -39,4 +36,4 @@ Tutorial How-to guides Reference Explanation -``` +``` \ No newline at end of file diff --git a/docs/server/reference/authentication/authentication.md b/docs/server/reference/authentication/authentication.md index c31b724..6679ee0 100644 --- a/docs/server/reference/authentication/authentication.md +++ b/docs/server/reference/authentication/authentication.md @@ -1,23 +1,22 @@ --- myst: html_meta: - description: "Authentication - technical reference for Livepatch on-prem server." + description: "Technical reference for Livepatch on-premises server authentication, covering Basic Auth, macaroons, client tokens, sync tokens, and cryptographic technologies." --- - (server-reference-livepatch-server-authentication)= -# Livepatch Server Authentication +# Livepatch Server authentication -This document provides a technical reference for all authentication and authorization mechanisms used by the on-premises Livepatch Server. It covers the authentication flows for each API surface and the cryptographic technologies involved. +This document provides a technical reference for the authentication and authorization mechanisms used by the on-premises Livepatch Server. It covers the authentication flows for each API surface and the cryptographic technologies involved. ## Admin APIs -These APIs are consumed by administrators through the Livepatch Admin Tool. +Admin APIs are consumed by administrators through the Livepatch Admin Tool. -The following authentication flows are supported: +The following authentication flow is supported: -- **Basic Auth → Macaroon**: Login using [Basic Auth](#server-reference-basic-auth) to obtain a [macaroon](#server-reference-macaroons), then use the macaroon to authenticate subsequent requests. Macaroons expire after 240 hours. +- **Basic Auth → Macaroon**: Authenticate using [Basic Auth](#server-reference-basic-auth) to obtain a [macaroon](#server-reference-macaroons). Use the macaroon to authenticate subsequent requests. Macaroons expire after 240 hours. All admin activity is logged as a structured security event with the `authz_admin` event code. @@ -25,19 +24,22 @@ All admin activity is logged as a structured security event with the `authz_admi ## Client APIs -These APIs are consumed by Livepatch Client instances. +Client APIs are consumed by Livepatch Client instances. -- **Auth Token**: A UUIDv4 token used to authenticate and register a machine. After successful registration, a machine token is issued for subsequent requests. This is a legacy token format that is no longer used for new clients. +- **Auth Token**: A UUIDv4 token used to authenticate and register a machine. After successful registration, a machine token is issued for subsequent requests. This is a legacy token format no longer used for new clients. - **Resource Token**: A macaroon verified against the Ubuntu Pro backend to authenticate requests. This token is provided to the Livepatch Client by the Ubuntu Pro client when enabling Pro. After authentication, client requests are authorized based on tier and affordances (architecture and kernel compatibility). ## Server APIs -These APIs are used for patch synchronization between on-premises servers and their upstream patch source (Canonical's hosted Livepatch service or another on-premises server). +Server APIs are used for patch synchronisation between on-premises servers and their upstream patch source (Canonical's hosted Livepatch service or another on-premises server). -- **Contract Resource Token**: A resource token obtained from the Ubuntu Pro contracts service, used to authenticate the on-premises server with Canonical's hosted Livepatch service. For charm deployments, obtained via the `get-resource-token` Juju action (`juju run canonical-livepatch-server-k8s/ get-resource-token contract-token=`). For snap deployments, obtained implicitly by setting the contract token (`sudo snap set canonical-livepatch-server token=`); the snap's configure hook exchanges it for a resource token and sets `patch-sync.token` automatically. The process exchanges a contract token for a machine token and then retrieves the resource token with appropriate affordances. -- **Sync Token**: A UUIDv4 generated through the Admin APIs of the upstream server (`livepatch-admin sync-tokens add `). Used in both direct (hosted) and federated (on-premises to on-premises) synchronization. Like client tokens, sync tokens specify which tier patches will be retrieved from. Configured via `patch-sync.token`. Stored in PostgreSQL with verification by direct comparison. +- **Contract Resource Token**: A resource token obtained from the Ubuntu Pro contracts service, used to authenticate the on-premises server with Canonical's hosted Livepatch service. + - For charm deployments, obtain the token using the `get-resource-token` Juju action: `juju run canonical-livepatch-server-k8s/ get-resource-token contract-token=`. + - For snap deployments, the token is obtained implicitly by setting the contract token (`sudo snap set canonical-livepatch-server token=`). The snap's configure hook exchanges it for a resource token and sets `patch-sync.token` automatically. + - The process exchanges a contract token for a machine token, then retrieves the resource token with appropriate affordances. +- **Sync Token**: A UUIDv4 token generated through the Admin APIs of the upstream server (`livepatch-admin sync-tokens add `). Used in both direct (hosted) and federated (on-premises to on-premises) synchronisation. Sync tokens specify which tier patches are retrieved from. Configured via `patch-sync.token`. Stored in PostgreSQL with verification by direct comparison. ## Technologies @@ -80,4 +82,4 @@ UUIDv4 is a 128-bit identifier generated using random number generation, represe Go packages used: -- [`github.com/google/uuid`](http://github.com/google/uuid) +- [`github.com/google/uuid`](http://github.com/google/uuid) \ No newline at end of file diff --git a/docs/server/reference/authentication/index.md b/docs/server/reference/authentication/index.md index c09d770..5d83389 100644 --- a/docs/server/reference/authentication/index.md +++ b/docs/server/reference/authentication/index.md @@ -1,24 +1,23 @@ --- myst: html_meta: - description: "Authentication reference for the Livepatch Server." + description: "Authentication reference for the Livepatch on-premises server, covering admin, client, and server API authentication mechanisms including Basic Auth, macaroons, and UUID tokens." --- - (server-reference-authentication)= # Authentication -Authentication reference for the Livepatch Server. +Authentication and authorization mechanisms for the Livepatch on-premises server. ## In this section -- [Authentication](/server/reference/authentication/authentication.md) +- [Livepatch Server authentication](/server/reference/authentication/authentication.md) — Authentication flows for admin, client, and server APIs, and the cryptographic technologies used. ```{toctree} :titlesonly: :maxdepth: 1 :hidden: -Authentication -``` +Livepatch Server authentication +``` \ No newline at end of file diff --git a/docs/server/reference/index.md b/docs/server/reference/index.md index 120f578..aa26876 100644 --- a/docs/server/reference/index.md +++ b/docs/server/reference/index.md @@ -1,23 +1,22 @@ --- myst: html_meta: - description: "Reference - technical reference for Livepatch on-prem server." + description: "Technical reference for the Livepatch on-premises server, covering platform configuration, authentication, patch management, patch storage, telemetry, and release notes." --- - (server-reference)= # Reference -Technical information - specifications, APIs, architecture, etc., related to Livepatch on-prem server. +This section provides technical reference information for the Livepatch on-premises server. ## In this section -- [Platform](/server/reference/platform/index.md) — Configuration, resource requirements, and network access. -- [Authentication](/server/reference/authentication/index.md) — Authentication reference for the Livepatch Server. -- [Patch management](/server/reference/patch-management/index.md) — Patch management settings and patch sync filters. -- [Patch storage](/server/reference/patch-storage/index.md) — Configure patch storage backends such as S3 for the Livepatch Server. -- [Telemetry](/server/reference/telemetry/index.md) — Data sent to Canonical and machine reports. +- [Platform](/server/reference/platform/index.md) — Configuration options, resource requirements, and network access rules. +- [Authentication](/server/reference/authentication/index.md) — Authentication and authorization mechanisms for the Livepatch Server APIs. +- [Patch management](/server/reference/patch-management/index.md) — Managing patch tiers, promotion workflows, and sync filter options. +- [Patch storage](/server/reference/patch-storage/index.md) — Configuring patch storage backends such as S3 for the Livepatch Server. +- [Telemetry](/server/reference/telemetry/index.md) — Data sent to Canonical during patch synchronisation and machine reporting. - [Releases](/release-notes/server/index.md) — Release notes for the Livepatch Server. ```{toctree} @@ -31,4 +30,4 @@ Patch management Patch storage Telemetry Releases <../../release-notes/server/index.md> -``` +``` \ No newline at end of file diff --git a/docs/server/reference/patch-management/index.md b/docs/server/reference/patch-management/index.md index c5e6377..22cd121 100644 --- a/docs/server/reference/patch-management/index.md +++ b/docs/server/reference/patch-management/index.md @@ -1,26 +1,25 @@ --- myst: html_meta: - description: "Patch management settings and patch sync filters." + description: "Reference for Livepatch on-premises patch management, including tier-based patch rollout, promotion workflows, and sync filter configuration." --- - (server-reference-patch-management)= # Patch management -Patch management settings and patch sync filters. +Management of patch tiers, promotion workflows, and synchronisation filters for the on-premises Livepatch Server. ## In this section -- [Patch management](/server/reference/patch-management/patch-management.md) -- [Patch sync filters](/server/reference/patch-management/patch-sync-filters.md) +- [Managing patches in an on-prem Livepatch deployment](/server/reference/patch-management/patch-management.md) — How patch tiers work and how to promote patches between tiers. +- [Patch sync filters](/server/reference/patch-management/patch-sync-filters.md) — Configurable filters to limit which patches are synchronised from the upstream server. ```{toctree} :titlesonly: :maxdepth: 1 :hidden: -Patch management +Managing patches in an on-prem Livepatch deployment Patch sync filters -``` +``` \ No newline at end of file diff --git a/docs/server/reference/patch-management/patch-management.md b/docs/server/reference/patch-management/patch-management.md index 783634b..2cb7e86 100644 --- a/docs/server/reference/patch-management/patch-management.md +++ b/docs/server/reference/patch-management/patch-management.md @@ -1,25 +1,26 @@ --- myst: html_meta: - description: "Patch management - technical reference for Livepatch on-prem server." + description: "Technical reference for managing patches in an on-premises Livepatch deployment, covering tier-based patch rollout and promotion using livepatch-admin." --- - (server-reference-managing-patches-in-an-on-prem-livepatch-deployment)= -# Managing patches in an on-prem livepatch deployment +# Managing patches in an on-prem Livepatch deployment + +Livepatch patches are managed using tiers — ordered groups that patches are placed into. Each Livepatch Client instance is associated with a specific tier through its token. After deployment, the server includes a default tier list: `edge`, `beta`, `candidate`, and `stable`. This list can be modified using the Livepatch administration tool. -Livepatch patches are managed using tiers. Tiers are basically containers that patches are put into. Each Livepatch client instance is associated with a specific tier (via the token). After deployment the server comes with a default tier list: edge, beta, candidate and stable. This list can be modified using the Livepatch administration tool. +![Patch tier overview](/_static/images/a5BXTUhxJVYx45D4Bb4Av7VtVW3.png) -![image2|624x428](/_static/images/a5BXTUhxJVYx45D4Bb4Av7VtVW3.png) +The tiers form an ordered list. When the on-premises server pulls patches from Canonical's servers, patches are initially assigned to the first tier in the list. The order of tiers in the output of the `livepatch-admin` tool reflects the order of patch promotion. -The tiers form an ordered list. When the on-prem server pulls in patches from Canonical's servers, these patches are initially assigned to the first tier in the list. The order of tiers in the output of the Livepatch admin tool command is in the order of patch promotion. In this example the `edge` tier is the initial tier patches will be assigned to: +To view the current tier order: ``` livepatch-admin tier list ``` -... should produce output like this: +The output resembles: ``` Tiers: @@ -29,34 +30,36 @@ Tiers: - Name: ``` -If no further validation of patches is necessary, all Livepatch client instances can be associated with that tier and the patches will become available to them as soon as they have been downloaded. +If no further validation of patches is required, associate all Livepatch Client instances with the first tier. Patches become available as soon as they have been downloaded. + +![Single-tier deployment](/_static/images/z7xA042h7EvRf7fRFNqLGiGi9Mw.png) -![image4|623x263](/_static/images/z7xA042h7EvRf7fRFNqLGiGi9Mw.png) +If validation or a staggered rollout of patches is required, use the patch tiers to implement this workflow. Associate a small portion of testing machines with the `beta` tier, and promote patches to higher tiers once they have been validated. -If, however, validation or a staggered rollout of patches is required, the patch tiers can be used to implement that. In such a scenario, a small portion of testing machines can be associated with the beta tier and patches can be promoted to higher tiers once they have been validated. +![Multi-tier promotion](/_static/images/hJiubhhVct8K28ljnzbxYhdyjza.png) -![image3|624x526](/_static/images/hJiubhhVct8K28ljnzbxYhdyjza.png) +## Promote a patch to a different tier -To promote a patch to a different tier, use the command: +To promote an individual patch to a different tier: ``` livepatch-admin patch promote ``` -The patch version here is the numerical patch version (e.g. 57.1). +The `patch-version` is the numerical patch version (for example, `57.1`). -## Promoting all patches in a tier +## Promote all patches in a tier -To promote all patches in one tier to another, there is a shortcut command `promote-all`: +To promote all patches from one tier to another, use the `promote-all` shortcut: ``` livepatch-admin patch promote-all ``` -This tool is useful during the initial setup of **Livepatch on-prem**, when all patches are imported into the edge tier and other tiers are empty. By running: +This command is useful during initial setup of Livepatch on-prem, when all patches are imported into the `edge` tier and other tiers are empty. For example: ```text livepatch-admin patch promote-all edge stable ``` -...you can make the contents of all the tiers from edge to stable identical. +This makes the contents of all tiers from `edge` to `stable` identical. \ No newline at end of file diff --git a/docs/server/reference/patch-management/patch-sync-filters.md b/docs/server/reference/patch-management/patch-sync-filters.md index ffdfdd9..860d278 100644 --- a/docs/server/reference/patch-management/patch-sync-filters.md +++ b/docs/server/reference/patch-management/patch-sync-filters.md @@ -1,22 +1,21 @@ --- myst: html_meta: - description: "Patch sync filters - learn about this topic in Livepatch on-prem." + description: "Reference for Livepatch on-premises patch sync filters, covering architecture, flavour, and minimum kernel version filtering to control which patches are synchronised." --- - (server-reference-patch-sync-filters)= -# Patch Sync Filters +# Patch sync filters -Livepatch on-prem enables users to synchronise with the hosted server, and this synchronisation process is configurable. +Livepatch on-prem synchronises patches from an upstream server. This synchronisation process is configurable through filters that limit which patches are downloaded. The primary synchronisation filters are: -- System architecture for limiting patches via architecture. -- Flavours for limiting the kernel flavour. -- Minimum kernel version, only allowing versions greater than the minimum to be synchronized. +- **System architecture** — Limit patches to specific CPU architectures. +- **Flavours** — Limit patches to specific kernel flavours. +- **Minimum kernel version** — Only synchronise patches for kernel versions greater than a specified minimum. -Set sync filters if you want to reduce the amount of space consumed by Livepatch files and/or you know your client machines will be limited to a certain set of kernel variants. +Configure sync filters to reduce the disk space consumed by patch files, or when client machines are limited to a specific set of kernel variants. -A full list of the available sync filters can be found in our [config](/server/reference/platform/configuration.md). +For a complete list of available sync filter options, see the [Livepatch Server configuration reference](/server/reference/platform/configuration.md). \ No newline at end of file diff --git a/docs/server/reference/patch-storage/index.md b/docs/server/reference/patch-storage/index.md index 893db0f..d4779e0 100644 --- a/docs/server/reference/patch-storage/index.md +++ b/docs/server/reference/patch-storage/index.md @@ -9,16 +9,16 @@ myst: # Livepatch on-prem patch storage -Livepatch server supports several different drivers for storing patch files downloaded from livepatch.canonical.com: +Livepatch Server supports several different drivers for storing patch files downloaded from livepatch.canonical.com: 1. Local filesystem 2. Swift 3. S3 (and compatible implementations, e.g. minio) 4. Postgresql -The filesystem patch store is easiest to deploy and suits most configurations. However, if there is a need to scale out the livepatch server such as have multiple livepatch servers running to handle the load, the filesystem patch store should not be used. +The filesystem patch store is easiest to deploy and suits most configurations. However, if there is a need to scale out the Livepatch Server such as have multiple Livepatch Servers running to handle the load, the filesystem patch store should not be used. -In case there is a need to scale out livepatch on-prem, use the s3, postgresql or swift patch stores. Any patch store should have enough space for storing livepatches - currently at least 45GB for all patches, see [this guide](/server/reference/patch-management/patch-sync-filters.md) to filter patches sent to your on-prem instance to specific kernel variants/architectures and lower this requirement. +In case there is a need to scale out Livepatch on-prem, use the s3, postgresql or swift patch stores. Any patch store should have enough space for storing live kernel patches - currently at least 45GB for all patches, see [this guide](/server/reference/patch-management/patch-sync-filters.md) to filter patches sent to your on-prem instance to specific kernel variants/architectures and lower this requirement. See the [patch storage](/server/reference/platform/configuration.md) config for all available parameters. diff --git a/docs/server/reference/patch-storage/use-s3-for-patch-storage.md b/docs/server/reference/patch-storage/use-s3-for-patch-storage.md index fba6501..5f80067 100644 --- a/docs/server/reference/patch-storage/use-s3-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-s3-for-patch-storage.md @@ -9,7 +9,7 @@ myst: # Livepatch on-prem with AWS S3 patch storage -In an AWS EC2 deployment of livepatch on-prem, it makes sense to use S3 for patch storage if the expected number of client machines is high (over 2000). +In an AWS EC2 deployment of Livepatch on-prem, it makes sense to use S3 for patch storage if the expected number of client machines is high (over 2000). To configure this, follow these steps: @@ -18,9 +18,9 @@ To configure this, follow these steps: - Create a programmatic IAM user account with permissions to perform S3 operations. - Configure the relevant S3 [config options](/server/reference/platform/configuration.md) -Once this is configured, livepatch will store and retrieve patch files from the S3 bucket. +Once this is configured, Livepatch will store and retrieve patch files from the S3 bucket. -A further improvement is to configure livepatch on-prem to serve patches from the S3 bucket directly. For that public http access needs to be allowed to that bucket. Set your server's [URL template config](/server/reference/platform/configuration.md) to something resembling: +A further improvement is to configure Livepatch on-prem to serve patches from the S3 bucket directly. For that public http access needs to be allowed to that bucket. Set your server's [URL template config](/server/reference/platform/configuration.md) to something resembling: ``` https://.amazonaws.com/{filaname} diff --git a/docs/server/reference/platform/configuration.md b/docs/server/reference/platform/configuration.md index a160f77..e6d961b 100644 --- a/docs/server/reference/platform/configuration.md +++ b/docs/server/reference/platform/configuration.md @@ -1,242 +1,227 @@ --- myst: html_meta: - description: "Configuration - technical reference for Livepatch on-prem server." + description: "Reference for Livepatch on-premises server configuration options, covering server, authentication, database, patch storage, sync, telemetry, and machine reporting settings." --- - (server-reference-configuration)= # Configuration -This document provides the configuration options for the Livepatch server. +This document provides the configuration options for the Livepatch Server for both Juju charm and snap deployments. ```{note} -The configuration below applies to the Livepatch Server operator charms and Server snap. -For our reactive charm (or if your deployment config doesn't match the below), please see [here](/server/how-to-guides/deployment/migrate-from-reactive-charm-to-operator-charm.md). +The configuration below applies to the Livepatch Server operator charms and Server snap. +For reactive charm deployments — or if your deployment configuration differs from the options below — see the [migration guide from reactive charm to operator charm](/server/how-to-guides/deployment/migrate-from-reactive-charm-to-operator-charm.md). ``` -## Setting config +## Setting configuration -Depending on your deployment you may be using Juju + charms or a standalone Snap to deploy the Livepatch server. How you setup config will differ slightly between the two. +Configuration methods differ depending on whether the Livepatch Server is deployed with Juju and charms, or as a standalone snap. -Default and example values are available on the respective [machine](https://charmhub.io/canonical-livepatch-server/configurations?channel=ops1.x/stable) and [K8s](https://charmhub.io/canonical-livepatch-server-k8s/configurations) charm config pages. +Default and example values are available on the respective [machine charm](https://charmhub.io/canonical-livepatch-server/configurations?channel=ops1.x/stable) and [K8s charm](https://charmhub.io/canonical-livepatch-server-k8s/configurations) configuration pages. ### Juju -The config values in the table below map directly to the config options exposed by the Livepatch charms (except where otherwise stated). +The configuration keys in the table below map directly to the options exposed by the Livepatch charms, unless otherwise noted. -Assuming the Livepatch server has been deployed with the alias `livepatch`, to change a config value run: +Assuming the Livepatch Server has been deployed with the alias `livepatch`, apply configuration changes with: ``` juju config livepatch = -# E.g. to enable basic auth +# Example: enable basic authentication juju config livepatch auth.basic.enabled=true ``` -See the [Juju docs](https://documentation.ubuntu.com/juju/latest/reference/juju-cli/list-of-juju-cli-commands/config/) for all the ways you can apply config. +See the [Juju CLI configuration documentation](https://documentation.ubuntu.com/juju/latest/reference/juju-cli/list-of-juju-cli-commands/config/) for all available methods of applying configuration. ### Snap -The config values in the table below map directly to the config values accepted by the Livepatch server snap. An additional value must be added to all commands as shown below. +The configuration keys in the table below map directly to the values accepted by the Livepatch Server snap. Prepend `lp.` to all keys when setting snap configuration. -To change a config value run: +Apply configuration changes with: ``` sudo snap set canonical-livepatch-server lp.= -# E.g. to enable basic auth +# Example: enable basic authentication sudo snap set canonical-livepatch-server lp.auth.basic.enabled=true ``` -## Config +## Configuration options -The following sections describes what configuration values are available. +The following sections describe the available configuration values. -### Server config +### Server configuration -| Name | Description | Value(s) | -| - | - | - | -| `server.log-level` | Log level for the server | `debug, info, warn, error, dpanic, panic, fatal` | -| `server.redirect_downloads` | Whether to redirect patch download requests to the URL configured in the `server.url-template` option. | `bool` | -| `server.url-template` | The template URL to redirect clients for patch downloads. For example: `https://my-file-server.com/{filename}`. | `string` | +| Name | Description | Values | +| ---- | ----------- | ------ | +| `server.log-level` | Log level for the server. | `debug`, `info`, `warn`, `error`, `dpanic`, `panic`, `fatal` | +| `server.redirect_downloads` | Whether to redirect patch download requests to the URL specified in `server.url-template`. | `bool` | +| `server.url-template` | Template URL for redirecting clients for patch downloads. Example: `https://my-file-server.com/{filename}`. | `string` | | `server.server-address` | Listen address for the server. | `url` | | `server.concurrency-limit` | Maximum number of API requests to serve concurrently. | `integer` | -| `server.burst-limit` | The queue limit, roughly equals `concurrency-burst-limit`. | `integer` | -| `server.is-leader` | In multi-server deployments, determine if this is a leader unit. Not available for charmed deployments. | `bool`. | -| `server.is-hosted` | Enable configuration blocks specific to Canonical's hosted configuration for livepatch. | `bool` | - -### Admin Authentication +| `server.burst-limit` | Queue limit. Approximately equals `concurrency-limit`. | `integer` | +| `server.is-leader` | In multi-server deployments, determines whether this unit is the leader. Not available for charmed deployments. | `bool` | +| `server.is-hosted` | Enable configuration blocks specific to Canonical's hosted Livepatch configuration. | `bool` | -The following values configure authentication to the server's admin endpoints. -Besides basic auth, only Ubuntu SSO auth is supported. +### Admin authentication -Some notes on this section: +The following values configure authentication to the server's admin endpoints. Only Basic Auth and Ubuntu SSO authentication are supported. - SSO Teams represent Launchpad teams. -- Basic auth can be a comma separated list, see [here](/server/how-to-guides/security/setup-administration-tool.md#password-authentication) for more info. -- Basic auth passwords *must* be bcrypt hashed. - -| Name | Description | Value(s) | -| - | - | - | -| `auth.basic.enabled` | Whether or not to enable basic auth. | `bool`| -| `auth.basic.users` | A comma separated list of user objects. | `:, :` | -| `auth.sso.enabled` | Whether or not to enable Ubuntu SSO auth. | `bool`| -| `auth.sso.teams` | SSO Auth configuration. | `https://launchpad.net/~team-1,https://launchpad.net/~team-2` | -| `auth.sso.url` | URL to access for SSO auth. | `login.ubuntu.com` | -| `auth.sso.public-key` | Public key for the auth server. Can be a file path or the key. | `string` | +- Basic Auth configuration accepts a comma-separated list of users. See the [admin tool setup guide](/server/how-to-guides/security/setup-administration-tool.md#password-authentication) for details. +- Basic Auth passwords must be bcrypt hashed. + +| Name | Description | Values | +| ---- | ----------- | ------ | +| `auth.basic.enabled` | Enable Basic Auth. | `bool` | +| `auth.basic.users` | Comma-separated list of user objects. | `:, :` | +| `auth.sso.enabled` | Enable Ubuntu SSO authentication. | `bool` | +| `auth.sso.teams` | SSO authentication configuration listing authorised teams. | `https://launchpad.net/~team-1,https://launchpad.net/~team-2` | +| `auth.sso.url` | URL for SSO authentication. | `login.ubuntu.com` | +| `auth.sso.public-key` | Public key for the authentication server. Accepts a file path or an inline key. | `string` | ### Ubuntu Pro -The following values configure how the server interacts with the Ubuntu Pro backend (also called the contracts server) for authenticating clients. -This is useful for Canonical's hosted Livepatch server and airgapped deployments. +The following values configure how the server interacts with the Ubuntu Pro backend (also referred to as the contracts server) for client authentication. These are relevant for Canonical's hosted Livepatch Server and airgapped deployments. -| Name | Description | Value(s) | -| - | - | - | +| Name | Description | Values | +| ---- | ----------- | ------ | | `contracts.enabled` | Whether to connect to the contracts service. | `bool` | | `contracts.url` | URL of the contracts server. | `string` | -| `contracts.user` | Basic auth user. | `string` | -| `contracts.password` | Basic auth pass. | `string` | +| `contracts.user` | Basic Auth username for the contracts service. | `string` | +| `contracts.password` | Basic Auth password for the contracts service. | `string` | ### Database -The following values configure how the server interacts with its database. +The following values configure how the server interacts with its PostgreSQL database. -| Name | Description | Value(s) | -| - | - | - | -| `database.connection-string` | PostgreSQL connection string (unavailable for charmed deployments, handled with Juju relations). | `string` | -| `database.connection-pool-max` | Max pool for connections. | `int` | -| `database.connection-lifetime-max` | Max lifetime of connections. | `int` | -| `database.work-mem` | The maximum amount of memory in MB available for each query operation. | `int` | +| Name | Description | Values | +| ---- | ----------- | ------ | +| `database.connection-string` | PostgreSQL connection string. Unavailable for charmed deployments (handled through Juju relations). | `string` | +| `database.connection-pool-max` | Maximum number of connections in the pool. | `int` | +| `database.connection-lifetime-max` | Maximum lifetime of a database connection. | `int` | +| `database.work-mem` | Maximum memory in MB available for each query operation. | `int` | -### Influx +### InfluxDB -The following values configure how the server interacts with InfluxDB, used for sending aggregated KPIs. +The following values configure how the server interacts with InfluxDB for sending aggregated KPIs. -| Name | Description | Value(s) | -| - | - | - | -| `influx.enabled` | Whether to enable influx KPI reporting (hosted). | `bool` | -| `influx.url` | URL of the Influx server. | `string` | -| `influx.token` | Auth token. | `string` | -| `influx.bucket` | Bucket to use. | `string` | -| `influx.ping_bucket` | Bucket to use for sending patch ping data, for example, under a different retention policy. If empty, this is set to the value of `influx.bucket`. | `string` | -| `influx.organization` | Org where bucket resides. | `string` | +| Name | Description | Values | +| ---- | ----------- | ------ | +| `influx.enabled` | Whether to enable InfluxDB KPI reporting (hosted). | `bool` | +| `influx.url` | URL of the InfluxDB server. | `string` | +| `influx.token` | Authentication token for InfluxDB. | `string` | +| `influx.bucket` | InfluxDB bucket to use. | `string` | +| `influx.ping_bucket` | Bucket for sending patch ping data, for example under a different retention policy. If empty, defaults to the value of `influx.bucket`. | `string` | +| `influx.organization` | InfluxDB organisation containing the bucket. | `string` | ### TimescaleDB -The following values configure how the server interacts with its TimescaleDB instance, used for storing time-series patch ping metrics. -TimescaleDB runs as a PostgreSQL extension on a dedicated PostgreSQL instance separate from the main database. -TimescaleDB can be enabled along side or can replace InfluxDB for KPI metrics. +The following values configure how the server interacts with its TimescaleDB instance for storing time-series patch ping metrics. TimescaleDB runs as a PostgreSQL extension on a dedicated PostgreSQL instance, separate from the main database. TimescaleDB can be enabled alongside or as a replacement for InfluxDB for KPI metrics. -| Name | Description | Value(s) | -| - | - | - | +| Name | Description | Values | +| ---- | ----------- | ------ | | `timescale-db.enabled` | Whether to enable the TimescaleDB store for KPI metrics. | `bool` | | `timescale-db.connection-string` | Connection string for the TimescaleDB PostgreSQL instance. | `string` | | `timescale-db.connection-pool-max` | Maximum number of connections in the pool (1–1000). | `int` | | `timescale-db.connection-lifetime-max` | Maximum lifetime of a connection before it is recycled. | `duration` | -| `timescale-db.work-mem` | The maximum amount of memory in MB available for each query operation. | `int` | -| `timescale-db.flush-timeout` | How long the store waits before flushing buffered writes. Defaults to 1 minute if unset. | `duration` | - -### Patch Storage - -The following values configure how the server interacts with its patch storage.\ -See our [how-to](/server/reference/patch-storage/index.md) on patch storage. - -| Name | Description | Value(s) | -| - | - | - | -| `patch-storage.type` | File storage type to use for on-prem deployment patch syncs | `oneof: filesystem,swift,postgres,s3` | -| `patch-storage.filesystem-path` | File path to directory to use for storage | `string` | -| `patch-storage.swift-username` | User of account. | `string` | -| `patch-storage.swift-api-key` | Auth API key. | `string` | -| `patch-storage.swift-auth-url` | Auth Url. | `string` | -| `patch-storage.swift-domain` | Swift domain to connect to. | `string` | -| `patch-storage.swift-tenant` | Swift tenancy. | `string` | +| `timescale-db.work-mem` | Maximum memory in MB available for each query operation. | `int` | +| `timescale-db.flush-timeout` | Duration the store waits before flushing buffered writes. Defaults to 1 minute if unset. | `duration` | + +### Patch storage + +The following values configure how the server manages patch storage. See the [patch storage how-to guide](/server/reference/patch-storage/index.md) for details. + +| Name | Description | Values | +| ---- | ----------- | ------ | +| `patch-storage.type` | Storage backend type for on-premises patch synchronisation. | `oneof: filesystem, swift, postgres, s3` | +| `patch-storage.filesystem-path` | Directory path for filesystem storage. | `string` | +| `patch-storage.swift-username` | Swift account username. | `string` | +| `patch-storage.swift-api-key` | Swift API key. | `string` | +| `patch-storage.swift-auth-url` | Swift authentication URL. | `string` | +| `patch-storage.swift-domain` | Swift domain. | `string` | +| `patch-storage.swift-tenant` | Swift tenant. | `string` | | `patch-storage.swift-container` | Swift container bucket. | `string` | | `patch-storage.swift-region` | Swift region. | `string` | -| `patch-storage.postgres-connection-string` | PostgreSQL connection string (can be left blank in charmed deployments to use Juju relations). | `string` | -| `patch-storage.s3-bucket` | S3 Bucket to store patches. | `string` | -| `patch-storage.s3-endpoint` | S3 endpoint. | `string` | -| `patch-storage.s3-region` | AWS Region for S3. | `string` | -| `patch-storage.s3-secure` | Whether to perform secure transfers. | `bool` | -| `patch-storage.s3-access-key` | AWS Access key. | `string` | -| `patch-storage.s3-secret-key` | AWS Secret key. | `string` | +| `patch-storage.postgres-connection-string` | PostgreSQL connection string. Can be left blank in charmed deployments to use Juju relations. | `string` | +| `patch-storage.s3-bucket` | S3 bucket for storing patches. | `string` | +| `patch-storage.s3-endpoint` | S3 endpoint URL. | `string` | +| `patch-storage.s3-region` | AWS region for S3. | `string` | +| `patch-storage.s3-secure` | Whether to use secure transfers. | `bool` | +| `patch-storage.s3-access-key` | AWS access key. | `string` | +| `patch-storage.s3-secret-key` | AWS secret key. | `string` | -### Patch Cache +### Patch cache The following values configure the server's patch cache. -| Name | Description | Value(s) | -| - | - | - | -| `patch-cache.enabled` | Whether or not to cache patches for quicker delivery. | `bool` | -| `patch-cache.cache-ttl` | TTL of patches in cache. | `string` | -| `patch-cache.cache-size` | Maximum size of caching for patches. | `int` | +| Name | Description | Values | +| ---- | ----------- | ------ | +| `patch-cache.enabled` | Whether to enable patch caching for faster delivery. | `bool` | +| `patch-cache.cache-ttl` | Time-to-live for cached patches. | `string` | +| `patch-cache.cache-size` | Maximum size of the patch cache. | `int` | -### Patch Sync +### Patch sync -The following values configure how the server syncs patches from an upstream server. +The following values configure how the server synchronises patches from an upstream server. -| Name | Description | Value(s) | -| - | - | - | -| `patch-sync.enabled` | Whether patch syncs are enabled. | `bool` | -| `patch-sync.id` | ID of unit (not available in charmed deployments). | `string` | -| `patch-sync.minimum-kernel-version` | A minimum kernel version of format "0.0.0" denoting the lowest kernel version to download patches for. For example, "5.4.0" will sync "5.4.0" and up. | `string` | +| Name | Description | Values | +| ---- | ----------- | ------ | +| `patch-sync.enabled` | Whether patch synchronisation is enabled. | `bool` | +| `patch-sync.id` | Unit ID. Not available in charmed deployments. | `string` | +| `patch-sync.minimum-kernel-version` | Minimum kernel version to download patches for, in `0.0.0` format. Example: `5.4.0` syncs `5.4.0` and above. | `string` | | `patch-sync.architectures` | Comma-separated list of kernel architectures to download patches for. | `string` | -| `patch-sync.flavors` | Comma-separated list of kernel flavors to download patches for. | `string` | -| `patch-sync.interval` | Automatic sync interval e.g. 12h. | `string` | -| `patch-sync.machine-count-strategy` | Define the way sync reports the machine counts, either by units or by buckets. On on-prem instances the counts are bucketed and the value reported is given by lower bound of the following buckets: `[1-49]`, `[50-99]`, `[100-499]`, `[500-999]`, `[1000-1999]`, `[2000-4999]`, `[5000-9999]`, `[10000, ∞]`. | `oneof: unit,bucket` | -| `patch-sync.send-machine-reports` | Whether or not to send machine reports. | `bool` | -| `patch-sync.token` | Token used to authorise with an upstream Livepatch server. | `string` | -| `patch-sync.upstream-url` | The upstream server to pull patches from. | `string` | -| `patch-sync.sync-tiers` | Enable syncing tiers from upstream server. | `bool` | -| `patch-sync.proxy.enabled` | Enable use of a proxy when syncing patches. | `bool` | -| `patch-sync.proxy.http` | HTTP Proxy. | `string` | -| `patch-sync.proxy.https` | HTTPS Proxy. | `string` | -| `patch-sync.proxy.no-proxy` | Comma separated list of addresses that should not go through the proxy. | `string` | - -### Blocklist Cache +| `patch-sync.flavors` | Comma-separated list of kernel flavours to download patches for. | `string` | +| `patch-sync.interval` | Automatic synchronisation interval (for example `12h`). | `string` | +| `patch-sync.machine-count-strategy` | Strategy for reporting machine counts: `unit` reports exact counts; `bucket` reports bucketed counts using the following lower bounds: `[1-49]`, `[50-99]`, `[100-499]`, `[500-999]`, `[1000-1999]`, `[2000-4999]`, `[5000-9999]`, `[10000, ∞]`. | `oneof: unit, bucket` | +| `patch-sync.send-machine-reports` | Whether to send machine reports during synchronisation. | `bool` | +| `patch-sync.token` | Token for authenticating with an upstream Livepatch Server. | `string` | +| `patch-sync.upstream-url` | URL of the upstream server to pull patches from. | `string` | +| `patch-sync.sync-tiers` | Whether to synchronise tiers from the upstream server. | `bool` | +| `patch-sync.proxy.enabled` | Whether to use a proxy when synchronising patches. | `bool` | +| `patch-sync.proxy.http` | HTTP proxy URL. | `string` | +| `patch-sync.proxy.https` | HTTPS proxy URL. | `string` | +| `patch-sync.proxy.no-proxy` | Comma-separated list of addresses to bypass the proxy. | `string` | + +### Blocklist cache The following values configure the server's patch blocklist cache. -| Name | Description | Value(s) | -| - | - | - | -| `patch-blocklist.enabled` | Whether or not to enable the blocklist cache. | `bool` | -| `patch-blocklist.refresh-interval` | How often to refresh the blocklist cache. | `string` | +| Name | Description | Values | +| ---- | ----------- | ------ | +| `patch-blocklist.enabled` | Whether to enable the blocklist cache. | `bool` | +| `patch-blocklist.refresh-interval` | Interval for refreshing the blocklist cache. | `string` | -### KPI Reports +### KPI reports -The following values configure how the server sends KPI reports. This requires Influx to be setup. -KPIs include aggregated information on client machines e.g. the client version, patch status, etc. +The following values configure how the server sends KPI reports. KPI reports require InfluxDB to be configured. KPIs include aggregated information on client machines such as client version and patch status. -| Name | Description | Value(s) | -| - | - | - | -| `kpi-reports.enabled` | Whether or not to enable KPI reporting. | `bool` | -| `kpi-reports.interval` | How often to submit reports. | `string` | +| Name | Description | Values | +| ---- | ----------- | ------ | +| `kpi-reports.enabled` | Whether to enable KPI reporting. | `bool` | +| `kpi-reports.interval` | Interval for submitting KPI reports. | `string` | ### Machine reports -The following values configure the server's behavior with machine reports. -Machine reports are stored in PostgreSQL and store information when client's check-in. - - +The following values configure the server's machine report behaviour. Machine reports are stored in PostgreSQL and capture information when clients check in. -| Name | Description | Value(s) | -| - | - | - | -| `machine-reports.database.enabled` | Whether or not to enable machine reporting to postgres. Reports are stored in the server's postgres store. | `bool` | -| `machine-reports.database.retention-days` | Retention for the given reports. | `int` | -| `machine-reports.database.cleanup-row-limit` | Row limit for each cleanup operation. | `int` | -| `machine-reports.database.cleanup-interval` | How often to perform cleanups. | `string` | +| Name | Description | Values | +| ---- | ----------- | ------ | +| `machine-reports.database.enabled` | Whether to enable machine reporting to PostgreSQL. Reports are stored in the server's PostgreSQL database. | `bool` | +| `machine-reports.database.retention-days` | Number of days to retain machine reports. | `int` | +| `machine-reports.database.cleanup-row-limit` | Maximum number of rows to delete per cleanup operation. | `int` | +| `machine-reports.database.cleanup-interval` | Interval for running report cleanup operations. | `string` | -## Cloud delay +### Cloud delay (deprecated) -The following values configure the server's behavior with cloud-delays. +The following values configure the server's cloud delay behaviour. ```{note} -The cloud delay feature is deprecated in favor of the patch-delay and cutoff-date configuration in Livepatch Client. +The cloud delay feature is deprecated. Use the `patch-delay` and `cutoff-date` configuration options on the Livepatch Client instead. ``` -| Name | Description | Value(s) | -| - | - | - | -| `cloud-delay.enabled` | Enable the server to delay the release of patches to clients based on their cloud/region/az | `bool` | -| `cloud-delay.default-delay-hours` | Default delay hours for clouds/regions/azs without predefined delay hours | `int` | +| Name | Description | Values | +| ---- | ----------- | ------ | +| `cloud-delay.enabled` | Whether to delay patch releases to clients based on their cloud, region, or availability zone. | `bool` | +| `cloud-delay.default-delay-hours` | Default delay in hours for clouds, regions, or availability zones without a specified delay. | `int` | \ No newline at end of file diff --git a/docs/server/reference/platform/index.md b/docs/server/reference/platform/index.md index 06074bc..93d2840 100644 --- a/docs/server/reference/platform/index.md +++ b/docs/server/reference/platform/index.md @@ -1,21 +1,20 @@ --- myst: html_meta: - description: "Configuration, resource requirements, and network access." + description: "Reference for Livepatch on-premises platform requirements, including configuration options, resource requirements, and network access rules." --- - (server-reference-platform)= # Platform -Configuration, resource requirements, and network access. +Configuration options, resource requirements, and network access rules for the Livepatch on-premises server. ## In this section -- [Configuration](/server/reference/platform/configuration.md) -- [Resource requirements](/server/reference/platform/resource-requirements.md) -- [Network access](/server/reference/platform/network-access.md) +- [Configuration](/server/reference/platform/configuration.md) — All available configuration options for the Livepatch Server, including Juju and snap deployment methods. +- [Resource requirements](/server/reference/platform/resource-requirements.md) — Minimum CPU, memory, and disk requirements for server components. +- [Network access](/server/reference/platform/network-access.md) — Hostnames and ports the Livepatch Server requires for outbound connectivity. ```{toctree} :titlesonly: @@ -25,4 +24,4 @@ Configuration, resource requirements, and network access. Configuration Resource requirements Network access -``` +``` \ No newline at end of file diff --git a/docs/server/reference/platform/network-access.md b/docs/server/reference/platform/network-access.md index 5f0e9f2..58b34b1 100644 --- a/docs/server/reference/platform/network-access.md +++ b/docs/server/reference/platform/network-access.md @@ -1,18 +1,17 @@ --- myst: html_meta: - description: "Network access - technical reference for Livepatch on-prem server." + description: "Reference for Livepatch on-premises network access requirements, listing the hostnames and ports needed for outbound connectivity from firewalled deployments." --- - (server-reference-livepatch-on-prem-network-access-requirements)= # Livepatch on-prem network access requirements -On firewalled deployments, Livepatch on-prem needs access to the following hostnames: +On firewalled deployments, the Livepatch on-premises server requires outbound access to the following hostnames: - `livepatch.canonical.com`, port 443 - `livepatch-files.canonical.com`, port 443 - `contracts.canonical.com`, port 443 -For snap installation, see [snap network requirements ](https://forum.snapcraft.io/t/network-requirements/5147). +For snap installations, see the [snap network requirements](https://forum.snapcraft.io/t/network-requirements/5147). \ No newline at end of file diff --git a/docs/server/reference/platform/resource-requirements.md b/docs/server/reference/platform/resource-requirements.md index 166feb0..3a3ac43 100644 --- a/docs/server/reference/platform/resource-requirements.md +++ b/docs/server/reference/platform/resource-requirements.md @@ -1,24 +1,23 @@ --- myst: html_meta: - description: "Resource requirements - technical reference for Livepatch on-prem server." + description: "Reference for Livepatch on-premises server resource requirements, listing minimum CPU, memory, and disk allocations for PostgreSQL, HAProxy, and Livepatch components." --- - (server-reference-machine-resources-for-livepatch-on-prem)= -# Machine resources for livepatch on-prem +# Machine resources for Livepatch on-prem -The resource requirements for machines running livepatch on-prem components (postgresql, haproxy, livepatch) depend on the amount of machines being serviced by the deployment. +The resource requirements for machines running Livepatch on-prem components (PostgreSQL, HAProxy, and Livepatch) depend on the number of machines served by the deployment. -Minimal requirements are: +The following are the minimum recommended allocations: -|Service|Memory|CPUs|Disk| -| --- | --- | --- | --- | -|postgresql|4GB|1|50GB| -|haproxy|2GB|1|50GB| -|livepatch|2GB|1|50GB| +| Service | Memory | CPUs | Disk | +| ---------- | ------ | ---- | ---- | +| PostgreSQL | 4 GB | 1 | 50 GB | +| HAProxy | 2 GB | 1 | 50 GB | +| Livepatch | 2 GB | 1 | 50 GB | -If postgresql is going to be used as the patchstore, we recommend increasing disk allocated to postgresql to 100GB. +If PostgreSQL is configured as the patch storage backend, increase the disk allocation for PostgreSQL to 100 GB. -The bundle needs to be deployed on machines running Ubuntu focal. +The bundle must be deployed on machines running Ubuntu Focal (20.04 LTS). \ No newline at end of file diff --git a/docs/server/reference/telemetry/data-sent.md b/docs/server/reference/telemetry/data-sent.md index 2814cce..c8ae605 100644 --- a/docs/server/reference/telemetry/data-sent.md +++ b/docs/server/reference/telemetry/data-sent.md @@ -1,23 +1,22 @@ --- myst: html_meta: - description: "Data sent - learn about this topic in Livepatch on-prem." + description: "Reference listing the data transmitted by Livepatch on-premises deployments to Canonical during periodic patch synchronisation checks." --- - (server-reference-data-sent-to-canonical-servers)= # Data sent to Canonical servers -Livepatch on-prem deployments periodically send requests to servers hosted by Canonical to check for the availability of new livepatches. These requests contain a unique ID of the deployment and the number of machines served by the deployment. +Livepatch on-prem deployments periodically send requests to servers hosted by Canonical to check for the availability of new live kernel patches. These requests include the following information: - Unique ID of the deployment - Number of machines served by the deployment -Additional reporting can be enabled by running +Additional machine-level reporting can be enabled by setting the `patch-sync.send-machine-reports` configuration option. For example, using Juju: ``` -juju config livepatch sync_send_machine_reports=true +juju config livepatch patch-sync.send-machine-reports=true ``` -Changing this config setting will allow livepatch on-prem to send reports about the exact state of each machine served by the deployment. +Enabling this setting allows Livepatch on-prem to send reports about the exact state of each machine served by the deployment. \ No newline at end of file diff --git a/docs/server/reference/telemetry/index.md b/docs/server/reference/telemetry/index.md index a56e0d9..44035cf 100644 --- a/docs/server/reference/telemetry/index.md +++ b/docs/server/reference/telemetry/index.md @@ -1,26 +1,25 @@ --- myst: html_meta: - description: "Data sent to Canonical and machine reports." + description: "Reference for Livepatch on-premises telemetry, including data sent to Canonical during synchronisation and machine report configuration." --- - (server-reference-telemetry)= # Telemetry -Data sent to Canonical and machine reports. +Data sent to Canonical during patch synchronisation, and configuration of machine reports. ## In this section -- [Data sent](/server/reference/telemetry/data-sent.md) -- [Machine reports](/server/reference/telemetry/machine-reports.md) +- [Data sent to Canonical](/server/reference/telemetry/data-sent.md) — Information transmitted by the server during patch synchronisation requests. +- [Machine reports](/server/reference/telemetry/machine-reports.md) — How to enable and generate reports on the state of registered machines. ```{toctree} :titlesonly: :maxdepth: 1 :hidden: -Data sent +Data sent to Canonical Machine reports -``` +``` \ No newline at end of file diff --git a/docs/server/reference/telemetry/machine-reports.md b/docs/server/reference/telemetry/machine-reports.md index 8b392e9..a650bae 100644 --- a/docs/server/reference/telemetry/machine-reports.md +++ b/docs/server/reference/telemetry/machine-reports.md @@ -1,27 +1,25 @@ --- myst: html_meta: - description: "Machine reports - learn about this topic in Livepatch on-prem." + description: "Reference for machine reports in Livepatch on-prem, covering report configuration, generation, and querying via the livepatch-admin tool." --- - (server-reference-machine-reports)= -# Machine Reports - -Each machine running the Livepatch Client will periodically check in with its configured server. +# Machine reports -The machine checks for patches and sends machine status information. The full list of information sent is documented [here](/client/reference/networking/data-sent.md). +Each machine running the Livepatch Client periodically checks in with its configured server. During this check-in, the machine queries for available patches and sends machine status information. For a full list of the information sent by clients, see the [Livepatch Client data reference](/client/reference/networking/data-sent.md). -## Enabling Machine Reports +## Enable machine reports -See our [machine reports config](/server/reference/platform/configuration.md) to enable machine reports and configure their retention period. +To enable machine reports and configure their retention period, see the [machine reports configuration options](/server/reference/platform/configuration.md) in the Livepatch Server configuration reference. -## Generating Machine Reports +## Generate machine reports -To generate machine reports use the Livepatch admin tool. -See [our how-to](/server/how-to-guides/security/setup-administration-tool.md) on setting up the admin tool. +Machine reports are generated using the Livepatch Admin Tool. See the [admin tool setup guide](/server/how-to-guides/security/setup-administration-tool.md) for instructions on configuring the tool. -You can create machine reports where you query machines by their tier, last applied patch version or patch state. +Generate a machine report by querying machines by their tier, last applied patch version, or patch state: -`livepatch-admin report machines [ [ [ []] +``` \ No newline at end of file diff --git a/docs/server/tutorial/airgapped-livepatch-and-microk8s.md b/docs/server/tutorial/airgapped-livepatch-and-microk8s.md index 337e3d8..1f6c195 100644 --- a/docs/server/tutorial/airgapped-livepatch-and-microk8s.md +++ b/docs/server/tutorial/airgapped-livepatch-and-microk8s.md @@ -1,339 +1,320 @@ --- myst: html_meta: - description: "Tutorial: Air-gapped Livepatch and MicroK8s - hands-on introduction to Livepatch on-prem." + description: "Complete a hands-on tutorial for airgapped Livepatch on-prem on MicroK8s. Deploy Livepatch and an airgapped Ubuntu Pro server using Juju in about 60 minutes." --- (server-tutorial-airgapped-livepatch-and-microk8s)= -# Airgapped Livepatch and MicroK8s +# Getting started with airgapped Livepatch on-prem and MicroK8s -## Introduction +> See also: {ref}`server` -Livepatch on-prem is a self-hosted version of the Livepatch server, enabling the delivery of patches to machines within network restricted environments. For security reasons, administrators may prefer to deploy Livepatch on-prem server in an airgapped environment with restricted Internet access. +This tutorial guides you through the process of deploying Livepatch on-prem in an airgapped environment using MicroK8s and Juju. Livepatch on-prem enables the delivery of kernel patches to machines within network-restricted environments. For organisations with strict security requirements, deploying Livepatch on-prem in an airgapped setup ensures that the server operates without direct communication to the upstream Livepatch service. -This tutorial will deploy the Livepatch on-prem server as a Kubernetes application in an airgapped environment. We will deploy and configure the Livepatch on-prem server using Juju and Charmed Operators. Juju is an Open Source Charmed Operator Framework that controls the whole lifecycle of an application. +In an airgapped environment, two additional tools replace the server's direct connection to Canonical's hosted Livepatch service: -For this tutorial, we will use Microk8s, a lightweight tool for creating a local Kubernetes cluster. You don’t need previous knowledge of Juju or Charmed Operators to follow this guide and deploy Livepatch. +- The **airgapped Ubuntu Pro server** provides Ubuntu Pro subscription services, including machine authentication and authorisation, without requiring Internet access. +- The **Patch Downloader** is a CLI tool for downloading the latest patch files from the upstream Livepatch Server. Administrators use this tool on an Internet-connected machine, then transfer the downloaded patches to the airgapped patch storage. -### How does Livepatch on-prem work in an airgapped environment? +```{note} +When deploying airgapped Livepatch on-prem on MicroK8s, configure the patch storage to use an independently accessible option such as an S3 or Swift bucket instead of PostgreSQL or the filesystem. This allows administrators to download patches with the Patch Downloader tool and transfer them to the storage independently. +``` -Generally, in order to perform authentication/authorisation of machines and also fetching latest patches, the Livepatch on-prem server needs to communicate with the main Livepatch server hosted by Canonical. In an airgapped environment, where such communication is not available, these functions have to be handled in an indirect way by using the following tools: +Completing this tutorial should take approximately 60 minutes. -- [**Airgapped Ubuntu Pro Server**](https://discourse.charmhub.io/t/15278) is an on-prem deployable service that provides services related to Ubuntu Pro subscriptions in airgapped environments. Livepatch on-prem can be integrated with this service to perform authentication/authorisation of machines and handle subscription-related functionalities. -- [**Patch Downloader**](https://snapcraft.io/canonical-livepatch-downloader) is a CLI tool that can be used to download the latest patch files from the Livepatch server. In an airgapped setup, the administrators of Livepatch on-prem should use this tool to fetch the latest patches and then upload them to the configured patch storage. You can check out [this](/server/reference/patch-storage/index) topic on how to configure various types of storage for Livepatch on-prem. [This](/server/how-to-guides/patch-management/use-the-patch-downloader-tool) topic explains how to use the Patch Downloader tool to fetch patches. +## Prerequisites -```{note} -When deploying airgapped Livepatch on-prem on MicroK8s, it is best to configure the patch storage to something independently accessible within your infrastructure, like an S3/Swift bucket, instead of PostgreSQL or filesystem. This way, Livepatch administrators can independently download the latest patches via the Patch Downloader CLI tool and transfer them to the patch storage. -``` +Before starting this tutorial, you'll need the following tools and resources. + +### Ubuntu Pro token + +You'll need an [Ubuntu Pro token](https://ubuntu.com/pro). Ubuntu Pro is free for up to five machines. + +If you already have an Ubuntu Pro account, copy your token from the [Ubuntu Pro dashboard](https://ubuntu.com/pro/dashboard). If you don't have an account, sign up for a [free personal Ubuntu Pro account](https://ubuntu.com/pro), then copy your token. -## Deployment steps +### Multipass -In this tutorial, we use [Multipass](https://multipass.run) to create an Ubuntu virtual machine (VM) to deploy Livepatch and its dependencies on it. If not already installed, we can use the command below to install Multipass: +Multipass is a CLI tool for launching Ubuntu VMs from Windows, Linux, and macOS. -```sh +Install Multipass from the Snap Store: + +```bash sudo snap install multipass ``` -### Step 1: Create a VM - -Once Multipass is installed, you can create the VM for this tutorial by running the command below. This will create a VM, named `livepatch-deploy` with the sufficient resources. +Launch a VM with sufficient resources for the Livepatch deployment: -```sh +```bash multipass launch jammy --name livepatch-deploy --cpus 6 --memory 12G --disk 40G ``` -Once the VM is created you need to open an interactive shell into it by running: +Open an interactive shell into the VM: -```sh +```bash multipass shell livepatch-deploy ``` -### Step 2: Setup MicroK8s +All subsequent commands in this tutorial are run from within this VM. + +## Install and configure MicroK8s -To deploy Livepatch on-prem and the airgapped Ubuntu Pro server, we would need Juju, MicroK8s, and LXD. The latter is already installed in the VM, so we just need the other two. To install MicroK8s, you need to use the following command: +Install MicroK8s from the Snap Store: -```sh +```bash sudo snap install microk8s --channel=1.30-strict/stable ``` -Once the installation is done, you need to apply the following configurations to make it easier to use MicroK8s with the current user and the `kubectl` CLI tool: +Configure MicroK8s for the current user: -```sh +```bash sudo usermod -a -G snap_microk8s $USER mkdir -p ~/.kube chmod 0700 ~/.kube newgrp snap_microk8s ``` -The next step is to enable some required addons on your MicroK8s cluster. To do this, you need to run: +Enable the required addons: -```sh +```bash sudo microk8s enable rbac sudo microk8s enable hostpath-storage sudo microk8s enable ingress ``` -Now, to make sure MicroK8s is up and running, try: +Verify MicroK8s is running: -```sh +```bash microk8s status --wait-ready ``` -You should see an output like this, which means MicroK8s is ready to be used. - -```text -microk8s is running -... -``` - -### Step 3: Setup Juju +## Install and bootstrap Juju -In this tutorial, we use Juju 3.5, which can be installed by running: +Install Juju from the Snap Store: -```sh +```bash sudo snap install juju --channel=3.5/stable ``` -After the installation is done, we need to modify the MicroK8s client configuration file so that the API address is accessible to the Juju controllers we are going to create in the next steps. To do this, we need to run the following: +Modify the MicroK8s client configuration file so the API address is accessible to Juju controllers: -```sh +```bash microk8s.config > /tmp/microk8s.config sudo cp /tmp/microk8s.config /var/snap/microk8s/current/credentials/client.config sudo snap restart microk8s ``` -Now, we need to bootstrap two controllers; one on our MicroK8s cluster, and one one LXD. We will use the MicroK8s controller to deploy Livepatch on-prem, and the other to deploy the airgapped Ubuntu Pro server. - -To bootstrap a controller on LXD, we need to run: +Bootstrap two Juju controllers: one on MicroK8s for the Livepatch on-prem deployment, and one on LXD for the airgapped Ubuntu Pro server. -```sh +```bash juju bootstrap localhost pro-demo-controller -``` - -This might take a while to complete. After it is done, we can use a similar command to bootstrap a Juju controller on Microk8s: - -```sh juju bootstrap microk8s livepatch-demo-controller ``` -After the completion of the above commands, you can checkout the available Juju controllers by running `juju controllers` which should print out the list of controllers like this: +Verify both controllers are available: -```sh +```bash juju controllers -Controller Model User Access Cloud/Region Models Nodes HA Version -livepatch-demo-controller* controller admin superuser microk8s/localhost 1 1 - 3.5.3 -pro-demo-controller controller admin superuser localhost/localhost 1 1 none 3.5.3 ``` -### Step 4: Deploy Livepatch on-prem +## Deploy Livepatch on-prem -First we need to create a Juju model to deploy Livepatch on-prem onto. To do this we need to run: +Create a Juju model and deploy the Livepatch on-prem bundle: -```sh +```bash juju add-model livepatch -``` - -In order to deploy Livepatch on-prem, we can simply use the `k8s/stable` channel of the [bundle](https://charmhub.io/canonical-livepatch-onprem?channel=k8s/stable) charm. The bundle gives us all we need to deploy a working Livepatch on-prem server. - -```sh juju deploy canonical-livepatch-onprem --channel=k8s/stable --trust ``` -Deploying the bundle takes a while to create the underlying pods/containers and integrating them to each other. We can check out the status of the model by running: +Monitor the deployment: -```sh +```bash juju status --watch 5s ``` -Once the status of the `livepatch` application changes to *"patch-sync token not set..."*, we are ready to continue. +Once the status of the `livepatch` application changes to *"patch-sync token not set..."*, the deployment is initialised. ```{note} -By default, the charm assumes an ordinary deployment of the Livepatch on-prem server (i.e., a non-airgapped setup), and that is why it asks for a patch synchronisation token. Since this is an airgapped deployment, you should ignore this message and proceed with integrating the charm with an airgapped Ubuntu Pro server. +By default, the charm assumes an ordinary (non-airgapped) deployment and prompts for a patch-sync token. Since this is an airgapped deployment, you can ignore this message and proceed with integrating the airgapped Ubuntu Pro server. ``` -Before continuing with the airgapped Ubuntu Pro server, we need to make sure the Livepatch on-prem server is accessible through a domain name. Depending on IP addresses is not a reliable solution when referencing applications deployed on Kubernetes from outside the cluster. The standard practice is to use a Kubernetes ingress. +### Configure the ingress -To create the ingress resource on our model and point it to the running Livepatch server, we need to configure the `nginx-ingress-integrator` charm that is already deployed in our model under an application, named `ingress`: +Configure the nginx ingress integrator charm with a domain name for the Livepatch Server: -```sh +```bash juju config ingress service-hostname=livepatch.test.com ``` -```{note} -Here, we used `livepatch.test.com` as the domain name, but this can be anything. -``` - -After applying the command it takes a little time to create the corresponding `ingress` resource on the MicroK8s cluster. As mentioned, we can track the status of the Juju model by using `juju status --watch 5s`. - -Once the operation is finished, the `ingress` application status message will show the IP address at which the ingress resource is accessible with the `livepatch.test.com` domain name. Alternatively, we can see the IP address of the ingress resource by running: +After a short delay, verify the ingress resource was created: -```sh +```bash microk8s kubectl get ingress -n livepatch ``` -This will print out a single item like this: +The output shows the IP address where the ingress is accessible. Add a corresponding entry to the VM's `/etc/hosts` file: +```bash +echo "127.0.0.1 livepatch.test.com" | sudo tee -a /etc/hosts ``` -NAME CLASS HOSTS ADDRESS PORTS AGE -relation-6-livepatch-test-com-ingress public livepatch.test.com 127.0.0.1 80 4d3h -``` - -As you can see the IP address to access the ingress resource is `127.0.0.1`. Note that depending on the network/MicroK8s configuration, the IP can differ from the loopback interface address we see in this case. - -To finish this step, we need to add an entry to our VMs `/etc/hosts` (mapping `livepatch.test.com` to `127.0.0.1`) to make our Livepatch on-prem server accessible to the airgapped Ubuntu Pro server we are going to deploy in the next step. ```{note} -Note that in a real-world scenario, the airgapped Ubuntu Pro server might be deployed on another node/VM. So, the administrators might need to follow their procedures to enable communication between the deployments. -``` - -You can use the command below to add the mentioned entry to the `/etc/hosts` file: - -```sh -echo "127.0.0.1 livepatch.test.com" | sudo tee -a /etc/hosts +In a real-world deployment, the airgapped Ubuntu Pro server may be deployed on a separate node. Administrators should follow their own procedures to enable communication between the deployments. ``` -### Step 5: Deploy airgapped Ubuntu Pro server +## Deploy the airgapped Ubuntu Pro server -To deploy the airgapped Ubuntu Pro server, we are going to use the [`pro-airgapped-server`](https://charmhub.io/pro-airgapped-server) charm. Since this is a machine charm, we have to deploy it on a model on LXD. The first step is to switch to our LXD controller and create a model on that: +Switch to the LXD controller and create a new model: -```sh +```bash juju switch pro-demo-controller juju add-model pro ``` -After the model is created, we can deploy the `pro-airgapped-server` charm by running: +Deploy the `pro-airgapped-server` charm: -```sh +```bash juju deploy pro-airgapped-server ``` -You can watch the model status changes by running `juju status --watch 5s`. +Provide your Ubuntu Pro token. Replace `` with your token: -After the charm is deployed, it will be in a blocked state waiting for an Ubuntu Pro token. You can find your Ubuntu Pro subscription token on the Ubuntu Pro [dashboard](https://ubuntu.com/pro/dashboard) page. Copy your subscription token, replace the `` placeholder in the command below with your token, and run it: - -```sh +```bash juju config pro-airgapped-server pro-tokens= ``` -After that, you need to provide the charm with your Livepatch on-prem address. Assuming you are using the same `livepatch.test.com` domain, you can run: +Configure the charm with your Livepatch on-prem address: -```sh -juju config pro-airgapped-server entitlements-url-map='{"livepatch": {"remoteServer": "http://livepatch.test.com"},"livepatch-onprem": {"remoteServer": "http://livepatch.test.com"}}' +```bash +juju config pro-airgapped-server entitlements-url-map='{"livepatch": {"remoteServer": "http://livepatch.test.com"},"livepatch-onprem": {"remoteServer": "http://livepatch.test.com"}}' ``` -Now, the `pro-airgapped-server` application status should be `active`. - -We should now create a Juju *application offer* to allow applications on other Juju models/controllers (i.e., Livepatch on-prem server, in this case) to integrate with the `pro-airgapped-server` application in the current model. You can simply create an application offer by running: +Once the application status shows `active`, create a Juju application offer to allow the Livepatch on-prem deployment on the MicroK8s controller to integrate with it: -```sh +```bash juju offer pro-airgapped-server:livepatch-server pro-offer ``` -Before we finish this step, we need to take note of the IP address of the `pro-airgapped-server` application. We will need it later when we are going to set up Ubuntu Pro clients. To find the IP address, you can just run `juju status` and copy the public IP address printed next to the `pro-airgapped-server/0` unit. +Note the IP address of the `pro-airgapped-server/0` unit from `juju status`. You'll need this later when configuring the Livepatch Client: + +```bash +juju status +``` -### Step 6: Enable airgapped operation on Livepatch on-prem +## Integrate Livepatch on-prem with the airgapped Ubuntu Pro server -We should now switch back to the Juju model containing the Livepatch on-prem and finish the integration with the `pro-airgapped-server` application. To switch to the corresponding model run: +Switch back to the Livepatch model: -```sh +```bash juju switch livepatch-demo-controller ``` -To be able to consume the application offer we created in the previous step, we need to call `juju consume` command: +Consume the application offer and integrate it with the Livepatch application: -```sh +```bash juju consume pro-demo-controller:pro.pro-offer -``` - -Now the application offer is ready to be integrated with: - -```sh juju integrate livepatch pro-offer ``` -When the integration is done, the status message on the `livepatch` application will change to *"url-template not set"*. This is about the URL template that the Livepatch clients can use to download the patch files. - -To configure the URL template you can use the command below: +When the integration completes, the status message on the `livepatch` application changes to *"url-template not set"*. Configure the URL template: -```sh +```bash juju config livepatch server.url-template="http://livepatch.test.com/v1/patches/{filename}" ``` ```{note} -The `{filename}` placeholder should not be omitted or replaced. +The `{filename}` placeholder must not be omitted or replaced. Livepatch replaces it with the actual file name at runtime. ``` -After some time, the Livepatch server should be up and running. You can see this in the Juju model status as the `livepatch` application status changes to `active`. To test the running Livepatch on-prem server we can use `curl` like this: +After a short time, the Livepatch application status should change to `active`. Verify the server is running: -```sh +```bash curl http://livepatch.test.com -Canonical Livepatch Health service, version v1.14.3 +# Canonical Livepatch Health service, version v1.14.3 ``` -At this point, our Livepatch on-prem server is operating in airgapped mode and there is no communication with the upstream Livepatch server. The next step is to set up Livepatch clients to speak with our on-prem server. +Your Livepatch on-prem server is now operating in airgapped mode, with no communication to the upstream Livepatch Server. -### Step 7: Set up Livepatch client +## Set up the Livepatch Client -In a real-world scenario, Livepatch clients run on different machines than those serving the Livepatch on-prem server. Since network configuration is out of the scope of this tutorial, we reuse the VM we have used so far, to install and configure the Livepatch client. +In a real-world scenario, Livepatch Clients run on separate machines. For this tutorial, you'll reuse the same VM to install and configure a client. -Before proceeding with the Livepatch client, we should first instruct the Ubuntu Pro client on the machine to communicate with the `pro-airgapped-server` we deployed on an LXD model. To do this replace the `` placeholder in the command below with the IP of the `pro-airgapped-server` you copied in Step 5, and run the command: +Configure the Ubuntu Pro client to communicate with the airgapped Ubuntu Pro server. Replace `` with the address of the `pro-airgapped-server` unit you noted earlier: -```sh +```bash sudo sed -i -e 's|contract_url:.*|contract_url: http://:8484|g' /etc/ubuntu-advantage/uaclient.conf ``` -You should also instruct the Ubuntu Pro client to refresh its internal state: +Refresh the Ubuntu Pro client's internal state: -```sh +```bash sudo pro refresh ``` -With Ubuntu Pro client being configured, we are ready to install the Livepatch client: +Install the Livepatch Client: -```sh +```bash sudo snap install canonical-livepatch ``` -By default, the Livepatch client is configured to communicate with the upstream Livepatch server. We need to change it so that the client speaks to our Livepatch on-prem server: +Configure the Livepatch Client to communicate with your on-prem server instead of the upstream service: -```sh +```bash sudo canonical-livepatch config remote-server='http://livepatch.test.com' ``` -Next, is to call `pro attach` and provide it with your Ubuntu Pro subscription token. You have already used the same token when configuring the `pro-airgapped-server`. Replace the `` placeholder below with the same token and run the command: +Attach your Ubuntu Pro subscription. Replace `` with your Ubuntu Pro token: -```sh +```bash sudo pro attach ``` -This might fail because we did not fully set up the `pro-airgapped-server` (e.g., apt repository mirrors). But for our purposes, it is okay and we can continue with enabling Livepatch: +```{note} +`pro attach` may fail if the airgapped Ubuntu Pro server is not fully configured (for example, without apt repository mirrors). This is expected for the purposes of this tutorial. +``` + +Enable Livepatch: -```sh +```bash sudo pro enable livepatch ``` -This should finish successfully. We can now check the status of the Livepatch client by running the following command: +Verify the Livepatch Client status: -```sh +```bash sudo canonical-livepatch status +``` + +The output confirms that the client is communicating with your airgapped Livepatch on-prem server: + +```text last check: 19 seconds ago kernel: 5.15.0-119.129-generic server check-in: succeeded ``` -At this point, our Livepatch client is talking to our airgapped Livepatch on-prem server. +## Managing patches in an airgapped environment -## Cleaning up +By default, Livepatch on-prem uses the filesystem to store patches at `/var/snap/canonical-livepatch-server/common/patches`. To provide patches to the airgapped server, use the Patch Downloader tool on an Internet-connected machine to download the latest patches, transfer them to the patch storage path, then use the admin tool to refresh the patch information. -Since we used Multipass for this tutorial, we only need to delete the created instance: +See the [Patch Downloader usage guide](/server/how-to-guides/patch-management/use-the-patch-downloader-tool) for instructions on downloading patches, and the [patch storage reference](/server/reference/patch-storage/index) for information on configuring alternative storage backends. -```sh +## Cleanup + +Delete the Multipass VM: + +```bash multipass stop livepatch-deploy multipass delete --purge livepatch-deploy ``` ## Summary -In this tutorial, we deployed an airgapped Livepatch on-prem server, alongside an Ubuntu Pro server enabling airgapped operations. Then, we configured the Ubuntu Pro client and Livepatch client to communicate with our airgapped servers. +In this tutorial, you deployed an airgapped Livepatch on-prem server on MicroK8s alongside an airgapped Ubuntu Pro server, integrated the two services, and configured a Livepatch Client to communicate with the airgapped servers. The on-prem server now operates without direct communication to the upstream Livepatch service. + +From here, you have several options: +- **Download and transfer patches**: Use the Patch Downloader tool to provide patches to your airgapped server. See the [Patch Downloader usage guide](/server/how-to-guides/patch-management/use-the-patch-downloader-tool). +- **Configure patch storage**: Set up an S3 or Swift bucket for patch storage in the airgapped environment. See the [patch storage reference](/server/reference/patch-storage/index). +- **Explore the Snap-based deployment**: Deploy airgapped Livepatch on-prem using Snaps instead. See the [airgapped Livepatch and Snap tutorial](/server/tutorial/airgapped-livepatch-and-snap). +- **Get support**: Canonical customers can receive support through the [Canonical support portal](https://portal.support.canonical.com/). \ No newline at end of file diff --git a/docs/server/tutorial/airgapped-livepatch-and-snap.md b/docs/server/tutorial/airgapped-livepatch-and-snap.md index f97c095..a53f5fa 100644 --- a/docs/server/tutorial/airgapped-livepatch-and-snap.md +++ b/docs/server/tutorial/airgapped-livepatch-and-snap.md @@ -1,70 +1,79 @@ --- myst: html_meta: - description: "Tutorial: Air-gapped Livepatch and Snap - hands-on introduction to Livepatch on-prem." + description: "Complete a hands-on tutorial for airgapped Livepatch on-prem using Snaps. Deploy Livepatch and an airgapped Ubuntu Pro server in about 45 minutes." --- (server-tutorial-airgapped-livepatch-and-snap)= -# Airgapped Livepatch and Snap +# Getting started with airgapped Livepatch on-prem and Snaps -## Introduction +> See also: {ref}`server` -Livepatch on-prem is a self-hosted version of the Livepatch server, enabling the delivery of patches to machines within network restricted environments. For security reasons, administrators may prefer to deploy Livepatch on-prem server in an airgapped environment with restricted Internet access. +This tutorial guides you through the process of deploying Livepatch on-prem in an airgapped environment using Snap packages. Livepatch on-prem enables the delivery of kernel patches to machines within network-restricted environments. For organisations with strict security requirements, deploying Livepatch on-prem in an airgapped setup ensures that the server operates without direct communication to the upstream Livepatch service. -This tutorial will deploy the Livepatch on-prem server as a Snap package in an airgapped environment. +In an airgapped environment, two additional tools replace the server's direct connection to Canonical's hosted Livepatch service: -### How does Livepatch on-prem work in an airgapped environment? - -Generally, in order to perform authentication/authorisation of machines and to fetch patches, the Livepatch on-prem server needs to communicate with the main Livepatch server hosted by Canonical. In an airgapped environment, where such communication is not available, these functions are handled using the following tools: - -- [**Airgapped Ubuntu Pro Server**](https://discourse.charmhub.io/t/15278) provides services related to Ubuntu Pro subscriptions in airgapped environments. Livepatch on-prem can be integrated with this service to perform authentication/authorisation of machines and handle subscription-related functionality. -- [**Patch Downloader**](https://snapcraft.io/canonical-livepatch-downloader) is a CLI tool that can be used to download the latest patch files from the Livepatch server. In an airgapped setup, the administrators of Livepatch on-prem should use this tool to fetch the latest patches and then upload them to the configured patch storage. You can check out [this](/server/reference/patch-storage/index) topic on how to configure various types of storage for Livepatch on-prem. [This](/server/how-to-guides/patch-management/use-the-patch-downloader-tool) topic explains how to use the Patch Downloader tool to fetch patches. +- The **airgapped Ubuntu Pro server** provides Ubuntu Pro subscription services, including machine authentication and authorisation, without requiring Internet access. +- The **Patch Downloader** is a CLI tool for downloading the latest patch files from the upstream Livepatch Server. Administrators use this tool on an Internet-connected machine, then transfer the downloaded patches to the airgapped patch storage. ```{note} -When deploying airgapped Livepatch on-prem using Snap, it is best to configure the patch storage to something independently accessible within your infrastructure, like the filesystem or an S3/Swift bucket, instead of PostgreSQL. This way, Livepatch administrators can independently download the latest patches via the Patch Downloader CLI tool and transfer them to the patch storage. +When deploying airgapped Livepatch on-prem using Snaps, configure the patch storage to use an independently accessible option such as the filesystem or an S3/Swift bucket instead of PostgreSQL. This allows administrators to download patches with the Patch Downloader tool and transfer them independently to the patch storage. ``` -## Deployment steps +Completing this tutorial should take approximately 45 minutes. + +## Prerequisites + +Before starting this tutorial, you'll need the following tools and resources. + +### Ubuntu Pro token + +You'll need an [Ubuntu Pro token](https://ubuntu.com/pro). Ubuntu Pro is free for up to five machines. -In this tutorial, we use [Multipass](https://multipass.run) to create Ubuntu virtual machines (VM) to deploy Livepatch and its dependencies on it. +If you already have an Ubuntu Pro account, copy your token from the [Ubuntu Pro dashboard](https://ubuntu.com/pro/dashboard). If you don't have an account, sign up for a [free personal Ubuntu Pro account](https://ubuntu.com/pro), then copy your token. -If not already installed, we can use the command below to install Multipass: +### Multipass -```sh +Multipass is a CLI tool for launching Ubuntu VMs from Windows, Linux, and macOS. + +Install Multipass from the Snap Store: + +```bash sudo snap install multipass ``` -Also, we will need two Multipass virtual machines; one as the airgapped environment where the Livepatch on-prem server is going to be deployed, and the other to simulate a normal environment (i.e., with access to the Internet) to finalize the configurations for the airgapped Ubuntu Pro server. +## Create the Multipass instances -### Step 1: Create Multipass instances +This tutorial uses two Multipass VMs: -You can create the Multipass instances needed in this tutorial by running the command below. This will create two instances, named `pro-configuration` and `livepatch-deploy`. +- `pro-configuration` -- an Internet-connected VM used to generate the airgapped Ubuntu Pro server configuration. +- `livepatch-deploy` -- the isolated VM representing your airgapped environment where the Livepatch on-prem server is deployed. -```sh +```bash multipass launch jammy --name pro-configuration multipass launch jammy --name livepatch-deploy -d 10G ``` -### Step 2: Create configurations for the airgapped Ubuntu Pro server +## Generate the airgapped Ubuntu Pro server configuration -We first need an interactive shell in the `pro-configuration` instance: +Open an interactive shell on the `pro-configuration` instance: -```sh +```bash multipass shell pro-configuration ``` -Once getting into the instance, we need to install the `pro-airgapped` configuration tool: +Install the `pro-airgapped` configuration tool: -```sh +```bash sudo add-apt-repository ppa:yellow/ua-airgapped sudo apt update sudo apt install pro-airgapped ``` -To create the configuration file, you will need your Ubuntu Pro subscription token. You should copy your token from the Ubuntu Pro [dashboard](https://ubuntu.com/pro/dashboard), replace the `` placeholder in the following command, and then run the command: +Create a configuration override file with your Ubuntu Pro token. Replace `` with your token. Set the `remoteServer` value to the hostname you intend to use for your Livepatch on-prem server: -```sh +```bash cat < override.yml : livepatch: @@ -77,70 +86,68 @@ EOF ``` ```{note} -Here we have set the Livepatch on-prem server hostname to `livepatch.test.com`. You can set it to any other value, but remember to replace it in the next steps. +The hostname `livepatch.test.com` is used throughout this tutorial. You can substitute a different hostname, but remember to use it consistently in all subsequent steps. ``` -This will create a file named `override.yml`. Now, we should use the `pro-airgapped` tool to make the final configuration file, which we will use to set up the airgapped environment. Note that the `pro-airgapped` tool needs Internet access to communicate with upstream Canonical services to fetch your subscription details. By running the following command the final configuration file will be created as `server-ready.yml`: +The `pro-airgapped` tool requires Internet access to communicate with upstream Canonical services and fetch your subscription details. Run the following to generate the final configuration file (`server-ready.yml`): -```sh +```bash cat override.yml | pro-airgapped > server-ready.yml ``` -Now, we are done with this Multipass instance, and we should exit the interactive shell: +Exit the `pro-configuration` instance: -```sh +```bash exit ``` -### Step 3: Transfer configuration to airgapped environment +## Transfer the configuration to the airgapped environment -Now, we need to transfer the airgapped Ubuntu Pro configuration file, `server-ready.yml`, to the isolated Multipass instance. To do this, we have to transfer the file to the host machine and then to the isolated instance. +Transfer the `server-ready.yml` file from `pro-configuration` to your host machine, then to the isolated `livepatch-deploy` instance: -```sh -mulitpass transfer pro-configuration:server-ready.yml /tmp/server-ready.yml +```bash +multipass transfer pro-configuration:server-ready.yml /tmp/server-ready.yml multipass transfer /tmp/server-ready.yml livepatch-deploy:server-ready.yml rm /tmp/server-ready.yml ``` -### Step 4: Deploy airgapped Ubuntu Pro server +## Deploy the airgapped Ubuntu Pro server -Now it is time to deploy the airgapped Ubuntu Pro server in the airgapped environment. To begin, we need an interactive shell in the isolated Multipass instance: +Open an interactive shell on the `livepatch-deploy` instance: -```sh +```bash multipass shell livepatch-deploy ``` -Next step is installing `contracts-airgapped` tool. +Install the `contracts-airgapped` tool: -```sh +```bash sudo add-apt-repository ppa:yellow/ua-airgapped sudo apt update sudo apt install contracts-airgapped ``` ```{note} -In a real airgapped environment there will be no Internet access. So, one should use other methods, like local mirrors/packages, to install the dependencies via `apt` or `snap`. Setting up a fully isolated airgapped environment is out of the scope of this tutorial. So, we simply install dependencies from the Internet. +In a real airgapped environment there is no Internet access. In that case, you must use local mirrors or packages to install dependencies via `apt` or `snap`. Setting up a fully isolated airgapped environment is outside the scope of this tutorial, so dependencies are installed directly from the Internet for simplicity. ``` -Once the installation is done, we need to run the airgapped Ubuntu Pro server with the configuration file we transferred to the instance in the previous step: +Run the airgapped Ubuntu Pro server with the configuration file you transferred: -```sh +```bash contracts-airgapped --input=./server-ready.yml ``` -The airgapped Ubuntu Pro server is now listening on TCP port `8484`. +The server starts listening on TCP port `8484`. This command runs in the foreground. Open a second shell to the `livepatch-deploy` instance, or run it in the background by appending `&`: -```{note} -This command runs the airgapped Ubuntu Pro server in the foreground. We still need to work on this Multipass instance. So, you can either open a new shell to the instance or run it in the background by appending a `&` to the command. +```bash +contracts-airgapped --input=./server-ready.yml & ``` -### Step 5: Deploy Livepatch on-prem server +## Deploy Livepatch on-prem -We should now deploy Livepatch on-prem server in the airgapped environment. For simplicity, we will reuse the same Multipass instance we used for running the airgapped Ubuntu Pro server. +Livepatch on-prem requires a PostgreSQL database. Install Docker Engine and create a PostgreSQL container. Follow the [Docker Engine installation instructions for Ubuntu](https://docs.docker.com/engine/install/ubuntu/), then run: -Livepatch on-prem requires a PostgreSQL database to work. Here, we use Docker Engine to spin up a PostgreSQL instance. Since the Multipass instance we are in does not have Docker, you need to install it by following the official [instructions](https://docs.docker.com/engine/install/ubuntu/). Once Docker Engine is installed, you can create a PostgreSQL container by using this command: - -```sh +```bash docker run \ --name postgresql \ -e POSTGRES_USER=livepatch \ @@ -150,108 +157,117 @@ docker run \ ``` ```{note} -Livepatch on-prem server requires PostgreSQL 12 or above. +Livepatch on-prem requires PostgreSQL 12 or above. ``` -Now, we are ready to install Livepatch on-prem server: +Install the Livepatch on-prem server snap: -```sh +```bash sudo snap install canonical-livepatch-server ``` -Before configuring Livepatch on-prem to communicate with our PostgreSQL database, we need to prepare the database: +Prepare the database schema: -```sh +```bash canonical-livepatch-server.schema-tool postgresql://livepatch:testing@localhost:5432/livepatch ``` -Once the database preparation is done, we can configure Livepatch on-prem database connection by the following command: +Configure the database connection: -```sh +```bash sudo snap set canonical-livepatch-server lp.database.connection-string=postgresql://livepatch:testing@localhost:5432/livepatch ``` -Next, the Livepatch on-prem server should be configured to communicate with the airgapped Ubuntu Pro server: +Configure Livepatch on-prem to communicate with the airgapped Ubuntu Pro server: -```sh +```bash sudo snap set canonical-livepatch-server \ lp.contracts.enabled=true \ lp.contracts.url=http://127.0.0.1:8484 ``` -Now, the Livepatch on-prem server is running and listening on TCP port `8080`. To test it, you can use `curl` like this: +The Livepatch on-prem server is now running and listening on TCP port `8080`. Verify it is operational: -```sh +```bash curl http://localhost:8080 # Canonical Livepatch Health service, version v1.14.3 ``` -```{note} -By default, Livepatch on-prem server uses filesystem to stores the patches. The directory is located at `/var/snap/canonical-livepatch-server/common/patches`. So, in a real-world setup, you can download the latest patches by using the Patch Downloader tool, transfer them to the mentioned path, and use the Admin tool to refresh patch information. Check out [this](/server/how-to-guides/patch-management/use-the-patch-downloader-tool) topic on how to use the Patch Downloader tool. -``` - -### Step 7: Set up Livepatch client +## Set up the Livepatch Client -In a real-world scenario, Livepatch clients run on different machines than those serving the Livepatch on-prem server. Since network configuration is out of the scope of this tutorial, we reuse the VM we have used so far, to install and configure the Livepatch client. +In a real-world scenario, Livepatch Clients run on separate machines. For this tutorial, you'll reuse the same VM. -Before proceeding with the Livepatch client, we should first instruct the Ubuntu Pro client on the machine to communicate with the airgapped Ubuntu Pro server: +Configure the Ubuntu Pro client to communicate with the airgapped Ubuntu Pro server: -```sh +```bash sudo sed -i -e 's|contract_url:.*|contract_url: http://127.0.0.1:8484|g' /etc/ubuntu-advantage/uaclient.conf ``` -You should also instruct the Ubuntu Pro client to refresh its internal state for changes to take effect: +Refresh the Ubuntu Pro client's internal state: -```sh +```bash sudo pro refresh ``` -More than that, we still need to map `livepatch.test.com` to the loopback interface IP address (i.e., `127.0.0.1`): +Map the Livepatch on-prem hostname to the loopback address: -```sh +```bash echo "127.0.0.1 livepatch.test.com" | sudo tee -a /etc/hosts ``` -With Ubuntu Pro client being configured, we are ready to install the Livepatch client: +Install the Livepatch Client: -```sh +```bash sudo snap install canonical-livepatch ``` -By default, the Livepatch client is configured to communicate with the upstream Livepatch server. We need to change it so that the client speaks to our Livepatch on-prem server: +Configure the Livepatch Client to communicate with your on-prem server instead of the upstream service: -```sh +```bash sudo canonical-livepatch config remote-server='http://livepatch.test.com' ``` -Next, is to call `pro attach` and provide it with your Ubuntu Pro subscription token. You have already used the same token in an earlier step. Replace the `` placeholder below with the same token and run the command: +Attach your Ubuntu Pro subscription. Replace `` with your Ubuntu Pro token: -```sh +```bash sudo pro attach ``` -This might fail because we did not fully set up the airgapped Ubuntu Pro server (e.g., apt repository mirrors). But for our purposes, it is okay and we can continue with enabling Livepatch: +```{note} +`pro attach` may fail if the airgapped Ubuntu Pro server is not fully configured (for example, without apt repository mirrors). This is expected for the purposes of this tutorial. +``` + +Enable Livepatch: -```sh +```bash sudo pro enable livepatch ``` -This should finish successfully. We can now check the status of the Livepatch client by running the following command: +Verify the Livepatch Client status: -```sh +```bash sudo canonical-livepatch status +``` + +The output confirms that the client is communicating with your airgapped Livepatch on-prem server: + +```text last check: 19 seconds ago kernel: 5.15.0-119.129-generic server check-in: succeeded ``` -At this point, our Livepatch client is talking to our airgapped Livepatch on-prem server. +## Managing patches in an airgapped environment + +By default, Livepatch on-prem stores patches on the filesystem at `/var/snap/canonical-livepatch-server/common/patches`. To provide patches to the airgapped server, use the Patch Downloader tool on an Internet-connected machine to download the latest patches, transfer them to the patch storage path, then use the admin tool to refresh the patch information. -## Cleaning up +See the [Patch Downloader usage guide](/server/how-to-guides/patch-management/use-the-patch-downloader-tool) for instructions on downloading patches, and the [patch storage reference](/server/reference/patch-storage/index) for information on configuring alternative storage backends. -Since we used Multipass for this tutorial, we just need to delete the created instances: +## Cleanup -```sh +Delete the Multipass VMs: + +```bash multipass stop pro-configuration multipass delete --purge pro-configuration multipass stop livepatch-deploy @@ -260,5 +276,11 @@ multipass delete --purge livepatch-deploy ## Summary -In this tutorial, we deployed an airgapped Livepatch on-prem server, alongside an Ubuntu Pro server enabling airgapped operations. Then, we configured the Ubuntu Pro client and Livepatch client to communicate with our airgapped servers. +In this tutorial, you deployed an airgapped Livepatch on-prem server alongside an airgapped Ubuntu Pro server using Snap packages and Docker, integrated the two services, and configured a Livepatch Client to communicate with the airgapped servers. The on-prem server now operates without direct communication to the upstream Livepatch service. + +From here, you have several options: +- **Download and transfer patches**: Use the Patch Downloader tool to provide patches to your airgapped server. See the [Patch Downloader usage guide](/server/how-to-guides/patch-management/use-the-patch-downloader-tool). +- **Configure patch storage**: Set up an S3 or Swift bucket for patch storage in the airgapped environment. See the [patch storage reference](/server/reference/patch-storage/index). +- **Explore the MicroK8s deployment**: Deploy airgapped Livepatch on-prem on MicroK8s instead. See the [airgapped Livepatch and MicroK8s tutorial](/server/tutorial/airgapped-livepatch-and-microk8s). +- **Get support**: Canonical customers can receive support through the [Canonical support portal](https://portal.support.canonical.com/). \ No newline at end of file diff --git a/docs/server/tutorial/index.md b/docs/server/tutorial/index.md index 999ac27..70daefe 100644 --- a/docs/server/tutorial/index.md +++ b/docs/server/tutorial/index.md @@ -1,23 +1,22 @@ --- myst: html_meta: - description: "Tutorial: Tutorial - hands-on introduction to Livepatch on-prem." + description: "Tutorials for Livepatch on-prem. Hands-on introduction to deploying Livepatch Server in various environments." --- - (server-tutorial)= # Tutorial -A hands-on introduction for Livepatch on-prem server for new users: +A hands-on introduction to Livepatch on-prem for new users: -- [Getting started with Livepatch On-Prem and LXD](/server/tutorial/livepatch-and-lxd.md) -- [Getting started with Livepatch On-Prem and MicroK8s](/server/tutorial/livepatch-and-microk8s.md) +- [Getting started with Livepatch on-prem and LXD](/server/tutorial/livepatch-and-lxd) +- [Getting started with Livepatch on-prem and MicroK8s](/server/tutorial/livepatch-and-microk8s) Setting up Livepatch in an airgapped environment: -- [Getting started with Airgapped Livepatch On-Prem on MicroK8s](/server/tutorial/airgapped-livepatch-and-microk8s.md) -- [Getting started with airgapped Livepatch On-Prem using Snaps ](/server/tutorial/airgapped-livepatch-and-snap.md) +- [Getting started with airgapped Livepatch on-prem on MicroK8s](/server/tutorial/airgapped-livepatch-and-microk8s) +- [Getting started with airgapped Livepatch on-prem using Snaps](/server/tutorial/airgapped-livepatch-and-snap) ```{toctree} :titlesonly: @@ -25,8 +24,8 @@ Setting up Livepatch in an airgapped environment: :glob: :hidden: -Livepatch and lxd -Livepatch and microk8s -Airgapped livepatch and microk8s -Airgapped livepatch and snap -``` +Livepatch and LXD +Livepatch and MicroK8s +Airgapped Livepatch and MicroK8s +Airgapped Livepatch and Snap +``` \ No newline at end of file diff --git a/docs/server/tutorial/livepatch-and-lxd.md b/docs/server/tutorial/livepatch-and-lxd.md index a715f39..3efc3ee 100644 --- a/docs/server/tutorial/livepatch-and-lxd.md +++ b/docs/server/tutorial/livepatch-and-lxd.md @@ -1,287 +1,268 @@ --- myst: html_meta: - description: "Tutorial: Livepatch and LXD - hands-on introduction to Livepatch on-prem." + description: "Complete a hands-on tutorial for Livepatch on-prem. Deploy Livepatch Server using LXD and Juju, configure authentication, and sync patches in about 30 minutes." --- - (server-tutorial-livepatch-and-lxd)= -# Livepatch and LXD - -## Introduction +# Getting started with Livepatch on-prem and LXD -In this tutorial we will deploy and configure the Livepatch on-premise server using LXD as our cloud provider. +> See also: {ref}`server` -We will be using LXD, Juju and the Livepatch server machine charm/bundle. +This tutorial guides you through the process of deploying Livepatch on-prem using LXD as your cloud provider. You'll bootstrap a Juju controller, deploy the Livepatch Server bundle, enable Ubuntu Pro, configure authentication, sync patches, and verify that the server is ready to serve clients. -For this how-to, you do not require any previous or advanced knowledge of [LXD](https://ubuntu.com/lxd/), [Juju](https://canonical.com/juju) or [Charmed Operators](https://documentation.ubuntu.com/juju/latest/reference/charm/) to proceed and deploy Livepatch on-premise. +Completing this tutorial should take approximately 30 minutes. -If you’ve already deployed Livepatch before, and wish to keep your same configuration, we’ve rewritten our machine charm and the configuration has changed. Please see [here](/server/how-to-guides/deployment/migrate-from-reactive-charm-to-operator-charm.md) for instructions on how to migrate. +## Prerequisites -### JQ - -JQ is a JSON processor, and we’ll use it within this tutorial to extract some values for later use. Install it like so: - -``` -sudo apt update -sudo apt install jq -``` +Before starting this tutorial, you'll need the following tools installed on your host machine. ### LXD -LXD provides a unified user experience for managing system containers and virtual machines. And in this how-to, Juju will utilise LXD to spawn containers for the Livepatch on-premise services. +LXD provides a unified experience for managing system containers and virtual machines. Juju uses LXD to spawn containers for the Livepatch on-prem services. -LXD can be installed locally via a [snap](https://snapcraft.io/lxd). To install LXD, run: +Install LXD from the Snap Store: -``` +```bash sudo snap install lxd --channel=5.0/stable ``` -Next, LXD must be initialised, run the following command and either accept the defaults or choose different options when prompted (you may also use the –auto flag): +Initialise LXD using the `--auto` flag to accept the defaults: -``` +```bash lxd init --auto ``` ### Juju -Juju is an open source orchestration engine for software operators that enables the deployment, integration and lifecycle management of applications at any scale, on any infrastructure using charms. +Juju is an open source orchestration engine for software operators that enables the deployment, integration, and lifecycle management of applications at any scale, on any infrastructure. -Juju can be installed locally via a [snap](https://snapcraft.io/juju). To install Juju, run: +Install Juju from the Snap Store: -``` +```bash sudo snap install juju ``` -### Ubuntu Pro +### JQ -Livepatch on-premise requires authorisation to the upstream hosted Livepatch by Canonical via the use of [Ubuntu Pro](https://ubuntu.com/pro) tokens. To retrieve your Ubuntu Pro token please go [here](https://ubuntu.com/pro/dashboard) and save your token for later use. +JQ is a lightweight JSON processor. You'll use it to extract values from Juju's output during this tutorial. -## Deployment Steps +```bash +sudo apt update && sudo apt install jq +``` -### 1. Initialise Juju +### Ubuntu Pro token -Let us bootstrap a controller on LXD: +Livepatch on-prem requires authorisation to the upstream Livepatch service hosted by Canonical. You'll need an [Ubuntu Pro token](https://ubuntu.com/pro) to enable Livepatch. Ubuntu Pro is free for up to five machines. -``` +If you already have an Ubuntu Pro account, copy your token from the [Ubuntu Pro dashboard](https://ubuntu.com/pro/dashboard). If you don't have an account, sign up for a [free personal Ubuntu Pro account](https://ubuntu.com/pro), then copy your token. + +## Bootstrap Juju + +Create a Juju controller on LXD: + +```bash mkdir -p ~/.local/share juju bootstrap lxd livepatch-onprem ``` -After some time the controller should be ready. -Next, we’ll create a model to deploy Livepatch. +The bootstrap operation takes a few moments to complete. Once finished, create a model to host the Livepatch deployment: -``` +```bash juju add-model livepatch ``` -### 2. Deploying the bundle +Verify that you're working in the correct model: -Ensure you’re on the livepatch model: - -``` +```bash juju switch livepatch ``` -And deploy the bundle: +## Deploy Livepatch on-prem -``` +Deploy the Livepatch on-prem bundle from Charmhub: + +```bash juju deploy canonical-livepatch-onprem --channel=machine ``` -You can watch the status of the deployment: +Monitor the deployment progress with: -``` +```bash juju status --watch 2s ``` -After some time, your model will resemble the following: +After some time, the model status will show all applications initialising and eventually settling into a stable state. -![image|800x247](/_static/images/171JtDxiYZSynZfd2wsTaa2j0IH.png) +> See also: If you're migrating from the reactive charm to the operator charm, refer to the [migration guide](/server/how-to-guides/deployment/migrate-from-reactive-charm-to-operator-charm). -You’ve successfully deployed Livepatch! But it requires a few more steps to get up and running. +## Enable Ubuntu Pro (optional) -### 3. Enabling Ubuntu Pro (Optional) +Enable Ubuntu Pro on the deployed machines for Expanded Security Maintenance (ESM). Replace `` with your Ubuntu Pro token: -We will enable Ubuntu Pro on the machines for ESM (Expanded Security Maintenance). -Using your token from https://ubuntu.com/pro run: - -``` +```bash juju config ubuntu-advantage token='' ``` -On a successful attach, you will see something similar to the follow in your status output: +On a successful attach, the status output will reflect the change. -![Screenshot from 2024-10-15 14-11-55|800x248](/_static/images/x3Tl6GdMdzkEh5Q8qyXnRosGsvN.png) +If you're not using Ubuntu Pro, remove the `ubuntu-advantage` application: -If you are not using Ubuntu Pro, you can remove the `ubuntu-advantage` charm. - -``` +```bash juju remove-application ubuntu-advantage ``` -### 4. Enabling Livepatch +## Enable Livepatch -Next, to enable Livepatch on-prem, we’ll run: +Enable Livepatch by providing your Ubuntu Pro token to the Livepatch Server unit: -``` +```bash juju run livepatch/0 enable token='' ``` -You will see the following action output if successful: - -![|581x200](/_static/images/LNe8mLyugCYQ9BU7qWfVfXTdqzDr.png) - -Livepatch is now enabled! In the next segment, we’ll configure the Livepatch server. - -### 5. Configuring Livepatch +A successful action returns an output confirming that Livepatch is enabled. -#### URL Template +## Configure the Livepatch Server -We’ll need to configure a charm config option called `server.url-template`. +### Set the URL template -The URL template specifies the URL where patch files can be downloaded by Livepatch clients. - -In an on-premise environment, this could be the server itself or any file server you have with patches ready to be served. - -The URL template resembles the following: +The `server.url-template` option specifies the URL where Livepatch Clients download patch files. The template must include the `{filename}` placeholder, which Livepatch replaces with the actual file name at runtime: ``` http(s)://domain/{filename} ``` -The {filename} segment is a special variable which Livepatch will insert file names as-is to. - -```{note} -Using an AWS S3 bucket is one option for patch storage. -To redirect clients for patch downloads your URL template may resemble -``https://s3-eu-west-2.amazonaws.com/livepatch/patches/{filename}`` -``` - -For this tutorial, we’ll use the server itself to server patches. The Livepatch server has a special endpoint for serving patches at: +For this tutorial, you'll use the Livepatch Server itself to serve patches. The server exposes a dedicated endpoint at: ``` /v1/patches/:patch_name ``` -To reach the server, we recommend going through HAProxy that is included in the bundle. HAProxy will act as a load-balancer, allowing you to scale the number of Livepatch server machines. - -You may use a DNS pointing to your HAProxy or as we will do here to test your deployment, you can use an address from one of your HAProxy units. Run: +The bundle includes HAProxy, which acts as a load balancer and reverse proxy. Use the HAProxy unit's address to construct the URL template. Run the following to set it automatically: -``` +```bash HAPROXY_ADDRESS=$(juju status --format json | jq -r '.applications.haproxy.units["haproxy/0"]["public-address"]') && echo $HAPROXY_ADDRESS -juju config livepatch server.url-template="http:/$HAPROXY_ADDRESS/v1/patches/{filename}" +juju config livepatch server.url-template="http://$HAPROXY_ADDRESS/v1/patches/{filename}" ``` -You can confirm this was successful by running: +Confirm the configuration was applied: -``` +```bash juju config livepatch server.url-template ``` -#### Database Migration - -For the final configuration step, we will trigger a database schema migration using a charm action: - -``` -juju run livepatch/0 schema-upgrade +```{note} +For production deployments, you may use an AWS S3 bucket or another file server for patch storage. In that case, your URL template might resemble `https://s3-eu-west-2.amazonaws.com/livepatch/patches/{filename}`. ``` -The output will look like: - -![|624x105](/_static/images/hrgPWFzMb6tCKLeLRhfvM5itvV.png) +### Run the database schema migration -And Livepatch will enter a running state: +Trigger a database schema migration on the Livepatch Server unit: -![Screenshot from 2024-10-15 14-15-54|800x248](/_static/images/vZ0aOUtzlc1FqpDVVVN4CLs5527.png) - -Note that the schema migration only needs to be run once. On future upgrades it will be run automatically. +```bash +juju run livepatch/0 schema-upgrade +``` -The server is now ready to serve patches! +This operation only needs to be run once. Future upgrades will apply schema migrations automatically. Once completed, the Livepatch application will enter a running state. -#### Authorisation and Authentication +## Set up administrator authentication -In order to manage this Livepatch on-premise deployment we need to setup admin authentication. This can be done with the following steps. +Administrator access to the Livepatch on-prem deployment requires setting up basic authentication. -Enable basic authentication: +Enable basic authentication on the Livepatch application: -``` +```bash juju config livepatch auth.basic.enabled=true ``` -Install the following for bcrypt utilities: +Install the `apache2-utils` package for `htpasswd`, which generates bcrypt password hashes: -``` +```bash sudo apt-get install apache2-utils -y ``` -Next, create a user and password: +Generate a username and password hash pair. Replace `admin` and `admin123` with your chosen credentials: -``` +```bash htpasswd -bnBC 10 admin admin123 -admin:$2y$10$jEmTFsxm7dpqxptch8u3UuilVbzzmT6HGTeu6kKMta5Gdqnj9cOHG ``` -Using the output verbatim, run (note the single quotes to escape special characters): +The output is a `username:hashed-password` pair. Use the output verbatim to configure Livepatch. Wrap the value in single quotes to escape special characters: +```bash +juju config livepatch auth.basic.users='admin:$2y$10$...' ``` -juju config livepatch auth.basic.users='admin:$2y$10$jEmTFsxm7dpqxptch8u3UuilVbzzmT6HGTeu6kKMta5Gdqnj9cOHG' -``` - -If you wish to add more users, this is a comma-separated list of user:passwords. -Now an administrator can login using the admin tool. +To add additional administrators, provide a comma-separated list of `user:password` pairs. -### 6. A brief introduction to the admin tool +## Configure the admin tool -Livepatch can be managed via our administrator tool. +The Livepatch administration tool allows you to manage the server from the command line. Install it from the Snap Store: -You can download the admin tool via snap [here](https://snapcraft.io/canonical-livepatch-server-admin). +```bash +sudo snap install canonical-livepatch-server-admin +``` -To make things a little easier, we’ll create an alias to access the tool via `livepatch-admin`: +Create a convenient alias: -``` +```bash sudo snap alias canonical-livepatch-server-admin.livepatch-admin livepatch-admin ``` -Next, we’ll export an environment variable called LIVEPATCH_URL. It must point at your DNS/HAProxy unit as discussed previously in this tutorial. +Export the Livepatch Server URL (pointing to the HAProxy address you retrieved earlier): -``` -export LIVEPATCH_URL=http://$HAPROXY_ADDRESS +```bash +export LIVEPATCH_URL="http://$HAPROXY_ADDRESS" ``` -Now, with one of your administrators, you can login: +Log in with one of your administrator credentials: -``` +```bash livepatch-admin login -a admin:admin123 ``` -The final step before attaching client machines to the server is to download patches from Canonical's hosted Livepatch server. +## Sync patches -Trigger a sync with: +Download patches from Canonical's hosted Livepatch Server to your on-prem instance: -``` +```bash livepatch-admin sync trigger --wait ``` -For further information on the admin tool, see [How to setup administration tool](/server/how-to-guides/security/setup-administration-tool.md). -Additionally, see how-to [configure patch sync filters](/server/reference/patch-management/patch-sync-filters.md) to limit what patches you download. +For more information on the admin tool, see the [administration tool setup guide](/server/how-to-guides/security/setup-administration-tool). To limit which patches are downloaded, see the [patch sync filters reference](/server/reference/patch-management/patch-sync-filters). -## Enabling machine status reporting +## Enable machine status reporting (optional) -Each livepatch on-prem instance can optionally send information about the status of the machines it's serving back to Canonical. Full details on what information is sent is available [here](/client/reference/networking/data-sent.md) +Each Livepatch on-prem instance can optionally send information about the status of the machines it serves back to Canonical. Full details on the data that is transmitted are available in the [data sent reference](/client/reference/networking/data-sent). -``` +Enable machine status reporting: + +```bash juju config livepatch patch-sync.send-machine-reports=true ``` -This can be disabled at any time by setting the flag to `false`. +Disable reporting at any time by setting the value to `false`: + +```bash +juju config livepatch patch-sync.send-machine-reports=false +``` -### 7. Cleaning up the deployment +## Cleanup -Should you wish to clean up your deployment, you can do so via: +When you're finished exploring Livepatch on-prem, destroy the Juju controller and all associated models: -``` +```bash juju destroy-controller livepatch-onprem --destroy-all-models ``` + +## Summary + +In this tutorial, you deployed Livepatch on-prem using LXD and Juju, configured the server to serve patches, set up administrator authentication, and synchronised patches from the upstream Livepatch service. Your Livepatch on-prem server is now ready to serve clients. + +From here, you have several options: + +- **Set up Livepatch Clients**: Install and configure the Livepatch Client on machines in your infrastructure. See the [Livepatch Client documentation](/client/index). +- **Configure patch sync filters**: Limit which patches are downloaded to your on-prem server. See the [patch sync filters reference](/server/reference/patch-management/patch-sync-filters). +- **Explore other deployment options**: Deploy Livepatch on-prem on MicroK8s instead. See the [Livepatch and MicroK8s tutorial](/server/tutorial/livepatch-and-microk8s). +- **Get support**: Canonical customers can receive support through the [Canonical support portal](https://portal.support.canonical.com/). \ No newline at end of file diff --git a/docs/server/tutorial/livepatch-and-microk8s.md b/docs/server/tutorial/livepatch-and-microk8s.md index 84c6e12..420bfa9 100644 --- a/docs/server/tutorial/livepatch-and-microk8s.md +++ b/docs/server/tutorial/livepatch-and-microk8s.md @@ -1,258 +1,324 @@ --- myst: html_meta: - description: "Tutorial: Livepatch and Microk8s - hands-on introduction to Livepatch on-prem." + description: "Complete a hands-on tutorial for Livepatch on-prem on Kubernetes. Deploy Livepatch Server using MicroK8s and Juju, configure authentication, and sync patches in about 45 minutes." --- (server-tutorial-getting-started-with-livepatch-on-prem-and-microk8s)= -# Getting started with Livepatch On-Prem and Microk8s +# Getting started with Livepatch on-prem and MicroK8s -## Introduction +> See also: {ref}`server` -Livepatch on-prem is a self-hosted version of the Livepatch server, enabling the delivery of patches to machines within network restricted environments. +This tutorial guides you through the process of deploying Livepatch on-prem as a Kubernetes application using MicroK8s and Juju. You'll bootstrap a Juju controller on MicroK8s, deploy the Livepatch Server bundle, configure the URL template and ingress, set up authentication, sync patches, and verify that the server is ready to serve clients. -This tutorial will deploy the Livepatch On-prem server as a Kubernetes application. We will deploy and configure the livepatch on-prem server using Juju and Charmed Operators. Juju is an Open Source Charmed Operator Framework that controls the whole lifecycle of an application. While this is one option for deploying the on-prem server, another is to deploy to virtual machines as described [here](/server/how-to-guides/deployment/deploy-via-juju.md). +Completing this tutorial should take approximately 45 minutes. -For this tutorial we will use Microk8s, a lightweight tool for creating a local Kubernetes cluster. +## Prerequisites -You don’t need to have previous or advanced knowledge of Juju or Charmed Operators to follow this guide and deploy livepatch. +Before starting this tutorial, you'll need the following tools and resources. -### Livepatch authorization token +### Ubuntu Pro token -Since on-prem livepatch servers act as caching proxies for the livepatch service hosted by Canonical, a subscription token is required to authorise the on-prem instance to pull patch information. +Livepatch on-prem requires a subscription token to authorise the on-prem instance to pull patch information from the upstream Livepatch service hosted by Canonical. -To get your Ubuntu Pro subscription token, please go to https://ubuntu.com/pro/dashboard, login to your Ubuntu SSO account and use your free personal token for the remainder of this guide. +If you already have an Ubuntu Pro account, copy your token from the [Ubuntu Pro dashboard](https://ubuntu.com/pro/dashboard). If you don't have an account, sign up for a [free personal Ubuntu Pro account](https://ubuntu.com/pro), then copy your token. -## Deployment Steps +### Multipass (optional) -### 1. (Optional) Setup Multipass environment +Multipass is a CLI tool for launching Ubuntu VMs from Windows, Linux, and macOS. You can run the remainder of this tutorial from within a Multipass VM to avoid affecting your host machine. -Multipass is a CLI tool to launch Ubuntu VMs from Windows, Linux and MacOS. The remainder of this guide can be run from within a multipass VM to avoid affecting the host machine. +Install Multipass from the Snap Store: -Start by running the following commands to install and start a Multipass VM, the optional section will define the VM’s memory/cpu/disk usage. - -``` +```bash sudo snap install multipass -multipass launch jammy --name livepatch-deploy [-m 12g -c 4 -d 40G] -multipass shell livepatch-deploy ``` -### 2. Initialize Juju and microk8s - -Now we can install our dependencies, note that Juju 3.1 only works with a strictly confined microk8s Snap. +Launch a VM with sufficient resources: +```bash +multipass launch jammy --name livepatch-deploy --cpus 4 --memory 12G --disk 40G ``` - sudo snap install microk8s --channel=1.25-strict/stable - sudo snap install juju --channel=3.1/stable + +Open an interactive shell into the VM: + +```bash +multipass shell livepatch-deploy ``` -Once you have the Juju CLI installed, you will need to bootstrap a Juju controller to your cloud (microk8s in this case). The [Juju documentation](https://documentation.ubuntu.com/juju/latest/tutorial/) has detailed instructions on how to do that for several clouds and machine types. +## Install and configure MicroK8s -To begin, +MicroK8s is a lightweight, CNCF-certified Kubernetes distribution. Install it from the Snap Store: +```bash +sudo snap install microk8s --channel=1.25-strict/stable ``` -# Add the 'ubuntu' user to the MicroK8s group: + +Add your user to the MicroK8s group and configure permissions: + +```bash sudo usermod -a -G snap_microk8s ubuntu -# Give the 'ubuntu' user permissions to read the ~/.kube directory: sudo chown -f -R ubuntu ~/.kube -# Create the 'microk8s' group: newgrp snap_microk8s -# Enable the necessary MicroK8s addons: +``` + +Enable the required MicroK8s addons: + +```bash sudo microk8s enable hostpath-storage dns ingress -# Set up a short alias for the Kubernetes CLI: +``` + +Create a short alias for the Kubernetes CLI: + +```bash sudo snap alias microk8s.kubectl kubectl ``` -Next, +## Install and bootstrap Juju +Install Juju from the Snap Store: + +```bash +sudo snap install juju --channel=3.1/stable ``` -# Since the Juju package is strictly confined, you also need to manually create a path: + +Create the local state directory and bootstrap a Juju controller on MicroK8s: + +```bash mkdir -p ~/.local/share juju bootstrap microk8s livepatch-demo-controller -juju add-model livepatch ``` -### 3. Deploying the bundle - -The bundle and charmed operators necessary to deploy livepatch server are available in the charmstore using the “k8s” track at +Create a model to host the Livepatch deployment: -https://charmhub.io/canonical-livepatch-onprem - -Livepatch On-Prem needs a place to store patches that it syncs from the upstream. By default the above "k8s" bundle will store patches in PostgreSQL directly. Other options including S3 storage are available and can be configured as described [here](/server/reference/patch-storage/index.md). +```bash +juju add-model livepatch +``` -In order to ensure PostgreSQL has enough space, see our [resources topic](/server/reference/platform/resource-requirements.md) for requirements on virtual machines running livepatch on-prem. Although this information relates to the deployment of Livepatch on virtual machines, the storage requirements remain similar. +## Deploy Livepatch on-prem -To start the deployment within the previously created juju model, run: +Deploy the Livepatch on-prem bundle from Charmhub. The bundle includes all the operators needed to run a working Livepatch on-prem server: -``` +```bash juju deploy canonical-livepatch-onprem --channel=k8s/stable --trust ``` -### 4. Configuring livepatch - -After the deployment completes, verify the status of the model by running: +Monitor the deployment progress: -``` +```bash juju status ``` -The output should look like the following while the applications are initialising: - -![|624x116](/_static/images/ym7r1pLvMBXCDSGgcVARsFDG3w9Po4z.png) - -After initialisation, the livepatch unit is expected to be in a blocked state with the message: +After initialisation, the Livepatch unit will enter a blocked state with the message: `"✘ patch-sync token not set, run get-resource-token action"` -Provide the token (acquired by following instructions in the Livepatch authorization token section) by running: +### Provide the patch-sync token -``` +Run the `get-resource-token` action with your Ubuntu Pro token to authorise the on-prem server. Replace `` with your Ubuntu Pro token: + +```bash juju run livepatch/leader get-resource-token contract-token= --wait 30s ``` -The output should indicate the token has successfully been acquired: +A successful action returns output confirming that the token has been acquired. -![|624x61](/_static/images/kdKRpt7Vxhsz1JKCNYoMEC9UjXj.png) +### Configure the patch storage -After that, provide the url_template setting as follows: +Livepatch on-prem needs a place to store patches synced from the upstream Livepatch service. By default, the bundle stores patches in PostgreSQL. Other storage options -- including S3 -- are available and can be configured at deploy time. See the [patch storage reference](/server/reference/patch-storage/index) for more information. -``` -juju config livepatch server.url-template="http://10.1.236.9:8080/v1/patches/{filename}" -``` +## Configure the Livepatch Server + +### Set the URL template -The url_template specifies the url where patch files can be downloaded by livepatch clients. The url template should be of the form 'http(s)://{HOSTNAME}/v1/patches/{filename}'. The hostname is the only part that needs to be changed. When using microk8s, all pods and services are exposed by default to the host so the hostname simplifies to the ip address of the livepatch-server unit (this is the pod’s IP address). This is useful for testing but not helpful in a production setup. You should now be able to curl the Livepatch pod with +The `server.url-template` option specifies the URL where Livepatch Clients download patch files. The template must include the `{filename}` placeholder, which Livepatch replaces with the actual file name at runtime. +First, find the IP address of the Livepatch Server pod. Run `juju status` and locate the IP address of the `livepatch` unit, or use the following command: + +```bash +juju status --format json | jq -r '.applications.livepatch.units[]."address"' ``` -curl 10.1.236.9:8080 -Canonical Livepatch Health service, version v1.13.1 + +Set the URL template using the pod's IP address. Replace `` with the value you retrieved: + +```bash +juju config livepatch server.url-template="http://:8080/v1/patches/{filename}" ``` -To take this a step further we can configure the `service-hostname` config option of the nginx-ingress-integrator charm which will then set up an ingress in the microk8s cluster. That can be tested as follows, +Verify the server is running: +```bash +curl :8080 +# Canonical Livepatch Health service, version v1.13.1 ``` + +### Configure the ingress + +For production deployments, referencing pods by IP address is unreliable. Use a Kubernetes ingress to expose the Livepatch Server through a stable domain name. + +Configure the `service-hostname` on the nginx ingress integrator charm: + +```bash juju config ingress service-hostname=livepatch.test.com -kubectl get ingress -n livepatch -NAME CLASS HOSTS ADDRESS PORTS AGE -livepatch-test-com-ingress public livepatch.test.com 127.0.0.1 80 2m14s -# Next we will edit our hosts file to make this address reachable locally -echo '127.0.0.1 livepatch.test.com' | sudo tee -a /etc/hosts -curl livepatch.test.com -Canonical Livepatch Health service, version v1.13.1 ``` -Follow up on this by changing the url-template to match the ingress with +After a short delay, verify the ingress was created: +```bash +kubectl get ingress -n livepatch ``` -juju config livepatch server.url-template="http://livepatch.test.com/v1/patches/{filename}" + +The output shows the IP address where the ingress is accessible with the `livepatch.test.com` domain name. Add an entry to your `/etc/hosts` file to resolve this domain locally: + +```bash +echo '127.0.0.1 livepatch.test.com' | sudo tee -a /etc/hosts ``` -To run this in a production environment, you will need to expose this microk8s cluster publicly. +Update the URL template to use the domain name: -#### Deploying with a config overlay (Optional) +```bash +juju config livepatch server.url-template="http://livepatch.test.com/v1/patches/{filename}" +``` -These settings can be configured at deploy-time by using a juju bundle overlay: +Verify the server is accessible through the ingress: +```bash +curl livepatch.test.com +# Canonical Livepatch Health service, version v1.13.1 ``` -juju deploy ch:canonical-livepatch-onprem –channel=k8s/stable --overlay config.yaml + +```{note} +To run this in a production environment, you must expose the MicroK8s cluster publicly. ``` -The overlay file should have the following content: +### Deploy with a bundle overlay (optional) -``` +You can apply these configuration options at deploy time using a Juju bundle overlay. Create an overlay file named `config.yaml`: + +```yaml applications: livepatch: options: - url_template: + url_template: external_hostname: ``` -### 5. Setting up authentication +Deploy the bundle with the overlay: + +```bash +juju deploy canonical-livepatch-onprem --channel=k8s/stable --overlay config.yaml +``` + +## Set up administrator authentication -To enable admin tool access to the livepatch server, authentication needs to be configured. This is done with username/password authentication. +Administrator access to the Livepatch on-prem deployment requires setting up basic authentication. -Generate the password hash using: +Install the `apache2-utils` package for `htpasswd`, which generates bcrypt password hashes: -``` +```bash sudo apt-get install apache2-utils -htpasswd -bnBC 10 -username:$2y$10$74ZpDgHaxnUQo.AJZk1cMuSRfef5oK5xq5o/GLbUH/Bbw6W2bmctm ``` -The above is a `username:` pair that was generated from the pair “username:password” exactly. This should be changed for a production workload. - -Use the output of the previous command to configure livepatch: +Generate a username and password hash pair. Replace `` and `` with your chosen credentials: +```bash +htpasswd -bnBC 10 ``` + +The output is a `username:hashed-password` pair. Use the output to configure Livepatch: + +```bash juju config livepatch auth.basic.enabled=true juju config livepatch auth.basic.users='username:$2y$10$74ZgHaxn...UH/Bbw6W2bmctm' ``` -See [Administration Tool](/server/how-to-guides/security/setup-administration-tool.md) topic for instructions on installing the administration tool and setting up authentication. +See the [administration tool setup guide](/server/how-to-guides/security/setup-administration-tool) for instructions on installing the admin tool and setting up authentication. -Once this has been done, the livepatch admin tool can be used to authenticate: +### Log in with the admin tool +Install the administration tool from the Snap Store and create an alias: + +```bash +sudo snap install canonical-livepatch-server-admin +sudo snap alias canonical-livepatch-server-admin.livepatch-admin livepatch-admin ``` -export LIVEPATCH_URL=http(s)://{pod or ingress url} + +Export the Livepatch Server URL and log in: + +```bash +export LIVEPATCH_URL="http://livepatch.test.com" livepatch-admin login -a username:password ``` -### 6. Downloading patches - -The final step before attaching client machines to the server is to download patches from Canonical servers. This can be done using the admin tool. See [How to setup administration tool](/server/how-to-guides/security/setup-administration-tool.md) for installation steps. +## Sync patches -To download patches, run: +Download patches from Canonical's hosted Livepatch Server to your on-prem instance: -``` - livepatch-admin sync trigger --wait +```bash +livepatch-admin sync trigger --wait ``` -To check for synced patches run: +To verify synced patches: -``` +```bash livepatch-admin storage patches ``` -And to check for any sync failures run: +To check for sync failures: -``` +```bash livepatch-admin sync report ``` -To limit which patches are downloaded see this [document](/server/reference/patch-management/patch-sync-filters.md). +To limit which patches are downloaded, see the [patch sync filters reference](/server/reference/patch-management/patch-sync-filters). -## Enabling machine status reporting +## Enable machine status reporting (optional) -Each livepatch on-prem instance can optionally send information about the status of the machines it's serving back to Canonical. This functionality is opt-in. +Each Livepatch on-prem instance can optionally send information about the status of the machines it serves back to Canonical. This functionality is opt-in. -The information sent back about each machine includes: +The information sent includes: - Kernel version - CPU model - Architecture - Boot time and uptime -- Livepatch client version -- Obfuscated machine id +- Livepatch Client version +- Obfuscated machine ID - Status of the patch currently applied to the machine's kernel -To enable this reporting, run the following juju command: +Enable machine status reporting: -``` +```bash juju config livepatch patch-sync.send-machine-reports=true ``` -This can be disabled at any time by setting the flag to `false`. +Disable reporting at any time by setting the value to `false`: -### 7. Cleaning up +```bash +juju config livepatch patch-sync.send-machine-reports=false +``` -To clean up your Juju model you can run the following: +## Cleanup -``` +To clean up your Juju model and all associated storage: + +```bash juju destroy-model --no-prompt livepatch --destroy-storage ``` -And to cleanup the Multipass VM: +If you used Multipass, delete the VM: -``` +```bash multipass delete --purge livepatch-deploy ``` + +## Summary + +In this tutorial, you deployed Livepatch on-prem on MicroK8s using Juju, configured an ingress for stable access, set up administrator authentication, and synchronised patches from the upstream Livepatch service. Your Livepatch on-prem server is now ready to serve clients. + +From here, you have several options: + +- **Set up Livepatch Clients**: Install and configure the Livepatch Client on machines in your infrastructure. See the [Livepatch Client documentation](/client/index). +- **Configure patch sync filters**: Limit which patches are downloaded to your on-prem server. See the [patch sync filters reference](/server/reference/patch-management/patch-sync-filters). +- **Explore alternative deployment options**: Deploy Livepatch on-prem on LXD. See the [Livepatch and LXD tutorial](/server/tutorial/livepatch-and-lxd). +- **Get support**: Canonical customers can receive support through the [Canonical support portal](https://portal.support.canonical.com/). \ No newline at end of file diff --git a/docs/support/get-more-help.md b/docs/support/get-more-help.md index f590252..f5f72d6 100644 --- a/docs/support/get-more-help.md +++ b/docs/support/get-more-help.md @@ -1,16 +1,24 @@ --- myst: html_meta: - description: "Get more help - learn about this topic in Livepatch client." + description: "Filing support tickets and getting help with the Livepatch Client and on-premises server." --- - (support-how-do-i-get-more-help)= -# How do I get more help? +# Get more help + +Access to the Ubuntu Livepatch service requires an [Ubuntu Pro](https://ubuntu.com/pro) subscription. Ubuntu Pro includes Canonical support for the Livepatch Client, the Livepatch on-premises server, and the hosted Livepatch service. + +## File a support ticket + +Ubuntu Pro customers can file support tickets through the [Canonical support portal](https://portal.support.canonical.com/). -To access Livepatch see the [Ubuntu Pro](https://www.ubuntu.com/pro) subscription. +When filing a support ticket, include the following information to help the support team diagnose your issue: -Ubuntu Pro customers should file support tickets at: +- Livepatch Client version (`canonical-livepatch --version`) +- Livepatch Client machine token (`canonical-livepatch status --verbose`) +- Ubuntu release and kernel version (`lsb_release -a` and `uname -a`) +- Relevant log output from the Livepatch Client daemon (`journalctl -u snap.canonical-livepatch.canonical-livepatchd`) -- https://portal.support.canonical.com +If you are reporting an issue with the Livepatch on-premises server, include the server version and relevant server log output in your ticket. diff --git a/docs/support/index.md b/docs/support/index.md index e0dde94..a705e4b 100644 --- a/docs/support/index.md +++ b/docs/support/index.md @@ -1,28 +1,31 @@ --- myst: html_meta: - description: "Support information for Livepatch client and server." + description: "Support and bug reporting information for the Livepatch Client and on-premises server." --- - (support)= # Support -To access Livepatch, see the [Ubuntu Pro](https://www.ubuntu.com/pro) subscription. +This section provides details on obtaining support for the Ubuntu Livepatch service, the Livepatch Client, and the Livepatch on-premises server. It also covers how to report bugs for each component. -Canonical customers can receive support on the Ubuntu Livepatch service, client, and server via Canonical's support portal: +## Getting support -- https://portal.support.canonical.com +Access to the Ubuntu Livepatch service requires an [Ubuntu Pro](https://ubuntu.com/pro) subscription. -The projects maintain bug trackers at: +Canonical customers can receive support on the Ubuntu Livepatch service, client, and on-premises server through the [Canonical support portal](https://portal.support.canonical.com/). -- [Livepatch client bug tracker](https://bugs.launchpad.net/canonical-livepatch-client/+filebug) -- [Livepatch on-prem bug tracker](https://bugs.launchpad.net/livepatch-onprem/+filebug) +For information on filing support tickets, see [Get more help](/support/get-more-help.md). + +## Reporting bugs -For client bug reporting details, see [Report bugs](/support/report-bugs.md). +The Livepatch projects maintain dedicated bug trackers: + +- [Livepatch Client bug tracker](https://bugs.launchpad.net/canonical-livepatch-client/+filebug) +- [Livepatch on-prem bug tracker](https://bugs.launchpad.net/livepatch-onprem/+filebug) -For more ways to get help, see [Get more help](/support/get-more-help.md). +For details on reporting client bugs, including the diagnostic information to include, see [Report bugs](/support/report-bugs.md). ```{toctree} :titlesonly: diff --git a/docs/support/report-bugs.md b/docs/support/report-bugs.md index ed0b9cc..824b329 100644 --- a/docs/support/report-bugs.md +++ b/docs/support/report-bugs.md @@ -1,22 +1,47 @@ --- myst: html_meta: - description: "Report bugs - learn about this topic in Livepatch client." + description: "Report bugs for the Livepatch Client and server, including diagnostic commands and privacy recommendations." --- - (support-reporting-bugs)= -# Reporting bugs +# Report bugs + +This page describes how to report bugs for the Livepatch Client and the Livepatch on-premises server. Including the right diagnostic information in your bug report helps the development team diagnose and resolve your issue quickly. + +## Report a Livepatch Client bug + +File client bugs on the [canonical-livepatch Launchpad project](https://bugs.launchpad.net/canonical-livepatch-client/+filebug). Include the output from the following commands in your bug report: + +```bash +snap info canonical-livepatch +``` + +```bash +canonical-livepatch status +``` + +```bash +lsb_release -a +``` + +```bash +uname -a +``` + +```bash +journalctl -u snap.canonical-livepatch.canonical-livepatchd +``` + +The output of `journalctl` can be lengthy. To include only recent log entries, pipe the output into `tail`: -Please file bugs at [the canonical-livepatch launchpad project](https://bugs.launchpad.net/canonical-livepatch-client/+filebug). When you open a bug, please provide the output from the following commands, so that we can troubleshoot your issue: +```bash +journalctl -u snap.canonical-livepatch.canonical-livepatchd | tail -100 +``` -- `snap info canonical-livepatch` -- `canonical-livepatch status` -- `lsb_release -a` -- `uname -a` -- `journalctl -u snap.canonical-livepatch.canonical-livepatchd` +**Note:** Mark the bug as private if any of the diagnostic output contains personal or sensitive information that you do not want publicly visible. -The output of `journalctl` can be long, so consider piping the output into `tail -100` to only show recent issues. +## Report a Livepatch on-prem server bug -**Note:** We recommend marking the bug as private if any of the output contains personal information that you do not want publicly available and searchable. +File server bugs on the [livepatch-onprem Launchpad project](https://bugs.launchpad.net/livepatch-onprem/+filebug). Include the server version and relevant log output in your bug report.