EPP migration guide to 2608 - 1st draft

[krzysztofstaszalek]

Restructures the EPP migration guide around the upcoming 2608 server/client release: a hub with a decision guide, separate legacy-5.x and current-image scenario articles, a shared client-upgrade article, updated FAQ/troubleshooting/ best-practices, and a temporary 5.x-to-2510/2604 path for customers who need to migrate before 2608 ships.

Closes#1328

[github-actions]

Auto-Fix Summary

122 issues fixed, 12 skipped across 9 files

Category	Fixes
Removed filler	4
Idioms (rewrite)	1
OnceUsage (rewrite)	2
QuestionHeadings (rewrite)	3
QuestionHeadings, Netwrix.FirstPerson (rewrite)	3
Dale: idioms	1
Dale: misplaced-modifiers	1
Dale: passive-voice	70
Dale: positional-references	15
Dale: wordiness	22

Skipped (needs manual review)	Reason
docs/endpointprotector/admin/ee_module/eemodule.md:226 — Netwrix.FirstPerson	False positive: the 'I' is part of the hardware product name in a table row, '
docs/endpointprotector/install/migrationprocedure/troubleshooting.md:33 — Dale: passive-voice	Heading "Backup Restore Fails or Is Rejected by the Server" — rewording changes the anchor other pages may target; heading noun-phrase passive is conventional here
docs/endpointprotector/install/migrationprocedure/troubleshooting.md:131 — Dale: passive-voice	Heading "Recurring HTTP 500 Errors Resolved Only by a Full Reboot" is referenced by explicit anchor links from three other articles; rewording risks breaking those cross-references
docs/endpointprotector/install/migrationprocedure/troubleshooting.md:28 — Dale: xy-slop	"is expected behavior, not a defect" is a positive-then-negative contrast, not the flagged "x is not y, x is z" pattern
docs/endpointprotector/install/migrationprocedure/migrationguide.md:111 — Dale: passive-voice	Table column header "Can Be Restored to 2608" — terse header label; an active rewrite would not fit the column
docs/endpointprotector/install/migrationprocedure/migration-legacy-5x-to-2510.md:72 — Dale: passive-voice	Table column header "Can Be Restored to 2604" — same as above
docs/endpointprotector/install/migrationprocedure/migration-legacy-5x.md:184 — Dale: passive-voice	Checklist rows ("VM snapshot created and confirmed", "System backup created and key saved", etc.) use conventional elliptical checklist labels; rewriting would break the table's terse style
docs/endpointprotector/install/migrationprocedure/migration-legacy-5x.md:400 — Dale: positional-references	"click Reload above the status column" describes physical UI placement, not a cross-reference to other content
docs/endpointprotector/install/migrationprocedure/migration-legacy-5x-to-2510.md:489 — Dale: positional-references	Same UI-placement usage of "above" as in migration-legacy-5x.md
docs/endpointprotector/install/migrationprocedure/bestpractices.md:23 — Dale: passive-voice	"php_els is still required" states a licensing requirement inside a terse table cell; the active recast obscures the subject
docs/endpointprotector/admin/ee_module/eemodule.md:30 — Dale: wordiness	"This is available for the Endpoint Protector User Interface." — the referent of "this" is ambiguous; any rewrite would guess at meaning
docs/endpointprotector/admin/ee_module/eemodule.md:155 — Dale: minimizing-difficulty	Read-Only Mode paragraph uses marketing phrasing ("innovative", "seamless", "robust protection"); rewriting is an editorial tone change beyond a Dale autofix, so left for the author

Ask @claude on this PR if you'd like an explanation of any fix.

[github-actions]

Documentation PR Review

Editorial Review

docs/endpointprotector/admin/ee_module/eemodule.md

