[PATCH docs v2 0/5] cephx-migration: Simplify docs

[PATCH docs v2 0/5] cephx-migration: Simplify docs

[Maximiliano Sandoval]

These are other patches I had on top of https://lore.proxmox.com/all/20260908113718.326913-1-m.sandoval@proxmox.com/T/#u.

Maximiliano Sandoval (5):
  cephx-migration: Replace consumer with client
  cephx-migration: Add link to CVE-2025-30156
  cephx-migration: Move all requirements into prelude
  cephx-migration: Introduce the helper
  cephx-migration: Simplify docs

 pveceph.adoc | 133 +++++++++++++++++++++++++--------------------------
 1 file changed, 65 insertions(+), 68 deletions(-)

-- 
2.47.3

[PATCH docs v2 1/5] cephx-migration: Replace consumer with client

[Maximiliano Sandoval]

The later term is used more often in the Proxmox VE documentation and upstream
[1]. The Consumer row is removed from the table to avoid being redundant after
replacing it with Client.

[1] https://docs.ceph.com/en/latest/dev/cephx/

Signed-off-by: Maximiliano Sandoval <m.sandoval@proxmox.com>
---
 pveceph.adoc | 41 ++++++++++++++++++++---------------------
 1 file changed, 20 insertions(+), 21 deletions(-)

diff --git a/pveceph.adoc b/pveceph.adoc
index c9832ec..9664289 100644
--- a/pveceph.adoc
+++ b/pveceph.adoc
@@ -1407,30 +1407,29 @@ automatically.
 [[pveceph_cipher_support]]
 .Check compatibility
 Several workloads can share one Ceph user. Migrate its key only when every
-consumer supports `aes256k`, including disconnected and external clients.
+client supports `aes256k`, including disconnected and external clients.
 Ceph programs from the updated {pve} packages support it; kernel clients
 require a *running* kernel version 7.0 or newer.
 
 [cols="2,3",options="header"]
 |===
-|Consumer |Client implementation
 |Virtual machine with RBD disks |Userspace, unless `krbd` is enabled.
 |Container on RBD |Always the kernel client.
 |CephFS mount |Kernel, unless `fuse` is enabled.
 |===
 
-Check external systems too. If any affected consumer is incompatible or
+Check external systems too. 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
-consumer of these users is affected; storages of external clusters are
+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 consumers to refresh
+files. Both keys remain valid until confirmation, allowing clients to refresh
 before the old key is retired. If a monitor cannot keep both keys valid, the
 helper refuses staging and names the monitor to update or restart.
 
@@ -1454,8 +1453,8 @@ While a key is staged, do not add or downgrade monitors or change that user's
 keys with other tools. Its `AUTH_INSECURE_CLIENT_KEY_TYPE` warning remains
 until confirmation makes the new key current and invalidates the old one.
 
-[[pveceph_cephx_refresh_consumers]]
-.Refresh consumers
+[[pveceph_cephx_refresh_clients]]
+.Refresh Clients
 * Live-migrate affected virtual machines in the web interface, or stop and
   start them. A guest reboot is not enough.
 * Stop and start affected containers and other RBD clients.
@@ -1468,8 +1467,8 @@ until confirmation makes the new key current and invalidates the old one.
   xref:pveceph_cephx_external_copies[managed key files], then restart or remount
   those clients.
 
-The helper reports sessions that may still hold an old key. Consumer names
-are hints, not a complete workload inventory; check disconnected consumers
+The helper reports sessions that may still hold an old key. Client names
+are hints, not a complete workload inventory; check disconnected clients
 and external key copies yourself.
 
 [[pveceph_cephx_finish]]
@@ -1478,7 +1477,7 @@ and external key copies yourself.
 
 Run a final dry run to check for remaining old-key sessions. It offers a
 confirmation command when its observed checks pass, but cannot verify
-disconnected consumers or external key copies for you.
+disconnected clients or external key copies for you.
 
 [source,bash]
 ----
@@ -1489,7 +1488,7 @@ WARNING: Clients that still need an old key or cipher cannot authenticate
 after this step. Existing IO can appear to work until a reconnect and then
 fail. Do not use `--force` to bypass a blocker.
 
