Explain why OpenVox Server overwrites hostcrl and how to avoid it

[miharp]

Summary

Closes #488.

OpenVox Server overwrites the hostcrl file ($ssldir/crl.pem by default) with the CA's CRL. The docs mentioned this in one sentence, as a start-time copy. This PR explains the full behavior and documents a workaround for the case where it breaks the agent on the server host.

Changes

puppet_conf_setting_diffs.markdown (OpenVox Server 8.x and 9.x):

• The shared cacrl / hostcrl text now says that the copy runs at start and again whenever the cacrl file changes, that it always replaces an existing hostcrl file (the CA certificate is only copied when localcacert is missing), and that it exists because the web server reads hostcrl.
• New subsection under hostcrl, "When the agent on the server host trusts a different CA". It covers the failure (certificate verify failed (unable to get certificate CRL)), why deleting the CRL only helps until the next overwrite, and the fix: a separate hostcrl path in the [server] section of puppet.conf. It ends with a recovery step, because the setting only prevents future overwrites: delete the agent's already-overwritten CRL and run the agent to download the correct one.
• The cacrl section links to that subsection.
• The subsection closes with a caveat: the setting separates only the CRL. The agent and server still share the host certificate, private key, and CA certificate, and the server assumes they all come from the same CA, so this is a temporary state and not a long-term configuration.
• The copy is described as skipped when cacrl and hostcrl are the same file, and on servers with the CA service disabled, such as compilers.

intermediate_ca.md (OpenVox Server 8.x and 9.x):

• A short note that a host already managed as an agent of another OpenVox server gets its agent CRL replaced while you set up its CA, linking to the new subsection. The subsection links back to this page.

dirs_ssldir.markdown (OpenVox 8.x and 9.x):

• The crl.pem entry notes that a server with the CA service overwrites the file, with a link to the hostcrl section.

Verification

Source: openvox-server master_service.clj (start-time copy), certificate_authority.clj (retrieve-ca-crl! has no exists check, retrieve-ca-cert! does), certificate_authority_service.clj (file watcher on cacrl), puppet_server_config_core.clj (ssl-crl-path defaults to hostcrl).

Lab, ghcr.io/openvoxproject/openvoxserver:latest (openvox-server 8.16.0):

• A CRL from an unrelated CA placed at $ssldir/crl.pem was replaced on the next restart.
• After puppetserver ca revoke, hostcrl matched cacrl within a second, with no restart.
• With the unrelated CRL in place, puppetserver ca generate failed with the error quoted in the docs.
• With hostcrl = /etc/puppetlabs/puppetserver/ca/host_crl.pem in [server]: the unrelated CRL at $ssldir/crl.pem survived restarts and revocations, the server kept host_crl.pem current, and the web server still refused a revoked client certificate while accepting an unrevoked one.

The shared-state caveat comes from source only (initialize-master-ssl! keeps an existing host certificate, and init-webserver! takes the certificate, key, and CA certificate from the shared puppet.conf settings). A host with its agent and server on different CAs was not lab-tested.

Not lab-tested on 9.x. The copy logic on openvox-server main is the same.

markdownlint passes on the six files, and jekyll build renders the new anchor and links.

Assisted by Claude.