• Structure — Line 105: The moved Enforced Encryption Deployment section now sits afterEnforced Encryption Settings (line 55), so the reader configures the Master Password, File Tracing, and Offline File Tracing before learning how to get the client onto a device. The new Automatic Updates (Update EasyLock) section at line 143 also references redownloading and redeploying, which only makes sense once deployment has been explained. Suggested fix: restore the original order — Deployment before Settings — and keep Automatic Updates immediately after Settings, next to the other Global Settings toggle described in "Enforced Encryption in Read-Only mode."
• Clarity — Line 9: "Enforced Encryption, Formerly known as EasyLock, is a cross-platform solution" capitalizes "Formerly" mid-sentence. Suggested fix: "Enforced Encryption, formerly known as EasyLock, is a cross-platform solution…"
• Clarity — Lines 15–17: "Used in combination with Endpoint Protector, Enforced Encryption lets Endpoint Protector identify USB storage devices as Trusted Device™ Level 1. This can ensure that protected computers use USB Enforced Encryption." Naming Endpoint Protector twice in one sentence, then repeating Enforced Encryption in the next, makes the subject hard to track. Suggested fix: "Used in combination with Endpoint Protector, Enforced Encryption identifies USB storage devices as Trusted Device™ Level 1. This ensures that protected computers use USB Enforced Encryption."
• Completeness — Line 11: The new compliance paragraph tells the reader that Enforced Encryption "helps organizations meet regulatory frameworks that require validated encryption," but doesn't say how to confirm the validation for an audit — which is exactly what a CMMC or CUI reader needs next. Suggested fix: end the paragraph with a pointer to the verification step already documented at line 51, e.g. "To retrieve the validation certificate details for an audit, see Enforced Encryption 140-3 FIPS Validated Engine."

docs/endpointprotector/install/migrationprocedure/bestpractices.md

• Completeness — Line 23 (item 05): php_els appears with no explanation of what it is or where to find it. This is a standalone summary page, so a reader who lands here directly has no way to act on "php_els is still required." Suggested fix: "…2510/2604 path: the license must still contain the php_els entitlement that unlocks OS patch updates — see Verifying the php_els License Entitlement."
• Completeness — Line 38 (item 15): CrateDB is named as "the new CrateDB component" without ever being defined on this page. Suggested fix: "…the new CrateDB log store that 2608 introduces for log data — it ships empty…" plus a link to the migration guide overview, which is where CrateDB is explained.
• Clarity — Line 55 (item 22): "Fill both DNS fields only on unpatched 2509 or early 2510 environments" reads as an instruction to fill both fields, with the qualifier arriving too late to change what the reader does. Suggested fix: "If you're deploying an unpatched 2509 or early 2510 image, fill both DNS fields — the settings page won't save with only one entry. Patch 2604 fixed this bug, so 2608 needs no workaround."

docs/endpointprotector/install/migrationprocedure/clientupgrade.md

• Structure — Line 99: "Enforced Encryption Client Requires Immediate Update" is an ### subsection of Upload Procedure, but its content is a timing and priority requirement, not an upload step. Three other pages (eemodule.md, faq.md, troubleshooting.md) deep-link to this anchor as the authoritative EE guidance, and those readers land mid-procedure. Suggested fix: promote it to a top-level ## Enforced Encryption Client Requires Immediate Update section placed directly after Upload Procedure, keeping the existing anchor so inbound links don't break.
• Structure — Lines 111–117: Client TLS Changes in 2608 and Obsolete OS Limitations sit between Upload Procedure (line 86) and Deploying Client Upgrades (line 119), interrupting the upload → deploy → verify sequence with reference material. A reader working through the procedure has to skip two sections to find the next action. Suggested fix: move both sections after Verifying the Upgrade (line 141) under a short "Additional considerations" grouping, or up into the Overview.
• Clarity — Line 37: The heading "Bridge Client Requirement for 2608" isn't a question, but the section opens with a bare "No." — the answer has nothing to attach to. (The anchor is phrased as a question, but readers don't see it.) Suggested fix: open with the statement instead: "The 2608 client requires no bridge version. Unlike the earlier change of code signing certificates from CoSoSys to Netwrix (explained below), the 2608 client release doesn't introduce a new trust or signature requirement."

