From 4ba03c9d38aae134bd8616178315086589b69ba8 Mon Sep 17 00:00:00 2001
From: Matthew Holt <mholt@users.noreply.github.com>
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 16647626c..de8820131 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 9b5b55290..52f1159b1 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.