mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 14:51:30 +00:00
shankar0123
85d247455b
Closes Top-10 fix #9 of the 2026-05-02 deployment-target audit
re-run (see cowork/deployment-target-audit-2026-05-02-rerun/
RESULTS.md). Pre-fix, the Postfix connector's docs in
docs/connectors.md described the connector as a single
"Postfix / Dovecot" target without explicit guidance on when to
use Mode=postfix vs Mode=dovecot. Operators with a mail server
running both Postfix (MTA, port 25) and Dovecot (IMAPS, port
993) had to read source to figure out the dual-deploy pattern.
Bundle 11 (commit b829365) added test pin for Mode=dovecot
(TestPostfix_Atomic_DovecotMode_HappyPath +
TestPostfix_Atomic_DovecotMode_VerifyFails_Rollback). This
commit lands the operator-facing doc that complements the test:
1. New "Choosing Mode=postfix vs Mode=dovecot" subsection in
docs/connectors.md "Built-in: Postfix / Dovecot" section.
Covers:
- When to use each mode (MTA on 25 vs IMAPS on 993).
- Daemon-specific defaults (cert_path, key_path,
validate_command, reload_command) cited verbatim from
internal/connector/target/postfix/postfix.go applyDefaults.
- Note that postfix is the default when mode is unset.
- Post-deploy verify endpoint is operator-supplied, NOT a
per-mode default (the connector does not bake in
port 25 / 993 — operators set post_deploy_verify.endpoint
themselves to point at their daemon's listener).
- Dual-deploy pattern for hosts running both daemons (two
separate targets; byte-equal cert hits SHA-256
idempotency on subsequent renewals; targets are independent
in the scheduler so one reload failing rolls back that
target only).
- Shared-cert-via-symlink pattern (atomic-write os.Rename
follows symlinks).
- Daemon-specific quirks (Postfix STARTTLS chain
requirements for external MTA validation; Dovecot IMAPS
client-facing chain shipping; reload independence).
- Test pin reference (Bundle 11 commit hash + dovecot test
names; postfix-mode equivalent test names).
2. Forward-pointer footnote in docs/deployment-atomicity.md
Section 3 "Per-connector atomic contract" pointing at the
new subsection.
No code changes; no test changes; doc-only commit.
Verified locally:
- All defaults cited verbatim from postfix.go::applyDefaults
(cert_path, key_path, validate_command, reload_command).
- Bundle 11 test names verified to exist in
internal/connector/target/postfix/postfix_atomic_test.go
(TestPostfix_Atomic_DovecotMode_HappyPath at L272,
TestPostfix_Atomic_DovecotMode_VerifyFails_Rollback at L354).
- Spec's claim of "verify port 25 / 993 default" was incorrect:
the connector does not bake in a per-mode verify port.
Doc reflects ground truth.
Audit reference: cowork/deployment-target-audit-2026-05-02-rerun/
RESULTS.md Top-10 fix #9.