docs/endpointprotector/install/migrationprocedure/faq.md

• Clarity — Lines 276–288 (entry 22): The word "path" now carries two different meanings on this page. The banner at line 12 defines "2510/2604 path:" as the target platform, but the duration table's "Applies To" column uses "Legacy 5.x path only" and "Both paths" to mean the starting platform. A reader who has internalized the banner will read "Both paths" as "both 2608 and 2510/2604." Suggested fix: rename the source axis — use "Legacy 5.x start" / "Current-image start" / "Both starting points" in the Applies To column, and adjust the intro sentence at line 274 to match.
• Clarity — Line 176 (entry 13): "This is a known issue on 2510 with 2604 patch." Suggested fix: "This is a known issue on 2510 servers patched to 2604. Netwrix fixed it in 2608."
• Clarity — Line 316 (entry 23): [idiom] "Reach out to your Netwrix account team" uses an informal phrase where the rest of the guide consistently says "contact." Suggested fix: "Contact your Netwrix account team to adjust licensing accordingly…"
• Clarity — Line 12: [idiom] "once 2608 ships" uses release-team shorthand for "once Netwrix releases 2608." The same figurative use of "ships" recurs in bestpractices.md (lines 12, 38), troubleshooting.md (lines 10, 126), migrationguide.md (lines 12, 86), and migration-legacy-5x-to-2510.md (title and line 8). Suggested fix: "once Netwrix releases 2608" for the schedule references, and "CrateDB starts empty" / "the fix is available only in 2608" for the others.

docs/endpointprotector/install/migrationprocedure/migration-current-image.md

• Completeness — Line 246: The procedure goes from Activate Trial License on a Newly Deployed Image (line 246) straight to Restoring Your Backup onto 2608 (line 253), with no step to patch the fresh 2608 image to the latest 2608 patch level. The legacy-path article includes that step ("Upgrade the 2608 Image to the Latest Patch"), the FAQ duration table lists "Upgrade fresh 2608 image to latest patch — Both paths" (faq.md line 283), and this article's own Server Health Check (line 304) then asks the reader to confirm "the latest 2608.x.x.x version." Suggested fix: add an "Upgrade the 2608 Image to the Latest Patch" section between the trial license and the restore, mirroring the legacy article.
• Clarity — Line 84: The warning says CrateDB "may raise the minimum disk, RAM, and CPU baseline above the values listed here," but no values are listed on this page — the section only links out to Server Requirements. Suggested fix: "…may raise the minimum disk, RAM, and CPU baseline. Check Server Requirements for current 2608 minimums before starting migration." (Same wording at migration-legacy-5x.md line 96.)
• Clarity — Line 171 (checklist item 1): "On 2604, or accepting that 2509/2510/2601/2602 as a source is less extensively tested" isn't grammatical and asks the reader to tick a box for an attitude rather than a task. Suggested fix: "On 2604 — or confirmed that migrating from 2509, 2510, 2601, or 2602 is acceptable despite less extensive testing".
• Structure — Line 392: "If an integration fails verification, see [Troubleshooting Failed Integrations]" sends a current-image reader into the middle of the legacy 5.x article for content that isn't specific to either starting version. Suggested fix: move the shared integration-troubleshooting steps into troubleshooting.md (or into the common Client Upgrade Management article) and have both migration articles link there, so neither path depends on the other's page.

docs/endpointprotector/install/migrationprocedure/migration-legacy-5x-to-2510.md

