From 4ba03c9d38aae134bd8616178315086589b69ba8 Mon Sep 17 00:00:00 2001 From: Matthew Holt Date: Sun, 4 Jun 2023 22:15:50 -0600 Subject: [PATCH] caddytls: Clarify some JSON config docs --- modules/caddytls/automation.go | 7 +++++++ modules/caddytls/tls.go | 15 ++++++++++++--- 2 files changed, 19 insertions(+), 3 deletions(-) diff --git a/modules/caddytls/automation.go b/modules/caddytls/automation.go index 16647626..de882013 100644 --- a/modules/caddytls/automation.go +++ b/modules/caddytls/automation.go @@ -85,6 +85,13 @@ type AutomationConfig struct { // TLS app to properly provision a new policy. type AutomationPolicy struct { // Which subjects (hostnames or IP addresses) this policy applies to. + // + // This list is a filter, not a command. In other words, it is used + // only to filter whether this policy should apply to a subject that + // needs a certificate; it does NOT command the TLS app to manage a + // certificate for that subject. To have Caddy automate a certificate + // or specific subjects, use the "automate" certificate loader module + // of the TLS app. SubjectsRaw []string `json:"subjects,omitempty"` // The modules that may issue certificates. Default: internal if all diff --git a/modules/caddytls/tls.go b/modules/caddytls/tls.go index 9b5b5529..52f1159b 100644 --- a/modules/caddytls/tls.go +++ b/modules/caddytls/tls.go @@ -39,9 +39,16 @@ func init() { // TLS provides TLS facilities including certificate // loading and management, client auth, and more. type TLS struct { - // Caches certificates in memory for quick use during + // Certificates to load into memory for quick recall during // TLS handshakes. Each key is the name of a certificate - // loader module. All loaded certificates get pooled + // loader module. + // + // The "automate" certificate loader module can be used to + // specify a list of subjects that need certificates to be + // managed automatically. The first matching automation + // policy will be applied to manage the certificate(s). + // + // All loaded certificates get pooled // into the same cache and may be used to complete TLS // handshakes for the relevant server names (SNI). // Certificates loaded manually (anything other than @@ -557,7 +564,9 @@ type Certificate struct { // // Technically, this is a no-op certificate loader module that is treated as // a special case: it uses this app's automation features to load certificates -// for the list of hostnames, rather than loading certificates manually. +// for the list of hostnames, rather than loading certificates manually. But +// the end result is the same: certificates for these subject names will be +// loaded into the in-memory cache and may then be used. type AutomateLoader []string // CaddyModule returns the Caddy module information.