-After checking disconnected consumers and external copies, run the exact
+After checking disconnected clients and external copies, run the exact
 command the dry run prints. When every rotation is ready and no key needs the
 old cipher, it is:
 
@@ -1509,7 +1508,7 @@ Use `pveceph auth status` for current and pending key ciphers, as
 
 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
-every consumer has been refreshed. Deleting it earlier loses the records
+every client has been refreshed. Deleting it earlier loses the records
 needed to resume.
 
 Additional Migration Details
@@ -1551,15 +1550,15 @@ checks this again on every run.
 With `--apply`, `--confirm-all-clients-refreshed` makes every staged key current
 and invalidates its previous key. The initial check refuses the entire batch
 if any open rotation is not ready. The helper then rechecks each key before
-retiring its old credential. If a consumer returns during the batch, completed
+retiring its old credential. If a client returns during the batch, completed
 rotations stay committed and the blocked key stays staged. To confirm ready
 users separately, use `--confirm-clients-refreshed <USER>` with `--apply`.
 
 [[pveceph_cephx_external_copies]]
-Key Copies for External Consumers
-+++++++++++++++++++++++++++++++++
+Key Copies for External Clients
++++++++++++++++++++++++++++++++
 
-For an external consumer of the local cluster, copy the staged credential from
+For an external client of the local cluster, copy the staged credential from
 the managed file for its Ceph user:
 
 * RBD keyring: `/etc/pve/priv/ceph/<STORAGE_ID>.keyring`
@@ -1567,7 +1566,7 @@ the managed file for its Ceph user:
 * Administrative keyring: `/etc/pve/priv/ceph.client.admin.keyring`
 
 Use the credential for that user, not `client.admin` as a substitute. Transfer
-it securely and update every saved copy before refreshing the consumer.
+it securely and update every saved copy before refreshing the client.
 Storage backed by an external cluster is different: the helper never rotates
 that cluster's keys. Follow its administrator's key-rotation procedure.
 
@@ -1583,7 +1582,7 @@ To return a staged user to its current key:
 
 . Run the helper with `--abort-staged-key <USER> --apply`. It restores the
   current key to every managed copy while both credentials remain valid.
-. Refresh all consumers back to that key, including disconnected clients and
+. Refresh all clients back to that key, including disconnected clients and
   external key copies. The helper retries managed CephFS mounts as during
   forward migration.
 . Run the helper with `--confirm-abort-clients-refreshed <USER> --apply` to
@@ -1591,9 +1590,9 @@ To return a staged user to its current key:
   incomplete, a visible session uses the staged key, or its key is unknown.
 
 Ceph 19.2.6-pve4 and 20.2.4-pve4 or newer monitors can identify each session's
-key, allowing consumers on the restored key to stay connected during rollback
+key, allowing clients on the restored key to stay connected during rollback
 confirmation. Upgrade and restart older monitors to use this feature. Without
-key identification, every visible consumer of that user must disconnect before
+key identification, every visible client of that user must disconnect before
 confirmation; upgrading is preferable for a shared user such as `client.admin`.
 
 Emergency Cipher Override
@@ -1632,7 +1631,7 @@ these Proxmox VE details:
   `/etc/pve/priv/ceph.mon.keyring`; never overwrite it.
 * Update an encrypted OSD's lockbox key in both the authentication database and
   its block-device LVM tag. Its temporary keyring is not the persistent copy.
-* Refresh every consumer before invalidating its previous Ceph user key.
+* Refresh every client before invalidating its previous Ceph user key.
 * Rotate `client.admin` last and prepare an independently tested recovery user
   before changing it.
 
-- 
2.47.3

Re: [PATCH docs v2 1/5] cephx-migration: Replace consumer with client

[Thomas Lamprecht]

Am 08.09.26 um 17:39 schrieb Maximiliano Sandoval:
> The later term is used more often in the Proxmox VE documentation and upstream
> [1]. The Consumer row is removed from the table to avoid being redundant after
> replacing it with Client.

I'm fine with that. "consumer" was meant to name all the individual users of
the credential without confusing them with the Ceph identity named client.admin,
and it tried to avoid suggesting that one Ceph identity corresponds to one VM
or connection.