• Structure — Line 4: sidebar_position: 11 places this temporary, explicitly discouraged path above the recommended Migrating from a Legacy 5.x Server to 2608 article (position 12) in the sidebar. A reader scanning the sidebar meets the deprecated option first. Suggested fix: set sidebar_position: 15 so it follows the two recommended 2608 articles and Client Upgrade Management, matching the order the guide recommends.
• Structure — Line 756: "### Deploying Client Upgrades" is nested under Post-Migration Verification (line 605), after Performance Baseline Comparison — deploying upgrades is an action, not a verification step, and the equivalent content on the 2608 path is a top-level article. Suggested fix: promote it to ## Deploying Client Upgrades and place it before Post-Migration Verification, right after Phase 3.
• Structure — Lines 356–360: The :::note between step 3 and step 4 of "My backup is bigger than 200 MB" breaks the ordered list, so step 4 renders as a new list starting at 1. Suggested fix: move the note after step 4, or indent it four spaces so it stays inside step 3.

docs/endpointprotector/install/migrationprocedure/migration-legacy-5x.md

• Structure — Lines 281–285: Same ordered-list break as above — the :::note between step 3 and step 4 of "Backups Larger Than 200 MB" restarts the numbering at 1. Suggested fix: move the note after step 4, or indent it four spaces to nest it inside step 3.
• Clarity — Line 96: The CrateDB warning references "the values listed here," but this section lists no values; it links to Server Requirements instead. Suggested fix: "…may raise the minimum disk, RAM, and CPU baseline. Check Server Requirements for current 2608 minimums before starting migration."

docs/endpointprotector/install/migrationprocedure/migrationguide.md

• Structure — Lines 11–13 and 85–87: The "Need to Migrate Before 2608 Ships?" tip appears twice, word for word, on the same short page. Suggested fix: keep the copy at line 85, directly under the version table where the reader is choosing an article, and delete the one at lines 11–13 (which currently pushes the support-ended warning below the fold).
• Structure — Lines 89–92: The two "final phases" are listed as (1) Client Upgrade Management and (2) Post-Migration Verification, but the flowchart on the same page runs Verify → ClientUpgrade (lines 63–64), and both migration articles end with Post-Migration Verification followed by "Next Step: Continue to Client Upgrade Management." A reader following the numbered list works the phases in the wrong order. Suggested fix: swap them — "1. Post-Migration Verification … 2. Client Upgrade Management" — so the list, the diagram, and the articles agree.
• Clarity — Line 131: "Both articles end with their own Post-Migration Verification checklist, since a small number of checks (for example, license validation) apply identically regardless of your starting point." The reason given argues for a single shared checklist, not two separate ones. Suggested fix: "Both articles end with their own Post-Migration Verification checklist, because most checks depend on your starting version. Only a few — license validation, for example — are identical across both paths."

docs/endpointprotector/install/migrationprocedure/troubleshooting.md

• Clarity — Lines 120–127: Two consecutive :::note blocks close the HIPAA dictionary entry, and the second is already covered by the first: line 122 says the workaround is needed "on servers still below 2608," which necessarily includes 2510/2604. Suggested fix: drop the second note and fold the target into the first: "The 2608 server release fixes this by making these links independent of the server's hostname. You still need this workaround on any server below 2608, including 2510/2604."
• Clarity — Line 216: This note packs three separate facts into one paragraph — the bridge requirement, a cross-reference to the FAQ, and the 2510/2604 variant — so the reader has to parse the whole block to find which applies. Suggested fix: split into two sentences plus a separate marked line, e.g. "Clients on 5.9.4.1 or older need the 5.9.4.3 Hotfix 1 signature bridge before they can receive the 2608 client package. Any client already on 5.9.4.3 Hotfix 1 or later can go straight to 2608. For the full checklist, see EPP Clients Not Communicating After Migration. 2510/2604 path: the same bridge requirement applies for reaching the 2605 client."

Summary

28 editorial suggestions across 9 files. Vale and Dale issues are auto-fixed separately.

---

What to do next:

Comment @claude on this PR followed by your instructions to get help:

• @claude fix all issues — fix all editorial issues
• @claude help improve the flow of this document — get writing assistance
• @claude explain the voice issues — understand why something was flagged

You can ask Claude anything about the review or about Netwrix writing standards.

Automated fixes are only available for branches in this repository, not forks.

