From 3c06220c0e6e3c5718056dd5131814a57cc60c28 Mon Sep 17 00:00:00 2001 From: Kunal Mohan Date: Mon, 17 Aug 2026 18:03:30 +0530 Subject: [PATCH 01/13] Document GCS, Azure, IBM, and Oracle patch storage backends Adds how-to pages for the four new patch storage backends (mirroring the existing S3 page), updates the patch storage overview and the platform configuration reference table with the new backends and options, and adds a guide for migrating patches between storage backends using rsync. --- docs/.custom_wordlist.txt | 8 ++++ docs/server/reference/patch-storage/index.md | 11 ++++- .../patch-storage/migrating-patch-storage.md | 44 +++++++++++++++++++ .../use-azure-for-patch-storage.md | 22 ++++++++++ .../use-gcs-for-patch-storage.md | 22 ++++++++++ .../use-ibm-for-patch-storage.md | 22 ++++++++++ .../use-oracle-for-patch-storage.md | 22 ++++++++++ .../reference/platform/configuration.md | 35 +++++++++++++-- 8 files changed, 181 insertions(+), 5 deletions(-) create mode 100644 docs/server/reference/patch-storage/migrating-patch-storage.md create mode 100644 docs/server/reference/patch-storage/use-azure-for-patch-storage.md create mode 100644 docs/server/reference/patch-storage/use-gcs-for-patch-storage.md create mode 100644 docs/server/reference/patch-storage/use-ibm-for-patch-storage.md create mode 100644 docs/server/reference/patch-storage/use-oracle-for-patch-storage.md diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 0598f2e..3cc014f 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -19,6 +19,7 @@ Canonical('s)? Charmcraft charmstore cjk +COS crypto cryptographically CVEs @@ -29,12 +30,15 @@ Downloader dvipng enablement Enablement +Entra filepath firewalled fonts freefont Furo gcp +GCE +GCS github GitHub gkeop @@ -42,6 +46,7 @@ glibc GPG gyre hostnames +HMAC hotfix(es)? html https @@ -75,6 +80,7 @@ MyST npm Numpy oem +OCI Open Graph openapi otf @@ -93,6 +99,7 @@ pymarkdown pymarkdownlnt QEMU Read the Docs +rclone readthedocs redeclare rediraffe @@ -104,6 +111,7 @@ Rockcraft rollout rollouts rst +rsync rtd SCons sequenceDiagram diff --git a/docs/server/reference/patch-storage/index.md b/docs/server/reference/patch-storage/index.md index d4779e0..a866042 100644 --- a/docs/server/reference/patch-storage/index.md +++ b/docs/server/reference/patch-storage/index.md @@ -15,10 +15,14 @@ Livepatch Server supports several different drivers for storing patch files down 2. Swift 3. S3 (and compatible implementations, e.g. minio) 4. Postgresql +5. Google Cloud Storage (GCS) +6. Azure Blob Storage +7. IBM Cloud Object Storage +8. Oracle Cloud Infrastructure (OCI) Object Storage 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 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. +In case there is a need to scale out Livepatch on-prem, use one of the object storage backends (s3, gcs, azure, ibm, oracle), 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. @@ -29,4 +33,9 @@ See the [patch storage](/server/reference/platform/configuration.md) config for :hidden: Use S3 for patch storage +Use GCS for patch storage +Use Azure for patch storage +Use IBM COS for patch storage +Use OCI Object Storage for patch storage +Migrate patches between storage backends ``` diff --git a/docs/server/reference/patch-storage/migrating-patch-storage.md b/docs/server/reference/patch-storage/migrating-patch-storage.md new file mode 100644 index 0000000..2a63026 --- /dev/null +++ b/docs/server/reference/patch-storage/migrating-patch-storage.md @@ -0,0 +1,44 @@ +--- +myst: + html_meta: + description: "Migrate patches between storage backends - learn about this topic in Livepatch on-prem." +--- + + +(server-reference-migrating-patch-storage)= + +# Migrating patches between storage backends + +Every patch storage backend supported by Livepatch Server (filesystem, S3, GCS, Azure, IBM, Oracle, Swift) stores patches as a flat set of files, each keyed by its filename. This means the same set of patch files works unmodified on any backend: migrating between backends is simply a matter of copying the patch files across, then updating [`patch-storage.type`](/server/reference/platform/configuration.md) and its associated options to point at the new backend. + +The recommended tool for copying patches is `rsync`, since it performs a checksum-verified copy and, on repeated runs, only transfers files that have changed. This allows for a near zero-downtime migration: run an initial sync while the current backend is still serving traffic, then run a final, much shorter sync during a brief maintenance window to catch any patches that arrived in between. + +## Filesystem to filesystem + +If either the source or destination (or both) is the filesystem backend, `rsync` can be used directly, locally or over SSH: + +```bash +rsync -avz --progress /var/snap/canonical-livepatch-server/common/patches/ user@remote-host:/path/to/new/patches/ +``` + +## Migrating to or from object storage + +For the object storage backends (S3, GCS, Azure, IBM, Oracle), mount the bucket or container as a local directory with [rclone](https://rclone.org/), which supports all of these backends (including any S3-compatible endpoint, such as IBM COS or MinIO), then `rsync` into or out of the mount as if it were a normal directory. + +1. Install rclone and configure a remote for the bucket/container, following [rclone's documentation](https://rclone.org/docs/) for the relevant backend (`s3`, `google cloud storage`, `azureblob`, or `oracle-object-storage`). +2. Mount the remote: + ```bash + mkdir -p /mnt/livepatch-patches + rclone mount : /mnt/livepatch-patches --daemon + ``` +3. Run an initial sync while the current backend is still in use: + ```bash + rsync -avz --progress /var/snap/canonical-livepatch-server/common/patches/ /mnt/livepatch-patches/ + ``` +4. Stop the Livepatch server (or disable [`patch-sync`](/server/reference/patch-management/patch-sync-filters.md) so no new patches are written) and run a final sync to catch any changes from step 3: + ```bash + rsync -avz --progress --delete /var/snap/canonical-livepatch-server/common/patches/ /mnt/livepatch-patches/ + ``` +5. Verify the file counts match between source and destination, then update the [patch storage config](/server/reference/platform/configuration.md) to the new backend and restart the server. + +The same approach applies in reverse (object storage to filesystem, or between two object storage backends) by mounting both sides and running `rsync` between the two mount points. diff --git a/docs/server/reference/patch-storage/use-azure-for-patch-storage.md b/docs/server/reference/patch-storage/use-azure-for-patch-storage.md new file mode 100644 index 0000000..c3878b1 --- /dev/null +++ b/docs/server/reference/patch-storage/use-azure-for-patch-storage.md @@ -0,0 +1,22 @@ +--- +myst: + html_meta: + description: "Use Azure for patch storage - learn about this topic in Livepatch on-prem." +--- + + +(server-reference-livepatch-on-prem-with-azure-patch-storage)= + +# Livepatch on-prem with Azure Blob Storage patch storage + +In an Azure deployment of Livepatch on-prem, Azure Blob Storage is a good choice for patch storage if the expected number of client machines is high (over 2000). + +To configure this, follow these steps: + +- Create a Blob Storage container in the preferred region (best if the region is the same as the deployment's). Care needs to be taken to make the container not publicly writable, as this would pose a significant security risk. +- Choose an authentication method: a storage account name/key pair, a connection string, an Entra ID (Azure AD) service principal, or a managed identity bound to the VM. +- Configure the relevant Azure [config options](/server/reference/platform/configuration.md). + +Once this is configured, Livepatch will store and retrieve patch files from the Azure Blob Storage container. + +`patch-storage.azure-account-name` is not required when `patch-storage.azure-connection-string` is set, since the connection string already carries the account name and key. When account key, connection string, and service principal credentials are all omitted, a managed identity bound to the VM is used instead (the system-assigned identity by default, or a user-assigned identity selected via `patch-storage.azure-managed-identity-client-id`). diff --git a/docs/server/reference/patch-storage/use-gcs-for-patch-storage.md b/docs/server/reference/patch-storage/use-gcs-for-patch-storage.md new file mode 100644 index 0000000..9dc6347 --- /dev/null +++ b/docs/server/reference/patch-storage/use-gcs-for-patch-storage.md @@ -0,0 +1,22 @@ +--- +myst: + html_meta: + description: "Use GCS for patch storage - learn about this topic in Livepatch on-prem." +--- + + +(server-reference-livepatch-on-prem-with-gcs-patch-storage)= + +# Livepatch on-prem with Google Cloud Storage patch storage + +In a GCP deployment of Livepatch on-prem, Google Cloud Storage (GCS) is a good choice for patch storage if the expected number of client machines is high (over 2000). + +To configure this, follow these steps: + +- Create a GCS bucket in the preferred region (best if the region is the same as the deployment's). Care needs to be taken to make the bucket not publicly writable, as this would pose a significant security risk. +- Create a service account with permissions to read and write objects in that bucket, or rely on the credentials already bound to the VM (e.g. the GCE metadata service, or workload identity) if it is granted the required permissions. +- Configure the relevant GCS [config options](/server/reference/platform/configuration.md). + +Once this is configured, Livepatch will store and retrieve patch files from the GCS bucket. + +`patch-storage.gcs-credentials-file` and `patch-storage.gcs-credentials-json` are both optional; when both are omitted, Application Default Credentials are used instead. `patch-storage.gcs-impersonate-service-account` is also optional; when set, the resolved credentials are used to impersonate that service account instead of being used directly. diff --git a/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md b/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md new file mode 100644 index 0000000..33bde61 --- /dev/null +++ b/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md @@ -0,0 +1,22 @@ +--- +myst: + html_meta: + description: "Use IBM Cloud Object Storage for patch storage - learn about this topic in Livepatch on-prem." +--- + + +(server-reference-livepatch-on-prem-with-ibm-patch-storage)= + +# Livepatch on-prem with IBM Cloud Object Storage patch storage + +In an IBM Cloud deployment of Livepatch on-prem, IBM Cloud Object Storage (COS) is a good choice for patch storage if the expected number of client machines is high (over 2000). + +To configure this, follow these steps: + +- Create a COS bucket in the preferred region (best if the region is the same as the deployment's). Care needs to be taken to make the bucket not publicly writable, as this would pose a significant security risk. +- Choose an authentication method: HMAC credentials, an IAM API key with a service instance ID, or the ambient VPC Instance Metadata Service if the VM is granted the required trusted profile. +- Configure the relevant IBM [config options](/server/reference/platform/configuration.md). + +Once this is configured, Livepatch will store and retrieve patch files from the COS bucket. + +Credentials are resolved in the following order of preference: HMAC keys (`patch-storage.ibm-access-key`/`patch-storage.ibm-secret-key`), then an IAM API key (`patch-storage.ibm-api-key`/`patch-storage.ibm-service-instance-id`), then, if none are configured, the ambient VPC Instance Metadata Service (optionally selecting a trusted profile via `patch-storage.ibm-trusted-profile-id`). diff --git a/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md b/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md new file mode 100644 index 0000000..8360bcb --- /dev/null +++ b/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md @@ -0,0 +1,22 @@ +--- +myst: + html_meta: + description: "Use OCI Object Storage for patch storage - learn about this topic in Livepatch on-prem." +--- + + +(server-reference-livepatch-on-prem-with-oracle-patch-storage)= + +# Livepatch on-prem with Oracle Cloud Infrastructure Object Storage patch storage + +In an OCI deployment of Livepatch on-prem, Oracle Cloud Infrastructure (OCI) Object Storage is a good choice for patch storage if the expected number of client machines is high (over 2000). + +To configure this, follow these steps: + +- Create an Object Storage bucket in the preferred region (best if the region is the same as the deployment's). Care needs to be taken to make the bucket not publicly writable, as this would pose a significant security risk. +- Choose an authentication method: an OCI config file/profile, or instance principal authentication if the compute instance is granted the required IAM policies. +- Configure the relevant OCI [config options](/server/reference/platform/configuration.md). + +Once this is configured, Livepatch will store and retrieve patch files from the OCI Object Storage bucket. + +`patch-storage.oracle-config-file` (and `patch-storage.oracle-profile`) are optional; when omitted, instance principal authentication is used instead, bound to the OCI compute instance the server runs on. diff --git a/docs/server/reference/platform/configuration.md b/docs/server/reference/platform/configuration.md index 1aa28b8..f31b371 100644 --- a/docs/server/reference/platform/configuration.md +++ b/docs/server/reference/platform/configuration.md @@ -143,7 +143,7 @@ The following values configure how the server manages patch storage. See the [pa | Name | Description | Values | | ---- | ----------- | ------ | -| `patch-storage.type` | Storage backend type for on-premises patch synchronisation. | `oneof: filesystem, swift, postgres, s3` | +| `patch-storage.type` | Storage backend type for on-premises patch synchronisation. | `oneof: filesystem, swift, postgres, s3, gcs, azure, ibm, oracle` | | `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` | @@ -154,11 +154,38 @@ The following values configure how the server manages patch storage. See the [pa | `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 for storing patches. | `string` | -| `patch-storage.s3-endpoint` | S3 endpoint URL. | `string` | +| `patch-storage.s3-endpoint` | S3 endpoint URL (only needed for non-AWS S3-compatible services, e.g. MinIO). | `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-storage.s3-use-path-style` | Whether to use path-style bucket addressing. Defaults to `false` (virtual-hosted-style); typically needs to be `true` for non-AWS S3-compatible services (e.g. MinIO, Ceph). | `bool` | +| `patch-storage.s3-access-key` | AWS access key (optional; defaults to the VM's ambient credentials, e.g. an EC2 instance role). | `string` | +| `patch-storage.s3-secret-key` | AWS secret key (optional; see `s3-access-key`). | `string` | +| `patch-storage.s3-assume-role-arn` | IAM role ARN to assume via STS, using the resolved credentials above (optional). | `string` | +| `patch-storage.gcs-bucket` | Google Cloud Storage bucket for storing patches. | `string` | +| `patch-storage.gcs-credentials-file` | Path to a service account JSON key file (optional; defaults to Application Default Credentials). | `string` | +| `patch-storage.gcs-credentials-json` | Inline service account JSON key (optional; see `gcs-credentials-file`). | `string` | +| `patch-storage.gcs-impersonate-service-account` | Email of a service account to impersonate, using the resolved credentials above (optional). | `string` | +| `patch-storage.azure-container` | Azure Blob Storage container for storing patches. | `string` | +| `patch-storage.azure-account-name` | Azure storage account name (not required when `azure-connection-string` is set, which already carries the account name). | `string` | +| `patch-storage.azure-account-key` | Azure storage account key (optional; defaults to a managed identity bound to the VM). | `string` | +| `patch-storage.azure-connection-string` | Azure storage connection string (optional alternative to account name/key). | `string` | +| `patch-storage.azure-tenant-id` | Entra ID tenant ID, for explicit service principal auth (optional; requires `azure-client-id` and `azure-client-secret`). | `string` | +| `patch-storage.azure-client-id` | Entra ID application (client) ID, for explicit service principal auth (optional). | `string` | +| `patch-storage.azure-client-secret` | Entra ID client secret, for explicit service principal auth (optional). | `string` | +| `patch-storage.azure-managed-identity-client-id` | Client ID of a user-assigned managed identity to use instead of the VM's system-assigned identity (optional). | `string` | +| `patch-storage.ibm-bucket` | IBM Cloud Object Storage bucket for storing patches. | `string` | +| `patch-storage.ibm-endpoint` | IBM Cloud Object Storage endpoint. | `string` | +| `patch-storage.ibm-region` | IBM Cloud Object Storage region. | `string` | +| `patch-storage.ibm-access-key` | IBM COS HMAC access key (optional; see `ibm-api-key`). | `string` | +| `patch-storage.ibm-secret-key` | IBM COS HMAC secret key (optional; see `ibm-access-key`). | `string` | +| `patch-storage.ibm-api-key` | IBM Cloud IAM API key (optional; defaults to the ambient VPC Instance Metadata Service). | `string` | +| `patch-storage.ibm-service-instance-id` | IBM COS resource instance ID, required when using `ibm-api-key`. | `string` | +| `patch-storage.ibm-trusted-profile-id` | Trusted profile ID to assume via the ambient VPC Instance Metadata Service (optional; defaults to the instance's default trusted profile). | `string` | +| `patch-storage.oracle-bucket` | OCI Object Storage bucket for storing patches. | `string` | +| `patch-storage.oracle-namespace` | OCI Object Storage namespace. | `string` | +| `patch-storage.oracle-region` | OCI region. | `string` | +| `patch-storage.oracle-config-file` | Path to an OCI config file (optional; defaults to instance principal authentication). | `string` | +| `patch-storage.oracle-profile` | Profile to use within `oracle-config-file` (optional). | `string` | ### Patch cache From 2ca1af0efa2a17d49dc4729a530025fc8fd35071 Mon Sep 17 00:00:00 2001 From: Kunal Mohan Date: Mon, 17 Aug 2026 18:51:11 +0530 Subject: [PATCH 02/13] update docs --- .../patch-storage/migrating-patch-storage.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/docs/server/reference/patch-storage/migrating-patch-storage.md b/docs/server/reference/patch-storage/migrating-patch-storage.md index 2a63026..17167fd 100644 --- a/docs/server/reference/patch-storage/migrating-patch-storage.md +++ b/docs/server/reference/patch-storage/migrating-patch-storage.md @@ -11,7 +11,7 @@ myst: Every patch storage backend supported by Livepatch Server (filesystem, S3, GCS, Azure, IBM, Oracle, Swift) stores patches as a flat set of files, each keyed by its filename. This means the same set of patch files works unmodified on any backend: migrating between backends is simply a matter of copying the patch files across, then updating [`patch-storage.type`](/server/reference/platform/configuration.md) and its associated options to point at the new backend. -The recommended tool for copying patches is `rsync`, since it performs a checksum-verified copy and, on repeated runs, only transfers files that have changed. This allows for a near zero-downtime migration: run an initial sync while the current backend is still serving traffic, then run a final, much shorter sync during a brief maintenance window to catch any patches that arrived in between. +The recommended tool for copying patches is `rsync`, since it performs a checksum-verified copy. Disable patch synchronisation in the config first (so no new patches arrive, and avoid running any manual syncs), then run `rsync` once to copy the existing patches across. ## Filesystem to filesystem @@ -25,20 +25,17 @@ rsync -avz --progress /var/snap/canonical-livepatch-server/common/patches/ user@ For the object storage backends (S3, GCS, Azure, IBM, Oracle), mount the bucket or container as a local directory with [rclone](https://rclone.org/), which supports all of these backends (including any S3-compatible endpoint, such as IBM COS or MinIO), then `rsync` into or out of the mount as if it were a normal directory. -1. Install rclone and configure a remote for the bucket/container, following [rclone's documentation](https://rclone.org/docs/) for the relevant backend (`s3`, `google cloud storage`, `azureblob`, or `oracle-object-storage`). -2. Mount the remote: +1. Disable [`patch-sync`](/server/reference/patch-management/patch-sync-filters.md) in the config so no new patches are synced to the on-prem server, and avoid running any manual syncs, while the migration is in progress. +2. Install rclone and configure a remote for the bucket/container, following [rclone's documentation](https://rclone.org/docs/) for the relevant backend (`s3`, `google cloud storage`, `azureblob`, or `oracle-object-storage`). +3. Mount the remote: ```bash mkdir -p /mnt/livepatch-patches rclone mount : /mnt/livepatch-patches --daemon ``` -3. Run an initial sync while the current backend is still in use: +4. Run `rsync` to copy the existing patches across: ```bash rsync -avz --progress /var/snap/canonical-livepatch-server/common/patches/ /mnt/livepatch-patches/ ``` -4. Stop the Livepatch server (or disable [`patch-sync`](/server/reference/patch-management/patch-sync-filters.md) so no new patches are written) and run a final sync to catch any changes from step 3: - ```bash - rsync -avz --progress --delete /var/snap/canonical-livepatch-server/common/patches/ /mnt/livepatch-patches/ - ``` -5. Verify the file counts match between source and destination, then update the [patch storage config](/server/reference/platform/configuration.md) to the new backend and restart the server. +5. Verify the file counts match between source and destination, then update the [patch storage config](/server/reference/platform/configuration.md) to the new backend and re-enable patch-sync. The same approach applies in reverse (object storage to filesystem, or between two object storage backends) by mounting both sides and running `rsync` between the two mount points. From 7635021d5b00529386d323298e7987ed87d85caa Mon Sep 17 00:00:00 2001 From: Kunal Mohan Date: Mon, 17 Aug 2026 18:56:43 +0530 Subject: [PATCH 03/13] update docs --- .../reference/patch-storage/use-azure-for-patch-storage.md | 2 -- .../server/reference/patch-storage/use-gcs-for-patch-storage.md | 2 -- .../server/reference/patch-storage/use-ibm-for-patch-storage.md | 2 -- .../reference/patch-storage/use-oracle-for-patch-storage.md | 2 -- 4 files changed, 8 deletions(-) diff --git a/docs/server/reference/patch-storage/use-azure-for-patch-storage.md b/docs/server/reference/patch-storage/use-azure-for-patch-storage.md index c3878b1..0a4d903 100644 --- a/docs/server/reference/patch-storage/use-azure-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-azure-for-patch-storage.md @@ -9,8 +9,6 @@ myst: # Livepatch on-prem with Azure Blob Storage patch storage -In an Azure deployment of Livepatch on-prem, Azure Blob Storage is a good choice for patch storage if the expected number of client machines is high (over 2000). - To configure this, follow these steps: - Create a Blob Storage container in the preferred region (best if the region is the same as the deployment's). Care needs to be taken to make the container not publicly writable, as this would pose a significant security risk. diff --git a/docs/server/reference/patch-storage/use-gcs-for-patch-storage.md b/docs/server/reference/patch-storage/use-gcs-for-patch-storage.md index 9dc6347..e0af10b 100644 --- a/docs/server/reference/patch-storage/use-gcs-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-gcs-for-patch-storage.md @@ -9,8 +9,6 @@ myst: # Livepatch on-prem with Google Cloud Storage patch storage -In a GCP deployment of Livepatch on-prem, Google Cloud Storage (GCS) is a good choice for patch storage if the expected number of client machines is high (over 2000). - To configure this, follow these steps: - Create a GCS bucket in the preferred region (best if the region is the same as the deployment's). Care needs to be taken to make the bucket not publicly writable, as this would pose a significant security risk. diff --git a/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md b/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md index 33bde61..8176955 100644 --- a/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md @@ -9,8 +9,6 @@ myst: # Livepatch on-prem with IBM Cloud Object Storage patch storage -In an IBM Cloud deployment of Livepatch on-prem, IBM Cloud Object Storage (COS) is a good choice for patch storage if the expected number of client machines is high (over 2000). - To configure this, follow these steps: - Create a COS bucket in the preferred region (best if the region is the same as the deployment's). Care needs to be taken to make the bucket not publicly writable, as this would pose a significant security risk. diff --git a/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md b/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md index 8360bcb..ed8f052 100644 --- a/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md @@ -9,8 +9,6 @@ myst: # Livepatch on-prem with Oracle Cloud Infrastructure Object Storage patch storage -In an OCI deployment of Livepatch on-prem, Oracle Cloud Infrastructure (OCI) Object Storage is a good choice for patch storage if the expected number of client machines is high (over 2000). - To configure this, follow these steps: - Create an Object Storage bucket in the preferred region (best if the region is the same as the deployment's). Care needs to be taken to make the bucket not publicly writable, as this would pose a significant security risk. From 9045d95768d76afb6ae53ab37003d7e85be935c0 Mon Sep 17 00:00:00 2001 From: Kunal Mohan Date: Mon, 17 Aug 2026 19:02:41 +0530 Subject: [PATCH 04/13] Use full patch-storage.* key names in cross-references; exclude Postgres from migration guide - Cross-references to other config options in the platform configuration table now use the full patch-storage.* key rather than the bare option name, avoiding ambiguity. - The migrating patches guide now explicitly scopes itself to the file-based storage backends and calls out that the Postgres backend isn't covered, since it stores patches in the database rather than as files. --- .../patch-storage/migrating-patch-storage.md | 4 +++- docs/server/reference/platform/configuration.md | 14 +++++++------- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/server/reference/patch-storage/migrating-patch-storage.md b/docs/server/reference/patch-storage/migrating-patch-storage.md index 17167fd..d01f06c 100644 --- a/docs/server/reference/patch-storage/migrating-patch-storage.md +++ b/docs/server/reference/patch-storage/migrating-patch-storage.md @@ -9,7 +9,9 @@ myst: # Migrating patches between storage backends -Every patch storage backend supported by Livepatch Server (filesystem, S3, GCS, Azure, IBM, Oracle, Swift) stores patches as a flat set of files, each keyed by its filename. This means the same set of patch files works unmodified on any backend: migrating between backends is simply a matter of copying the patch files across, then updating [`patch-storage.type`](/server/reference/platform/configuration.md) and its associated options to point at the new backend. +This guide covers migrating between the file-based patch storage backends (filesystem, S3, GCS, Azure, IBM, Oracle, Swift). Each of these stores patches as a flat set of files, each keyed by its filename, so the same set of patch files works unmodified on any of them: migrating between backends is simply a matter of copying the patch files across, then updating [`patch-storage.type`](/server/reference/platform/configuration.md) and its associated options to point at the new backend. + +The Postgres backend (`patch-storage.postgres-connection-string`) is not covered here, since it stores patches as rows in a database rather than as files, and cannot be migrated with `rsync` in the same way. The recommended tool for copying patches is `rsync`, since it performs a checksum-verified copy. Disable patch synchronisation in the config first (so no new patches arrive, and avoid running any manual syncs), then run `rsync` once to copy the existing patches across. diff --git a/docs/server/reference/platform/configuration.md b/docs/server/reference/platform/configuration.md index f31b371..d4ed6a5 100644 --- a/docs/server/reference/platform/configuration.md +++ b/docs/server/reference/platform/configuration.md @@ -159,33 +159,33 @@ The following values configure how the server manages patch storage. See the [pa | `patch-storage.s3-secure` | Whether to use secure transfers. | `bool` | | `patch-storage.s3-use-path-style` | Whether to use path-style bucket addressing. Defaults to `false` (virtual-hosted-style); typically needs to be `true` for non-AWS S3-compatible services (e.g. MinIO, Ceph). | `bool` | | `patch-storage.s3-access-key` | AWS access key (optional; defaults to the VM's ambient credentials, e.g. an EC2 instance role). | `string` | -| `patch-storage.s3-secret-key` | AWS secret key (optional; see `s3-access-key`). | `string` | +| `patch-storage.s3-secret-key` | AWS secret key (optional; see `patch-storage.s3-access-key`). | `string` | | `patch-storage.s3-assume-role-arn` | IAM role ARN to assume via STS, using the resolved credentials above (optional). | `string` | | `patch-storage.gcs-bucket` | Google Cloud Storage bucket for storing patches. | `string` | | `patch-storage.gcs-credentials-file` | Path to a service account JSON key file (optional; defaults to Application Default Credentials). | `string` | -| `patch-storage.gcs-credentials-json` | Inline service account JSON key (optional; see `gcs-credentials-file`). | `string` | +| `patch-storage.gcs-credentials-json` | Inline service account JSON key (optional; see `patch-storage.gcs-credentials-file`). | `string` | | `patch-storage.gcs-impersonate-service-account` | Email of a service account to impersonate, using the resolved credentials above (optional). | `string` | | `patch-storage.azure-container` | Azure Blob Storage container for storing patches. | `string` | | `patch-storage.azure-account-name` | Azure storage account name (not required when `azure-connection-string` is set, which already carries the account name). | `string` | | `patch-storage.azure-account-key` | Azure storage account key (optional; defaults to a managed identity bound to the VM). | `string` | | `patch-storage.azure-connection-string` | Azure storage connection string (optional alternative to account name/key). | `string` | -| `patch-storage.azure-tenant-id` | Entra ID tenant ID, for explicit service principal auth (optional; requires `azure-client-id` and `azure-client-secret`). | `string` | +| `patch-storage.azure-tenant-id` | Entra ID tenant ID, for explicit service principal auth (optional; requires `patch-storage.azure-client-id` and `patch-storage.azure-client-secret`). | `string` | | `patch-storage.azure-client-id` | Entra ID application (client) ID, for explicit service principal auth (optional). | `string` | | `patch-storage.azure-client-secret` | Entra ID client secret, for explicit service principal auth (optional). | `string` | | `patch-storage.azure-managed-identity-client-id` | Client ID of a user-assigned managed identity to use instead of the VM's system-assigned identity (optional). | `string` | | `patch-storage.ibm-bucket` | IBM Cloud Object Storage bucket for storing patches. | `string` | | `patch-storage.ibm-endpoint` | IBM Cloud Object Storage endpoint. | `string` | | `patch-storage.ibm-region` | IBM Cloud Object Storage region. | `string` | -| `patch-storage.ibm-access-key` | IBM COS HMAC access key (optional; see `ibm-api-key`). | `string` | -| `patch-storage.ibm-secret-key` | IBM COS HMAC secret key (optional; see `ibm-access-key`). | `string` | +| `patch-storage.ibm-access-key` | IBM COS HMAC access key (optional; see `patch-storage.ibm-api-key`). | `string` | +| `patch-storage.ibm-secret-key` | IBM COS HMAC secret key (optional; see `patch-storage.ibm-access-key`). | `string` | | `patch-storage.ibm-api-key` | IBM Cloud IAM API key (optional; defaults to the ambient VPC Instance Metadata Service). | `string` | -| `patch-storage.ibm-service-instance-id` | IBM COS resource instance ID, required when using `ibm-api-key`. | `string` | +| `patch-storage.ibm-service-instance-id` | IBM COS resource instance ID, required when using `patch-storage.ibm-api-key`. | `string` | | `patch-storage.ibm-trusted-profile-id` | Trusted profile ID to assume via the ambient VPC Instance Metadata Service (optional; defaults to the instance's default trusted profile). | `string` | | `patch-storage.oracle-bucket` | OCI Object Storage bucket for storing patches. | `string` | | `patch-storage.oracle-namespace` | OCI Object Storage namespace. | `string` | | `patch-storage.oracle-region` | OCI region. | `string` | | `patch-storage.oracle-config-file` | Path to an OCI config file (optional; defaults to instance principal authentication). | `string` | -| `patch-storage.oracle-profile` | Profile to use within `oracle-config-file` (optional). | `string` | +| `patch-storage.oracle-profile` | Profile to use within `patch-storage.oracle-config-file` (optional). | `string` | ### Patch cache From e4795ad42c7f2124ef2ab713cae01bfa3d7d4948 Mon Sep 17 00:00:00 2001 From: Kunal Mohan Date: Tue, 18 Aug 2026 09:54:44 +0530 Subject: [PATCH 05/13] fix broken link --- docs/server/how-to-guides/security/harden-your-deployment.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 29cdd88..0eaf012 100644 --- a/docs/server/how-to-guides/security/harden-your-deployment.md +++ b/docs/server/how-to-guides/security/harden-your-deployment.md @@ -41,7 +41,7 @@ In [federated deployments](/server/how-to-guides/patch-management/chain-livepatc 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.com/data/postgresql/docs/16/how-to/network-and-encryption/enable-tls/). The Livepatch charm does not expose separate database credential configuration -- all credentials are exchanged through the Juju relation protocol. ## Encrypt patch storage connections @@ -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. \ No newline at end of file +To fully reset, remove the application and redeploy. From 5efacda073c299d8deb7f3c4ca62149394db47cc Mon Sep 17 00:00:00 2001 From: Kunal Mohan Date: Tue, 18 Aug 2026 10:12:55 +0530 Subject: [PATCH 06/13] exclude generated build files from lint-md --- docs/Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/Makefile b/docs/Makefile index ebe9470..3bf9ec8 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -120,6 +120,7 @@ lint-md: pymarkdownlnt-install --recurse \ --exclude=$(DEV_DIR)/** \ --exclude=$(DOCS_VENVDIR)/** \ + --exclude=$(DOCS_BUILDDIR)/** \ $(DOCS_SOURCEDIR); \ status=$$?; \ if [ $$status -eq 1 ]; then \ From dd3462d55fed530656b3b5c94bc473aa0db20bfe Mon Sep 17 00:00:00 2001 From: Kunal Mohan Date: Thu, 3 Sep 2026 12:12:48 +0530 Subject: [PATCH 07/13] Remove IBM HMAC-based auth references from public docs ibm-access-key/ibm-secret-key are present in code but aren't intended to be a publicly supported authentication method, so they're removed from the config reference table and the IBM patch storage how-to guide. --- .../reference/patch-storage/use-ibm-for-patch-storage.md | 4 ++-- docs/server/reference/platform/configuration.md | 2 -- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md b/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md index 8176955..5bc7b37 100644 --- a/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md @@ -12,9 +12,9 @@ myst: To configure this, follow these steps: - Create a COS bucket in the preferred region (best if the region is the same as the deployment's). Care needs to be taken to make the bucket not publicly writable, as this would pose a significant security risk. -- Choose an authentication method: HMAC credentials, an IAM API key with a service instance ID, or the ambient VPC Instance Metadata Service if the VM is granted the required trusted profile. +- Choose an authentication method: an IAM API key with a service instance ID, or the ambient VPC Instance Metadata Service if the VM is granted the required trusted profile. - Configure the relevant IBM [config options](/server/reference/platform/configuration.md). Once this is configured, Livepatch will store and retrieve patch files from the COS bucket. -Credentials are resolved in the following order of preference: HMAC keys (`patch-storage.ibm-access-key`/`patch-storage.ibm-secret-key`), then an IAM API key (`patch-storage.ibm-api-key`/`patch-storage.ibm-service-instance-id`), then, if none are configured, the ambient VPC Instance Metadata Service (optionally selecting a trusted profile via `patch-storage.ibm-trusted-profile-id`). +Credentials are resolved in the following order of preference: an IAM API key (`patch-storage.ibm-api-key`/`patch-storage.ibm-service-instance-id`), then, if not configured, the ambient VPC Instance Metadata Service (optionally selecting a trusted profile via `patch-storage.ibm-trusted-profile-id`). diff --git a/docs/server/reference/platform/configuration.md b/docs/server/reference/platform/configuration.md index d4ed6a5..9af618a 100644 --- a/docs/server/reference/platform/configuration.md +++ b/docs/server/reference/platform/configuration.md @@ -176,8 +176,6 @@ The following values configure how the server manages patch storage. See the [pa | `patch-storage.ibm-bucket` | IBM Cloud Object Storage bucket for storing patches. | `string` | | `patch-storage.ibm-endpoint` | IBM Cloud Object Storage endpoint. | `string` | | `patch-storage.ibm-region` | IBM Cloud Object Storage region. | `string` | -| `patch-storage.ibm-access-key` | IBM COS HMAC access key (optional; see `patch-storage.ibm-api-key`). | `string` | -| `patch-storage.ibm-secret-key` | IBM COS HMAC secret key (optional; see `patch-storage.ibm-access-key`). | `string` | | `patch-storage.ibm-api-key` | IBM Cloud IAM API key (optional; defaults to the ambient VPC Instance Metadata Service). | `string` | | `patch-storage.ibm-service-instance-id` | IBM COS resource instance ID, required when using `patch-storage.ibm-api-key`. | `string` | | `patch-storage.ibm-trusted-profile-id` | Trusted profile ID to assume via the ambient VPC Instance Metadata Service (optional; defaults to the instance's default trusted profile). | `string` | From 366b29f4b1a0f9c426227efa476acdaa13035b7b Mon Sep 17 00:00:00 2001 From: kunalmohan-work Date: Thu, 3 Sep 2026 12:24:33 +0530 Subject: [PATCH 08/13] Update description for IBM Cloud Object Storage patch storage Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: kunalmohan-work --- docs/server/reference/patch-storage/use-ibm-for-patch-storage.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md b/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md index 5bc7b37..96d519e 100644 --- a/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md @@ -4,7 +4,6 @@ myst: description: "Use IBM Cloud Object Storage for patch storage - learn about this topic in Livepatch on-prem." --- - (server-reference-livepatch-on-prem-with-ibm-patch-storage)= # Livepatch on-prem with IBM Cloud Object Storage patch storage From 673bbca7f1a848c5042fc3ec85cf8ae5a6c0736a Mon Sep 17 00:00:00 2001 From: kunalmohan-work Date: Thu, 3 Sep 2026 14:45:36 +0530 Subject: [PATCH 09/13] Revise COS bucket creation instructions Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: kunalmohan-work --- .../server/reference/patch-storage/use-ibm-for-patch-storage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md b/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md index 96d519e..8650a56 100644 --- a/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-ibm-for-patch-storage.md @@ -10,7 +10,7 @@ myst: To configure this, follow these steps: -- Create a COS bucket in the preferred region (best if the region is the same as the deployment's). Care needs to be taken to make the bucket not publicly writable, as this would pose a significant security risk. +- Create an IBM Cloud Object Storage (COS) bucket in the preferred region (best if the region is the same as the deployment's). Care needs to be taken to make the bucket not publicly writable, as this would pose a significant security risk. - Choose an authentication method: an IAM API key with a service instance ID, or the ambient VPC Instance Metadata Service if the VM is granted the required trusted profile. - Configure the relevant IBM [config options](/server/reference/platform/configuration.md). From 523318a9c427c3283f9510c91c367403e8df4882 Mon Sep 17 00:00:00 2001 From: Daniel Toader Date: Thu, 20 Aug 2026 11:04:28 +0300 Subject: [PATCH 10/13] Add redirect for supported kernels (#11) --- docs/.custom_wordlist.txt | 2 ++ docs/redirects.txt | 1 + 2 files changed, 3 insertions(+) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 3cc014f..91f7319 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -31,6 +31,7 @@ dvipng enablement Enablement Entra +eTags filepath firewalled fonts @@ -106,6 +107,7 @@ rediraffe redownloading rerediraffe reStructuredText +resync retrigger(ing)? Rockcraft rollout diff --git a/docs/redirects.txt b/docs/redirects.txt index f7e7241..7b86c83 100644 --- a/docs/redirects.txt +++ b/docs/redirects.txt @@ -123,6 +123,7 @@ "livepatch/reference/patch-lifecycle.md" "client/explanation/patches/patch-lifecycle.md" "livepatch/reference/patch-security.md" "client/reference/patches/patch-security.md" "livepatch/reference/supported-kernels.md" "client/reference/platform/supported-kernels.md" +"livepatch/reference/kernels.md" "client/reference/platform/supported-kernels.md" "livepatch_on_prem/explanation/access-control.md" "server/explanation/architecture/access-control.md" "livepatch_on_prem/explanation/data-sent.md" "server/reference/telemetry/data-sent.md" "livepatch_on_prem/explanation/index.md" "server/explanation/index.md" From 549f625f22264d248bda6648787f8a5747d7adee Mon Sep 17 00:00:00 2001 From: Kunal Mohan Date: Thu, 3 Sep 2026 23:45:58 +0530 Subject: [PATCH 11/13] address review comments --- .../server/reference/patch-storage/migrating-patch-storage.md | 3 +-- .../reference/patch-storage/use-azure-for-patch-storage.md | 1 - .../reference/patch-storage/use-gcs-for-patch-storage.md | 1 - .../reference/patch-storage/use-oracle-for-patch-storage.md | 1 - docs/server/reference/platform/configuration.md | 4 ++-- 5 files changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/server/reference/patch-storage/migrating-patch-storage.md b/docs/server/reference/patch-storage/migrating-patch-storage.md index d01f06c..28d7a60 100644 --- a/docs/server/reference/patch-storage/migrating-patch-storage.md +++ b/docs/server/reference/patch-storage/migrating-patch-storage.md @@ -4,7 +4,6 @@ myst: description: "Migrate patches between storage backends - learn about this topic in Livepatch on-prem." --- - (server-reference-migrating-patch-storage)= # Migrating patches between storage backends @@ -28,7 +27,7 @@ rsync -avz --progress /var/snap/canonical-livepatch-server/common/patches/ user@ For the object storage backends (S3, GCS, Azure, IBM, Oracle), mount the bucket or container as a local directory with [rclone](https://rclone.org/), which supports all of these backends (including any S3-compatible endpoint, such as IBM COS or MinIO), then `rsync` into or out of the mount as if it were a normal directory. 1. Disable [`patch-sync`](/server/reference/patch-management/patch-sync-filters.md) in the config so no new patches are synced to the on-prem server, and avoid running any manual syncs, while the migration is in progress. -2. Install rclone and configure a remote for the bucket/container, following [rclone's documentation](https://rclone.org/docs/) for the relevant backend (`s3`, `google cloud storage`, `azureblob`, or `oracle-object-storage`). +2. Install rclone and configure a remote for the bucket/container, following [rclone's documentation](https://rclone.org/docs/) for the relevant backend (`s3`, `google cloud storage`, `azureblob`, `swift`, or `oracle-object-storage`). 3. Mount the remote: ```bash mkdir -p /mnt/livepatch-patches diff --git a/docs/server/reference/patch-storage/use-azure-for-patch-storage.md b/docs/server/reference/patch-storage/use-azure-for-patch-storage.md index 0a4d903..a78efc8 100644 --- a/docs/server/reference/patch-storage/use-azure-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-azure-for-patch-storage.md @@ -4,7 +4,6 @@ myst: description: "Use Azure for patch storage - learn about this topic in Livepatch on-prem." --- - (server-reference-livepatch-on-prem-with-azure-patch-storage)= # Livepatch on-prem with Azure Blob Storage patch storage diff --git a/docs/server/reference/patch-storage/use-gcs-for-patch-storage.md b/docs/server/reference/patch-storage/use-gcs-for-patch-storage.md index e0af10b..8f4797b 100644 --- a/docs/server/reference/patch-storage/use-gcs-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-gcs-for-patch-storage.md @@ -4,7 +4,6 @@ myst: description: "Use GCS for patch storage - learn about this topic in Livepatch on-prem." --- - (server-reference-livepatch-on-prem-with-gcs-patch-storage)= # Livepatch on-prem with Google Cloud Storage patch storage diff --git a/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md b/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md index ed8f052..a59f786 100644 --- a/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md +++ b/docs/server/reference/patch-storage/use-oracle-for-patch-storage.md @@ -4,7 +4,6 @@ myst: description: "Use OCI Object Storage for patch storage - learn about this topic in Livepatch on-prem." --- - (server-reference-livepatch-on-prem-with-oracle-patch-storage)= # Livepatch on-prem with Oracle Cloud Infrastructure Object Storage patch storage diff --git a/docs/server/reference/platform/configuration.md b/docs/server/reference/platform/configuration.md index 9af618a..34d4489 100644 --- a/docs/server/reference/platform/configuration.md +++ b/docs/server/reference/platform/configuration.md @@ -166,7 +166,7 @@ The following values configure how the server manages patch storage. See the [pa | `patch-storage.gcs-credentials-json` | Inline service account JSON key (optional; see `patch-storage.gcs-credentials-file`). | `string` | | `patch-storage.gcs-impersonate-service-account` | Email of a service account to impersonate, using the resolved credentials above (optional). | `string` | | `patch-storage.azure-container` | Azure Blob Storage container for storing patches. | `string` | -| `patch-storage.azure-account-name` | Azure storage account name (not required when `azure-connection-string` is set, which already carries the account name). | `string` | +| `patch-storage.azure-account-name` | Azure storage account name (not required when `patch-storage.azure-connection-string` is set, which already carries the account name). | `string` | | `patch-storage.azure-account-key` | Azure storage account key (optional; defaults to a managed identity bound to the VM). | `string` | | `patch-storage.azure-connection-string` | Azure storage connection string (optional alternative to account name/key). | `string` | | `patch-storage.azure-tenant-id` | Entra ID tenant ID, for explicit service principal auth (optional; requires `patch-storage.azure-client-id` and `patch-storage.azure-client-secret`). | `string` | @@ -257,4 +257,4 @@ The cloud delay feature is deprecated. Use the `patch-delay` and `cutoff-date` c | 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 +| `cloud-delay.default-delay-hours` | Default delay in hours for clouds, regions, or availability zones without a specified delay. | `int` | From e37e50f3eca5e9d5113a0e149450f8e314c235c3 Mon Sep 17 00:00:00 2001 From: Kunal Mohan Date: Fri, 4 Sep 2026 00:06:10 +0530 Subject: [PATCH 12/13] address broken links and review comments --- .../installation/disable-livepatch-during-startup.md | 4 ++-- docs/client/reference/patches/patch-security.md | 4 ++-- docs/server/reference/patch-storage/index.md | 4 ++-- .../server/reference/patch-storage/migrating-patch-storage.md | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) 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 5fc6546..564076a 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 @@ -52,8 +52,8 @@ The process of reporting, blocklisting, and releasing a replacement Livepatch ta 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). +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). 5. Set the Livepatch mode to `normal` or delete the Livepatch mode file. 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 retrieve the most recent Livepatch. \ No newline at end of file +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. diff --git a/docs/client/reference/patches/patch-security.md b/docs/client/reference/patches/patch-security.md index d506b9e..24a66f9 100644 --- a/docs/client/reference/patches/patch-security.md +++ b/docs/client/reference/patches/patch-security.md @@ -31,7 +31,7 @@ Patch files are distributed as tarballs containing metadata and a Linux kernel m All kernel modules are signed by Canonical to verify their authenticity, using asymmetric encryption: - 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) +- Canonical's public key 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. @@ -57,4 +57,4 @@ The Livepatch Client can also be configured to enforce TLS for all patch downloa Go packages used for TLS configuration: -- [`crypto/tls`](https://pkg.go.dev/crypto/tls) \ No newline at end of file +- [`crypto/tls`](https://pkg.go.dev/crypto/tls) diff --git a/docs/server/reference/patch-storage/index.md b/docs/server/reference/patch-storage/index.md index a866042..d0a7bbf 100644 --- a/docs/server/reference/patch-storage/index.md +++ b/docs/server/reference/patch-storage/index.md @@ -13,8 +13,8 @@ Livepatch Server supports several different drivers for storing patch files down 1. Local filesystem 2. Swift -3. S3 (and compatible implementations, e.g. minio) -4. Postgresql +3. S3 (and compatible implementations, e.g. MinIO) +4. PostgreSQL 5. Google Cloud Storage (GCS) 6. Azure Blob Storage 7. IBM Cloud Object Storage diff --git a/docs/server/reference/patch-storage/migrating-patch-storage.md b/docs/server/reference/patch-storage/migrating-patch-storage.md index 28d7a60..d4d7ba5 100644 --- a/docs/server/reference/patch-storage/migrating-patch-storage.md +++ b/docs/server/reference/patch-storage/migrating-patch-storage.md @@ -12,7 +12,7 @@ This guide covers migrating between the file-based patch storage backends (files The Postgres backend (`patch-storage.postgres-connection-string`) is not covered here, since it stores patches as rows in a database rather than as files, and cannot be migrated with `rsync` in the same way. -The recommended tool for copying patches is `rsync`, since it performs a checksum-verified copy. Disable patch synchronisation in the config first (so no new patches arrive, and avoid running any manual syncs), then run `rsync` once to copy the existing patches across. + The recommended tool for copying patches is `rsync`. If you need checksum-based verification, add `--checksum` (note that this can be slower). Disable patch synchronisation in the config first (so no new patches arrive, and avoid running any manual syncs), then run `rsync` once to copy the existing patches across. ## Filesystem to filesystem @@ -24,7 +24,7 @@ rsync -avz --progress /var/snap/canonical-livepatch-server/common/patches/ user@ ## Migrating to or from object storage -For the object storage backends (S3, GCS, Azure, IBM, Oracle), mount the bucket or container as a local directory with [rclone](https://rclone.org/), which supports all of these backends (including any S3-compatible endpoint, such as IBM COS or MinIO), then `rsync` into or out of the mount as if it were a normal directory. +For the object storage backends (S3, GCS, Azure, IBM, Oracle, Swift), mount the bucket or container as a local directory with [rclone](https://rclone.org/), which supports all of these backends (including any S3-compatible endpoint, such as IBM COS or MinIO), then `rsync` into or out of the mount as if it were a normal directory. 1. Disable [`patch-sync`](/server/reference/patch-management/patch-sync-filters.md) in the config so no new patches are synced to the on-prem server, and avoid running any manual syncs, while the migration is in progress. 2. Install rclone and configure a remote for the bucket/container, following [rclone's documentation](https://rclone.org/docs/) for the relevant backend (`s3`, `google cloud storage`, `azureblob`, `swift`, or `oracle-object-storage`). From 2f04fe85d46a95babec9c3b3a5854659b73cb85e Mon Sep 17 00:00:00 2001 From: Kunal Mohan Date: Fri, 4 Sep 2026 12:20:57 +0530 Subject: [PATCH 13/13] address review comments --- docs/server/reference/patch-storage/migrating-patch-storage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/server/reference/patch-storage/migrating-patch-storage.md b/docs/server/reference/patch-storage/migrating-patch-storage.md index d4d7ba5..f6541a2 100644 --- a/docs/server/reference/patch-storage/migrating-patch-storage.md +++ b/docs/server/reference/patch-storage/migrating-patch-storage.md @@ -12,7 +12,7 @@ This guide covers migrating between the file-based patch storage backends (files The Postgres backend (`patch-storage.postgres-connection-string`) is not covered here, since it stores patches as rows in a database rather than as files, and cannot be migrated with `rsync` in the same way. - The recommended tool for copying patches is `rsync`. If you need checksum-based verification, add `--checksum` (note that this can be slower). Disable patch synchronisation in the config first (so no new patches arrive, and avoid running any manual syncs), then run `rsync` once to copy the existing patches across. +The recommended tool for copying patches is `rsync`. If you need checksum-based verification, add `--checksum` (note that this can be slower). Disable patch synchronisation in the config first (so no new patches arrive, and avoid running any manual syncs), then run `rsync` once to copy the existing patches across. ## Filesystem to filesystem