docs: Clarify recovery key documentation for master key vs. per-user key modes#14791
Merged
docs: Clarify recovery key documentation for master key vs. per-user key modes#14791
Conversation
artonge
reviewed
May 7, 2026
Contributor
artonge
left a comment
artonge
left a comment
There was a problem hiding this comment.
Very verbose I think, I would only add a warning near the recovery key paragraph, but this is adding a lot of noise IMO. And also a lot of confusion as the AI generate part are truth-like but to truth.
skjnldsv
added a commit
that referenced
this pull request
May 7, 2026
Implement suggestions from @artonge and @schiessle to reduce verbosity and avoid encouraging unnecessary migration to per-user key mode: Changes: - Remove vague 'performance and compatibility' claims from master key section - Simplify recovery key descriptions to avoid encouraging adoption - Delete duplicate caution box before recovery keys section - Remove instructions on switching to per-user key mode - Reframe per-user keys as compatibility option for legacy/older setups - Add warning about recovery process being slow and resource-intensive - Clarify that master key mode is the default and recommended approach Key changes respond to review feedback: - Avoid 'generating a need' for recovery keys when they're not needed in default mode - Position per-user keys as historical compatibility option, not new choice - Reduce overall verbosity while keeping core clarification of issue #1340 Addresses review comments on PR #14791 Signed-off-by: skjnldsv <skjnldsv@protonmail.com>
Member
Author
|
Updated @artonge and @schiessle |
artonge
approved these changes
May 7, 2026
skjnldsv
commented
May 7, 2026
…key modes Fix issue #1340: recovery key field documentation was confusing since it only applies to per-user key mode, not the default master key mode introduced in Nextcloud 13. Changes: - Update Key Management Modes section to explicitly state recovery key availability - Add reference label for cross-linking - Add caution box in 'Enabling file recovery keys' subsection explaining the limitation - Add troubleshooting entry: 'Why don't I see the recovery key option in Encryption settings?' - Link to server issue #8283 for technical context - Clarify that master key mode is recommended for most deployments Fixes the confusion reported in: - GitHub issue #1340 - Help forum: https://help.nextcloud.com/t/recovery-key-field-missing/50590 - Server issue #8283 Relates to: #1340 Signed-off-by: skjnldsv <skjnldsv@protonmail.com>
Implement suggestions from @artonge and @schiessle to reduce verbosity and avoid encouraging unnecessary migration to per-user key mode: Changes: - Remove vague 'performance and compatibility' claims from master key section - Simplify recovery key descriptions to avoid encouraging adoption - Delete duplicate caution box before recovery keys section - Remove instructions on switching to per-user key mode - Reframe per-user keys as compatibility option for legacy/older setups - Add warning about recovery process being slow and resource-intensive - Clarify that master key mode is the default and recommended approach Key changes respond to review feedback: - Avoid 'generating a need' for recovery keys when they're not needed in default mode - Position per-user keys as historical compatibility option, not new choice - Reduce overall verbosity while keeping core clarification of issue #1340 Addresses review comments on PR #14791 Signed-off-by: skjnldsv <skjnldsv@protonmail.com>
Signed-off-by: John Molakvoæ <skjnldsv@users.noreply.github.com>
skjnldsv
force-pushed
the
fix/recovery-key-documentation-1340
branch
from
238eb90 to
706f924
Compare
come-nc
approved these changes
May 7, 2026
Contributor
📖 Documentation Preview📄 1 changed documentation pageLast updated: Thu, 07 May 2026 17:06:46 GMT |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR fixes issue #1340 by clarifying the recovery key documentation, which has been confusing users since Nextcloud 13 changed the default encryption mode.
Problem
Users reported that recovery key configuration options don't appear in the default Nextcloud installation, suggesting the documentation was outdated. This confusion was reported in:
Root Cause
Since Nextcloud 13, the default encryption mode uses master keys (system-wide encryption), but recovery keys only exist in per-user key mode (legacy, opt-in). The documentation didn't clearly state this limitation.
Solution
Updated
admin_manual/configuration_files/encryption_configuration.rstto:Update Key Management Modes section to explicitly state:
Add reference label for cross-linking from troubleshooting section
Add caution box in "Enabling file recovery keys" subsection explaining:
occ encryption:disable-master-key)Add troubleshooting entry directly addressing the issue:
Changes Made
Verification
✅ Documentation now clearly states recovery keys only exist in per-user key mode
✅ Troubleshooting section directly addresses GitHub issue #1340
✅ Commands to switch modes are clearly referenced
✅ Master key recommendation is clear with reasoning
Related Issues
Fixes #1340
Related to nextcloud/server#8283
Testing
The changes are documentation-only and don't affect functionality. The RST syntax has been verified and should build correctly.