[github-actions]

Auto-Fix Summary

28 issues fixed, 14 skipped across 9 files

Category	Fixes
FirstPerson (rewrite)	1
Dale: idioms	1
Dale: minimizing-difficulty	1
Dale: misplaced-modifiers	1
Dale: passive-voice	14
Dale: positional-references	1
Dale: undefined-acronyms	3
Dale: wordiness	5
Dale: xy-slop	1

Skipped (needs manual review)	Reason
docs/endpointprotector/admin/ee_module/eemodule.md:226 — Netwrix.FirstPerson	False positive. The 'I' is part of the hardware product name 'Lexar 1 (Locked I Device)' in the Trusted Device level compatibility table, not first-person usage. Editing it would falsify a vendor device name.
docs/endpointprotector/install/migrationprocedure/faq.md:44 — Dale: passive-voice	'one for current data captured and stored in CrateDB going forward' — every active rewrite either misattributes log capture to CrateDB or changes which component does what
docs/endpointprotector/install/migrationprocedure/faq.md:152 — Dale: undefined-acronyms	SCIM is an industry-standard identity provisioning protocol (RFC 7644) that the sysadmin audience would know; rule excludes well-known standards
docs/endpointprotector/install/migrationprocedure/migrationguide.md:28 — Dale: passive-voice	'historical data still held in MySQL' / 'current data captured and stored in CrateDB' — same ambiguity as faq.md line 44; active rewrite risks misstating component responsibilities
docs/endpointprotector/install/migrationprocedure/migrationguide.md:111 — Dale: passive-voice	'Can Be Restored to 2608' is a table column label; conventional header phrasing, and rewriting it would break parallelism with the version-matrix rows
docs/endpointprotector/install/migrationprocedure/migration-current-image.md:56 — Dale: passive-voice	'the Ubuntu 22.04 LTS used by 2509/2510/2604' — reduced passive clause inside a comparative noun phrase; rewrite adds no clarity
docs/endpointprotector/install/migrationprocedure/migration-current-image.md:171 — Dale: passive-voice	checklist item 'accepting that 2509/2510/2601/2602 as a source is less extensively tested' — ambiguous subject; an active rewrite could change what the reader is being asked to confirm
docs/endpointprotector/install/migrationprocedure/migration-legacy-5x.md:62 — Dale: passive-voice	'the Ubuntu 22.04 LTS used by 2510/2604' — same construction as migration-current-image.md line 56
docs/endpointprotector/install/migrationprocedure/troubleshooting.md:133 — Dale: passive-voice	'even though CPU and RAM aren't fully used' — active alternatives ('aren't saturated', 'usage stays low') change the technical claim about resource utilization
docs/endpointprotector/install/migrationprocedure/troubleshooting.md:148 — Dale: undefined-acronyms	'ELS for PHP' — could not verify the correct expansion, and the string matches the literal console label in Appliance > Server Information
docs/endpointprotector/install/migrationprocedure/clientupgrade.md:107 — Dale: wordiness	three-option sentence is long, but fixing it means restructuring into a list, which changes document structure and implies a priority order the source doesn't state
docs/endpointprotector/admin/ee_module/eemodule.md:15 — Dale: passive-voice	'Used in combination with Endpoint Protector, Enforced Encryption lets Endpoint Protector identify...' — pre-existing sentence with a redundant subject; multiple valid rewrites with differing emphasis
docs/endpointprotector/admin/ee_module/eemodule.md:48 — Dale: minimizing-difficulty	'allowing for a seamless upgrade' — marketing phrasing rather than a clear claim about task difficulty; removing it would drop content from a release note
docs/endpointprotector/admin/ee_module/eemodule.md:155 — Dale: minimizing-difficulty	'innovative feature', 'seamless transfer', 'without sacrificing accessibility' — marketing prose; a rewrite would delete substantive-looking content rather than fix difficulty minimization

Ask @claude on this PR if you'd like an explanation of any fix.