Anyway, that is to subtle in any case (and I jumped terms here a few time,
so everything sounded odd in the end), with a fresher brain the client
terms sounds OK here.

> 
> [1] https://docs.ceph.com/en/latest/dev/cephx/
> 
> Signed-off-by: Maximiliano Sandoval <m.sandoval@proxmox.com>
> ---
>  pveceph.adoc | 41 ++++++++++++++++++++---------------------
>  1 file changed, 20 insertions(+), 21 deletions(-)
> 
> diff --git a/pveceph.adoc b/pveceph.adoc
> index c9832ec..9664289 100644
> --- a/pveceph.adoc
> +++ b/pveceph.adoc
> @@ -1407,30 +1407,29 @@ automatically.
>  [[pveceph_cipher_support]]
>  .Check compatibility
>  Several workloads can share one Ceph user. Migrate its key only when every
> -consumer supports `aes256k`, including disconnected and external clients.
> +client supports `aes256k`, including disconnected and external clients.
>  Ceph programs from the updated {pve} packages support it; kernel clients
>  require a *running* kernel version 7.0 or newer.
>  
>  [cols="2,3",options="header"]
>  |===
> -|Consumer |Client implementation

removing the table header without removing the options="header", which
tells asciidoc that the first row will be a table header, makes this
render odd.

>  |Virtual machine with RBD disks |Userspace, unless `krbd` is enabled.
>  |Container on RBD |Always the kernel client.
>  |CephFS mount |Kernel, unless `fuse` is enabled.
>  |===
>  

[PATCH docs v2 2/5] cephx-migration: Add link to CVE-2025-30156

[Maximiliano Sandoval]

Signed-off-by: Maximiliano Sandoval <m.sandoval@proxmox.com>
---
 pveceph.adoc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/pveceph.adoc b/pveceph.adoc
index 9664289..625768f 100644
--- a/pveceph.adoc
+++ b/pveceph.adoc
@@ -1341,7 +1341,8 @@ 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 CVE-2025-30156.
+worked without warnings before. The older method is affected by
+https://docs.ceph.com/en/latest/security/CVE-2025-30156['CVE-2025-30156'].
 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/].
-- 
2.47.3

[PATCH docs v2 3/5] cephx-migration: Move all requirements into prelude

[Maximiliano Sandoval]

The migration should start after all requirements are meet.

Note that the script will warn if it is not being run as root. There is no need
to mention that the script should be run as root.

Signed-off-by: Maximiliano Sandoval <m.sandoval@proxmox.com>
---
 pveceph.adoc | 51 ++++++++++++++++++++++++++-------------------------
 1 file changed, 26 insertions(+), 25 deletions(-)

diff --git a/pveceph.adoc b/pveceph.adoc
index 625768f..40ca16b 100644
--- a/pveceph.adoc
+++ b/pveceph.adoc
@@ -1363,21 +1363,35 @@ 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.
 
 .Before You Begin
-* Upgrade `pve-manager` to 9.2.17 or newer and install the latest Ceph
-  packages on every node. Staged client-key rotation requires Ceph
-  19.2.6-pve3, 20.2.4-pve3, or newer on every monitor. Then complete the
-  rolling restart of all Ceph services.
+* Upgrade all cluster nodes to the latest {pve} packages. In particular,
+  ** `pve-manager` '9.2.17' or newer
+  ** Ceph '20.2.4-pve3' or newer if using Tentacle
+  ** Ceph '19.2.6-pve3' or newer if using Squid
+  ** Kernel 7.0 or newer.
+* Ensure all external clients are running Ceph and Kernel versions supporting `aes256k`.
+* Complete a rolling restart of Ceph services.
 * Resolve health warnings and errors not listed in
-  xref:pveceph_cephx_health_check_reference[Health Check Reference]. Ensure
-  every node is reachable over SSH.
-* Run the helper as `root` on one node only. Do not start another migration,
-  a rolling restart, or change Ceph keys with other tools while it runs. The
-  helper's lock does not block direct Ceph authentication commands.
+  xref:pveceph_cephx_health_check_reference[Health Check Reference].
+* Ensure every node is reachable over SSH.
+
+.Kernel Support Considerations
+A storage client requires support for `aes256k` in the `rbd` kernel module if:
+
+* A container is using a RBD storage.
+* or, A VM is using a RBD storage, if `krbd` is enabled on the storage configuration.
+* or, a CephFS is mounted, unless `fuse` is enabled in the storage configuration.
+
+Clients requiring kernel support should not downgrade to older kernel versions
+after the migration.
 
 1. Migrate the Cluster-Owned Keys
 +++++++++++++++++++++++++++++++++
 
