Publish the agent deployment variables and the operator guidance the design assumes

Component: documentation Rough size: M

Description

Objective item 32, plus §2.6, §4.6 and §7. Half of the field problems in this area are documentation problems. The context document's own variable table was wrong in two places within one release, which is the argument for generating this from source rather than maintaining it by hand.

Tasks

• Every deployment variable the installers honour, with its effect — including the dead ones and what replaced them. That list collapses under #39063 to WAZUH_ENROLLMENT_TOKEN, WAZUH_MANAGER_ENDPOINT, WAZUH_SSL_VERIFICATION, and the handful that were never about registration (WAZUH_AGENT_NAME, groups, keepalive, reconnect, ENROLLMENT_DELAY). Every credential variable goes, WAZUH_REGISTRATION_CA with them, and the rest of the address family (WAZUH_MANAGER, _IP, _PORT); SSL_VERIFICATION is renamed with the old name dropped outright rather than deprecated. Publish the migration, not only the end state — a table of "what you used to set, what you set now" is the artefact people actually need.
• Document the single registration path, and the 4.x rule. Decided 2026-09-11: the enrollment token is the only way to register, and a 4.x agent reaches a 5.x manager only if it is already enrolled — an unenrolled one has to be upgraded to 5.x first and then enrolled with a token. Both halves need saying explicitly, because the second one silently retires the legacy 1515 enrollment path for every new agent.
• Document the token lifetime against the image-baking workflow, or get the lifetime changed. §2.2 recommends baking a credential-less token into a golden image because it "is not a secret at all", but in #39040's store entry.expires = now + mint->ttl is set unconditionally — outside the if (!mint->no_credential) branch — and mint->ttl <= 0 is rejected, so no token is exempt and none can be non-expiring. Default 30 days. With the token now the only registration path, a baked image stops being able to enroll a month after it was built, and there is no WAZUH_MANAGER fallback left. Either the manager grows a non-expiring credential-less token or the documented image workflow has to inject a fresh token at first boot.
• Document the reset, which #39060 closed without producing. PR #39242 recorded it only as a code comment and left "whether this becomes a formally named mechanism" to a separate discussion — so the operator-facing half does not exist anywhere. Today moving an already-bootstrapped agent to a different manager or CA needs all three of: the anchor removed, client.keys cleared, and a new enrollment-token file placed. Any one alone does nothing, because each latch short-circuits on a different file. Say that plainly, and coordinate with whatever #39123 decides about the off switch for verification — the anchor file is both.
• Document the two install shapes, because there are now only two. A token install needs no TLS configuration at all — the anchor arrives with the token and lands at etc/certs/root-ca.pem. A non-token install sets the address with WAZUH_MANAGER_ENDPOINT and the mode with WAZUH_SSL_VERIFICATION, and places the CA itself — the certificate goes to etc/certs/root-ca.pem by hand, and only the CA path needs ossec.conf if it is put anywhere else. There is no longer a middle ground where an environment variable does part of it, and saying that plainly is worth more than documenting each removed variable separately.
• Document the deployments a token cannot name, and how they are configured instead. A zone-scoped IPv6 manager ([fe80::1%25eth0]) can never appear in a token: a zone id has no X.509 representation and mint validates --address against the certificate's SAN, so ERROR 9025 is the only possible outcome. A manager serving no URL prefix needs the host/ spelling. Both are why WAZUH_MANAGER_ENDPOINT is kept (decided 2026-09-14) — say so, with the grammar of §1.4 and a worked example of each, so the variable's remaining purpose is obvious rather than looking like a leftover.
• The verification runbook of §7 and the by-hand certificate path of §4.2, so someone can diagnose an agent that will not verify.
• The golden-image split: a credential-less token carries nothing secret and bakes safely, the credential is injected at first boot from instance metadata or a secrets store. Anything already enrolled has client.keys and the trust state removed before imaging.
• Air-gapped guidance: a pin token at 187 characters can be transcribed if it has to be; an embedded-CA token at ~1,700 characters cannot, and hand transcription is not a supported path for it.
• Migration ordering for a fleet already running (§4.6), and the shared-configuration constraint stated plainly — the manager cannot push <ssl>, by design.
• The 4.x→5.0.0 WPK migration runbook that Task 7 implements: derive the pin from root-ca.pem, place wazuh_ca_pin.txt in etc/shared/<group>/, force the group sync, confirm the file reached the agent before creating the upgrade task, then upgrade and verify the resulting verification_mode. Be explicit about the two things that go wrong at fleet scale: creating the upgrade task before the sync completes silently lands the agent on none, and the state marker Task 7 writes is the only way to find those agents afterwards — so document how to sweep for them.

Definition of Done

• The published list matches what the installers actually do, checked against source.
• An operator can diagnose a non-verifying agent from the runbook without reading code.
• An operator can run the 4.x migration end to end from the runbook, and audit the result across a fleet.

Related: #38940, #39021