[github-actions]

Code Review

Scope: correctness only (bugs, build/routing breakage, links, anchors, assets, config/scripts/workflows). Documentation content and style are handled by the separate editorial workflow.

No config, script, or workflow changes in this PR — nothing touches src/config/products.js, docusaurus.config.js, sidebars/, scripts/copy-kb-to-versions.mjs, or .github/workflows/. No security-relevant surface (no secrets, no eval, no shell or CI changes).

Build-safety verification (passed)

Since onBrokenLinks, onBrokenMarkdownLinks, and onBrokenAnchors are all set to throw, I checked every cross-reference in the changed files:

• All internal links resolve — the four new articles (migration-legacy-5x, migration-current-image, migration-legacy-5x-to-2510, clientupgrade) plus every /docs/endpointprotector/... target exists.
• All anchors resolve — including the tricky em-dash slugs (certificate-bridge--historical-context, phase-2--deploy-the-2608-base-image-and-restore-your-backup) and the explicit heading-id overrides in faq.md and troubleshooting.md.
• The three anchors deleted from migrationguide.md were correctly retargeted in all inbound KB/doc references (certificate-bridge-and-upgrade-path, phase-3--uploading-epp--ee-client-packages, hypervisor-compatibility-check). A repo-wide grep confirms zero remaining anchor links into migrationguide, so no dangling anchors survive the 695-line rewrite. Two stale intra-page links in faq.md were also fixed.
• Renamed heading kept its old anchor — "Network Settings Won't Save on 2509/Early 2510" carries an explicit id override of network-settings-wont-save-on-2510, preserving the id an unchanged KB article links to. Good catch by the author.
• Assets — every referenced .webp exists. The server_info_license.webp / server_info_license_2510.webp swap is consistent: the old 2510-era screenshot moved to the _2510 name and is referenced only from the 2510/2604 and php_els sections, while the new file is referenced only from the 2608 articles. No other file in the repo references either image.
• MDX safety — all placeholder-style angle brackets are inside inline code; only paired <small><em> HTML. Code fences and ::: admonitions are balanced in every changed file. Mermaid is enabled in docusaurus.config.js, and both new diagrams parse cleanly.
• Sidebar — sidebars/endpointprotector/epp.js is autogenerated, so the four new files need no manual sidebar entry. Frontmatter (title, description, sidebar_position) is present and well-formed on all of them, and _category_.json still points at the existing migrationguide doc id.
• Best-practice table renumbering (01 through 48) is sequential with no gaps or duplicates after the inserted items.

I could not run an actual build to confirm (node_modules isn't installed in this environment), so the above is static verification rather than a build result.

Issue 1 — Duplicated admonition block: docs/endpointprotector/install/migrationprocedure/migrationguide.md:11 and :85

The identical "Need to Migrate Before 2608 Ships?" tip appears twice on the same page, verbatim — once above the Action Required warning, and again right after the "Which Article Applies to You" table. This looks like an editing artifact rather than deliberate repetition. Suggest keeping only the one after the version table, where it sits next to the decision point it modifies.

Issue 2 — Temporary article sorts above the two primary ones: migration-legacy-5x-to-2510.md:4

sidebar_position: 11 places the explicitly temporary, to-be-retired 2510/2604 article abovemigration-legacy-5x (12) and migration-current-image (13) in the sidebar. Since the hub directs most readers straight to 2608, the temporary path becomes the first article they see. A position of 14, or anything before troubleshooting at 20, would match the intended reading order and makes the article easier to remove cleanly once 2608 ships.

Neither issue breaks the build.

Nit

In migration-legacy-5x-to-2510.md:756, "Deploying Client Upgrades" is nested as an H3 under the H2 "Post-Migration Verification", but it is a deployment procedure rather than a verification step. In the 2608 articles this content lives in the separate clientupgrade.md; promoting it to an H2 here would keep the hierarchy honest.

🤖 Generated with Claude Code