-Review the cluster-owned migration in the default dry-run mode:
+WARNING: Do not start another migration, a rolling restart, or change Ceph keys
+with other tools during the migration. The helper's lock does not block direct
+Ceph authentication commands.
+
+Review the cluster-owned key migration in dry-run mode:
 
 [source,bash]
 ----
@@ -1405,21 +1419,8 @@ automatically.
 2. Migrate the Keys of Compatible Ceph Users
 ++++++++++++++++++++++++++++++++++++++++++++
 
-[[pveceph_cipher_support]]
-.Check compatibility
-Several workloads can share one Ceph user. Migrate its key only when every
-client supports `aes256k`, including disconnected and external clients.
-Ceph programs from the updated {pve} packages support it; kernel clients
-require a *running* kernel version 7.0 or newer.
-
-[cols="2,3",options="header"]
-|===
-|Virtual machine with RBD disks |Userspace, unless `krbd` is enabled.
-|Container on RBD |Always the kernel client.
-|CephFS mount |Kernel, unless `fuse` is enabled.
-|===
-
-Check external systems too. If any affected client is incompatible or
+Migrate a user's key only once all its clients support `aes256k`, including
+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
-- 
2.47.3

Re: [PATCH docs v2 3/5] cephx-migration: Move all requirements into prelude

[Jonas Theisen]

On 9/8/26 17:39, Maximiliano Sandoval wrote:
> The migration should start after all requirements are meet.
>
> Note that the script will warn if it is not being run as root. There is no need
> to mention that the script should be run as root.
>
> Signed-off-by: Maximiliano Sandoval <m.sandoval@proxmox.com>
> ---
>   pveceph.adoc | 51 ++++++++++++++++++++++++++-------------------------
>   1 file changed, 26 insertions(+), 25 deletions(-)
>
> diff --git a/pveceph.adoc b/pveceph.adoc
> index 625768f..40ca16b 100644
> --- a/pveceph.adoc
> +++ b/pveceph.adoc
> @@ -1363,21 +1363,35 @@ 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.
>   
>   .Before You Begin
> -* Upgrade `pve-manager` to 9.2.17 or newer and install the latest Ceph
> -  packages on every node. Staged client-key rotation requires Ceph
> -  19.2.6-pve3, 20.2.4-pve3, or newer on every monitor. Then complete the
> -  rolling restart of all Ceph services.
> +* Upgrade all cluster nodes to the latest {pve} packages. In particular,
> +  ** `pve-manager` '9.2.17' or newer
> +  ** Ceph '20.2.4-pve3' or newer if using Tentacle
> +  ** Ceph '19.2.6-pve3' or newer if using Squid
> +  ** Kernel 7.0 or newer.
> +* Ensure all external clients are running Ceph and Kernel versions supporting `aes256k`.
> +* Complete a rolling restart of Ceph services.
>   * Resolve health warnings and errors not listed in
> -  xref:pveceph_cephx_health_check_reference[Health Check Reference]. Ensure
> -  every node is reachable over SSH.
> -* Run the helper as `root` on one node only. Do not start another migration,
> -  a rolling restart, or change Ceph keys with other tools while it runs. The
> -  helper's lock does not block direct Ceph authentication commands.
> +  xref:pveceph_cephx_health_check_reference[Health Check Reference].
> +* Ensure every node is reachable over SSH.

Small knit: The trailing full stops are probably unnecessary for a list

