From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gate001.proxmox.com (gate001.proxmox.com [IPv6:2a0f:8001:1:32::40]) by lore.proxmox.com (Postfix) with ESMTPS id 23E291FF0B2 for ; Tue, 08 Sep 2026 17:39:54 +0200 (CEST) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id 6143A21614; Tue, 08 Sep 2026 17:39:39 +0200 (CEST) From: Maximiliano Sandoval To: pve-devel@lists.proxmox.com Subject: [PATCH docs v2 5/5] cephx-migration: Simplify docs Date: Tue, 8 Sep 2026 17:39:31 +0200 Message-ID: <20260908153932.577051-6-m.sandoval@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20260908153932.577051-1-m.sandoval@proxmox.com> References: <20260908153932.577051-1-m.sandoval@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1788881964959 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.844 Adjusted score from AWL reputation of From: address DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment (newer systems) KAM_SHORT 0.001 Use of a URL Shortener for very short URL RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: VWDSPS4LPBKDOQRXIY2CPMTH3CTR5CLA X-Message-ID-Hash: VWDSPS4LPBKDOQRXIY2CPMTH3CTR5CLA X-MailFrom: m.sandoval@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: This is an already complex migration, simply reducing the word count can be helpful. - The helper is verbose already, there is no need to document here what it is (not) going to do or print. - No need to mention that client.admin and storage keys are unchanged, this is the content of the next section. Signed-off-by: Maximiliano Sandoval --- pveceph.adoc | 41 +++++++++++++++++++---------------------- 1 file changed, 19 insertions(+), 22 deletions(-) diff --git a/pveceph.adoc b/pveceph.adoc index 9eba9b3..038eb7d 100644 --- a/pveceph.adoc +++ b/pveceph.adoc @@ -1330,19 +1330,19 @@ as the mute lasts. Migrate Cephx Keys from `aes` to `aes256k` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This section explains how to migrate the cluster-owned keys and the keys of -compatible Ceph users from `aes` to `aes256k`. For an explanation of Ceph -users, tickets, and key storage, see +This section explains how to migrate Ceph user authentication keys from `aes` to +`aes256k`. For an explanation of Ceph users, tickets, and key storage, see xref:pveceph_cephx_how_it_works[Cephx Authentication]. Why the Health Checks Appear ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Ceph Squid 19.2.6 and Ceph Tentacle 20.2.4 add health checks for keys and -temporary access credentials that use the older `aes` encryption method. The -checks can therefore appear directly after an upgrade even if the cluster -worked without warnings before. The older method is affected by +temporary access credentials that use the older `aes` encryption method which is +affected by https://docs.ceph.com/en/latest/security/CVE-2025-30156['CVE-2025-30156']. + +The warnings can therefore appear after upgrading a previously healthy cluster. See the upstream release announcement for background footnote:[Ceph: Squid v19.2.6 and Tentacle v20.2.4 released https://ceph.io/en/news/blog/2026/v20-2-4-v19-2-6-combo-released/]. @@ -1358,8 +1358,8 @@ Migration Steps {pve} offers a helper which can handle the migration. The following steps can be performed on a single node. -Reruns do not rotate completed keys again. After each run, invoke the helper -without options to check the current state and follow the next steps it prints. +Between runs, invoke the helper without options to check the current state and +follow the next steps it prints. .Before You Begin * Upgrade all cluster nodes to the latest {pve} packages. In particular, @@ -1404,11 +1404,10 @@ If the plan reports no blocker, apply the same selection: /usr/share/pve-manager/migrations/pve-cephx-rotate-service-keys --rotate-cluster-keys --apply ---- -The helper rotates the manager, metadata server, OSD, monitor, bootstrap, crash, -and xref:pveceph_cephx_lockbox[encrypted OSD lockbox keys]. It restarts services -one at a time when needed, including monitors. Storage-user keys and -`client.admin` stay unchanged, existing tickets remain valid, and the old -cipher stays enabled. +The helper rotates the keys of cluster services, and the +xref:pveceph_cephx_lockbox[encrypted OSD lockbox keys]. It restarts services +sequentially when needed. Existing tickets remain valid, and the old cipher +stays enabled. After Ceph updates its health status, the two error-severity checks clear. The warning about rotating service keys can remain for a few hours and clears @@ -1423,11 +1422,10 @@ disconnected and external clients. If any affected client is incompatible or unknown, leave its user's key unchanged and postpone this step. .Stage the keys -Use `--rotate-all-storage-keys` for the dedicated users of managed local RBD -and CephFS storages, together with `--rotate-admin-key` for `client.admin`, -which the command line and storages without their own user share. Every -client of these users is affected; storages of external clusters are -excluded. +Use `--rotate-all-storage-keys` for users of RBD and CephFS storages managed by +{pve}, together with `--rotate-admin-key` for `client.admin`, shared by the API +and storages without a dedicated user. Every client of these users is +affected; storages of external clusters are excluded. The helper stages each new key and writes it to the managed keyring and secret files. Both keys remain valid until confirmation, allowing clients to refresh @@ -1464,7 +1462,7 @@ until confirmation makes the new key current and invalidates the old one. * The helper refreshes idle CephFS mounts and leaves busy or unresponsive mounts alone. Once nothing uses them, rerun the helper with `--apply` to retry the outstanding mounts. -* For clients outside {pve}, distribute the staged credential from the +* For external clients, distribute the staged credential from the xref:pveceph_cephx_external_copies[managed key files], then restart or remount those clients. @@ -1476,7 +1474,7 @@ and external key copies yourself. 3. Finish or Pause the Migration ++++++++++++++++++++++++++++++++ -Run a final dry run to check for remaining old-key sessions. It offers a +Run a dry run to check for remaining old-key sessions. It offers a confirmation command when its observed checks pass, but cannot verify disconnected clients or external key copies for you. @@ -1504,8 +1502,7 @@ enabled rather than restricting it. You can xref:pveceph_mute_health_check[mute the remaining warnings] while waiting for those clients to upgrade. -Use `pveceph auth status` for current and pending key ciphers, as -`ceph auth ls` does not list pending keys. +Use `pveceph auth status` for current and pending key ciphers. NOTE: `/etc/pve/priv/cephx-key-migration.json` records progress and contains secret old keys. Protect it and keep it until the migration is complete and -- 2.47.3