Also i would propose to move the "Ensure all external clients [...]"
point to the bottom of the list since this will be the exception.
To reflect this the point could also be formulated like:
"If external clients are accessing the Ceph cluster ensure they support 
'aes256k'"
Imho this would reduce the risk of users getting confused.
> +
> +.Kernel Support Considerations
> +A storage client requires support for `aes256k` in the `rbd` kernel module if:
> +
> +* A container is using a RBD storage.
> +* or, A VM is using a RBD storage, if `krbd` is enabled on the storage configuration.
> +* or, a CephFS is mounted, unless `fuse` is enabled in the storage configuration.
> +
> +Clients requiring kernel support should not downgrade to older kernel versions
> +after the migration.
>   
>   1. Migrate the Cluster-Owned Keys
>   +++++++++++++++++++++++++++++++++
>   
> -Review the cluster-owned migration in the default dry-run mode:
> +WARNING: Do not start another migration, a rolling restart, or change Ceph keys
> +with other tools during the migration. The helper's lock does not block direct
> +Ceph authentication commands.
> +
> +Review the cluster-owned key migration in dry-run mode:
>   
>   [source,bash]
>   ----
> @@ -1405,21 +1419,8 @@ automatically.
>   2. Migrate the Keys of Compatible Ceph Users
>   ++++++++++++++++++++++++++++++++++++++++++++
>   
> -[[pveceph_cipher_support]]
> -.Check compatibility
> -Several workloads can share one Ceph user. Migrate its key only when every
> -client supports `aes256k`, including disconnected and external clients.
> -Ceph programs from the updated {pve} packages support it; kernel clients
> -require a *running* kernel version 7.0 or newer.
> -
> -[cols="2,3",options="header"]
> -|===
> -|Virtual machine with RBD disks |Userspace, unless `krbd` is enabled.
> -|Container on RBD |Always the kernel client.
> -|CephFS mount |Kernel, unless `fuse` is enabled.
> -|===
> -
> -Check external systems too. If any affected client is incompatible or
> +Migrate a user's key only once all its clients support `aes256k`, including
> +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

Re: [PATCH docs v2 3/5] cephx-migration: Move all requirements into prelude

[Thomas Lamprecht]

Am 08.09.26 um 17:39 schrieb Maximiliano Sandoval:
> The migration should start after all requirements are meet.
>
> Note that the script will warn if it is not being run as root. There is no need
> to mention that the script should be run as root.

I mean, fine by me as that user is for such PVE operations rather
commonly needed anyway, but I'd not sign off on that argument in
general; especially for such migrations I 

> 
> Signed-off-by: Maximiliano Sandoval <m.sandoval@proxmox.com>
> ---
>  pveceph.adoc | 51 ++++++++++++++++++++++++++-------------------------
>  1 file changed, 26 insertions(+), 25 deletions(-)
> 
> diff --git a/pveceph.adoc b/pveceph.adoc
> index 625768f..40ca16b 100644
> --- a/pveceph.adoc
> +++ b/pveceph.adoc
> @@ -1363,21 +1363,35 @@ 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.
>  
>  .Before You Begin
> -* Upgrade `pve-manager` to 9.2.17 or newer and install the latest Ceph
> -  packages on every node. Staged client-key rotation requires Ceph
> -  19.2.6-pve3, 20.2.4-pve3, or newer on every monitor. Then complete the
> -  rolling restart of all Ceph services.
> +* Upgrade all cluster nodes to the latest {pve} packages. In particular,
> +  ** `pve-manager` '9.2.17' or newer
> +  ** Ceph '20.2.4-pve3' or newer if using Tentacle
> +  ** Ceph '19.2.6-pve3' or newer if using Squid
> +  ** Kernel 7.0 or newer.


note that this is not strictly true, you can migrate the most essential
keys owned by the cluster just fine without upgrading to kernel 7.0; that's
purely needed for CephFS and krbd, but neither the service daemons nor VMs
running on librbd. Getting imprecise here is IMO not that ideal. btw. for the
case it matters upgrading alone isn't enough, one actually needs to run it.

And just migrating all ceph services over gets rid of the health errors and
improves data at rest safety and some other relevant properties already, so
IMO it can be a relevant for those pondering if they really must upgrade to
7.0 (e.g. due to some compat issue).

> +* Ensure all external clients are running Ceph and Kernel versions supporting `aes256k`.
> +* Complete a rolling restart of Ceph services.
>  * Resolve health warnings and errors not listed in
> -  xref:pveceph_cephx_health_check_reference[Health Check Reference]. Ensure
> -  every node is reachable over SSH.
> -* Run the helper as `root` on one node only. Do not start another migration,
> -  a rolling restart, or change Ceph keys with other tools while it runs. The
> -  helper's lock does not block direct Ceph authentication commands.
> +  xref:pveceph_cephx_health_check_reference[Health Check Reference].
> +* Ensure every node is reachable over SSH.
> +
> +.Kernel Support Considerations
> +A storage client requires support for `aes256k` in the `rbd` kernel module if:
> +
> +* A container is using a RBD storage.
> +* or, A VM is using a RBD storage, if `krbd` is enabled on the storage configuration.
> +* or, a CephFS is mounted, unless `fuse` is enabled in the storage configuration.
> +
> +Clients requiring kernel support should not downgrade to older kernel versions
> +after the migration.

this is a bit odd on its own given that it doesn't mentions the actual required
kernel version (and above requirement doesn't links to it). and IMO the table
was slightly clearer. 

>  
>  1. Migrate the Cluster-Owned Keys
>  +++++++++++++++++++++++++++++++++
>  
> -Review the cluster-owned migration in the default dry-run mode:
> +WARNING: Do not start another migration, a rolling restart, or change Ceph keys
> +with other tools during the migration. The helper's lock does not block direct
> +Ceph authentication commands.
> +
> +Review the cluster-owned key migration in dry-run mode:
>  
>  [source,bash]
>  ----
> @@ -1405,21 +1419,8 @@ automatically.
>  2. Migrate the Keys of Compatible Ceph Users
>  ++++++++++++++++++++++++++++++++++++++++++++
>  
> -[[pveceph_cipher_support]]
> -.Check compatibility
> -Several workloads can share one Ceph user. Migrate its key only when every
> -client supports `aes256k`, including disconnected and external clients.
> -Ceph programs from the updated {pve} packages support it; kernel clients
> -require a *running* kernel version 7.0 or newer.
> -
> -[cols="2,3",options="header"]
> -|===
> -|Virtual machine with RBD disks |Userspace, unless `krbd` is enabled.
> -|Container on RBD |Always the kernel client.
> -|CephFS mount |Kernel, unless `fuse` is enabled.
> -|===
> -
> -Check external systems too. If any affected client is incompatible or
> +Migrate a user's key only once all its clients support `aes256k`, including
> +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

[PATCH docs v2 4/5] cephx-migration: Introduce the helper

[Maximiliano Sandoval]

At this point the helper has not yet been introduced.

Signed-off-by: Maximiliano Sandoval <m.sandoval@proxmox.com>
---
 pveceph.adoc | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/pveceph.adoc b/pveceph.adoc
index 40ca16b..9eba9b3 100644
--- a/pveceph.adoc
+++ b/pveceph.adoc
@@ -1355,9 +1355,8 @@ to `aes256k` and, when all clients support it, disable the vulnerable method.
 Migration Steps
 ^^^^^^^^^^^^^^^
 
-The migration helper checks the cluster, rotates keys, and resumes interrupted
-work. Review each dry run before applying its plan; add `--verbose` for full
-node, keyring, and device inventories.
+{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.
-- 
2.47.3

[PATCH docs v2 5/5] cephx-migration: Simplify docs

[Maximiliano Sandoval]

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 <m.sandoval@proxmox.com>
---
 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

Re: [PATCH docs v2 5/5] cephx-migration: Simplify docs

[Thomas Lamprecht]

Am 08.09.26 um 17:39 schrieb Maximiliano Sandoval:
> 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 <m.sandoval@proxmox.com>
> ---
>  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

I added the sentence about reruns not rotating keys again deliberately, after
triple-checking if it actually holds up in practice myself when running into
an edge case on a production cluster, and I then figured some users will wonder
about this being idempotent here, as a another key rotation could mess things
up bad at the wrong step, and just betting on us doing the right thing without
any indicator seems rather nerve racking in such situations.

> -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.

I mine fine I guess, but I got a hard time figuring where explicitly stating
that the client keys stay unchanged here is really confusing anybody.


> +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.

IMO rather relevant to now that `auth ls` is not complete to remove foot guns.
I.e., sure less docs to read is nice, but only as long as core foot guns and
clarity do not get traded for "word golfing". 

>  
>  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