summaryrefslogtreecommitdiff
path: root/modules
diff options
context:
space:
mode:
Diffstat (limited to 'modules')
-rw-r--r--modules/caddyhttp/matchers.go12
-rw-r--r--modules/caddyhttp/responsematchers.go2
-rw-r--r--modules/caddyhttp/templates/templates.go3
-rw-r--r--modules/caddyhttp/vars.go11
-rw-r--r--modules/caddypki/pki.go11
-rw-r--r--modules/caddytls/acmeissuer.go15
-rw-r--r--modules/caddytls/automation.go6
-rw-r--r--modules/caddytls/tls.go19
8 files changed, 44 insertions, 35 deletions
diff --git a/modules/caddyhttp/matchers.go b/modules/caddyhttp/matchers.go
index a22a3f1..073f82f 100644
--- a/modules/caddyhttp/matchers.go
+++ b/modules/caddyhttp/matchers.go
@@ -97,7 +97,8 @@ type (
// ```
MatchQuery url.Values
- // MatchHeader matches requests by header fields. It performs fast,
+ // MatchHeader matches requests by header fields. The key is the field
+ // name and the array is the list of field values. It performs fast,
// exact string comparisons of the field values. Fast prefix, suffix,
// and substring matches can also be done by suffixing, prefixing, or
// surrounding the value with the wildcard `*` character, respectively.
@@ -114,7 +115,8 @@ type (
// (potentially leading to collisions).
MatchHeaderRE map[string]*MatchRegexp
- // MatchProtocol matches requests by protocol.
+ // MatchProtocol matches requests by protocol. Recognized values are
+ // "http", "https", and "grpc".
MatchProtocol string
// MatchRemoteIP matches requests by client IP (or CIDR range).
@@ -139,9 +141,9 @@ type (
// matchers within a set work the same (i.e. different matchers in
// the same set are AND'ed).
//
- // Note that the generated docs which describe the structure of
- // this module are wrong because of how this type unmarshals JSON
- // in a custom way. The correct structure is:
+ // NOTE: The generated docs which describe the structure of this
+ // module are wrong because of how this type unmarshals JSON in a
+ // custom way. The correct structure is:
//
// ```json
// [
diff --git a/modules/caddyhttp/responsematchers.go b/modules/caddyhttp/responsematchers.go
index d9ad848..821def9 100644
--- a/modules/caddyhttp/responsematchers.go
+++ b/modules/caddyhttp/responsematchers.go
@@ -32,7 +32,7 @@ type ResponseMatcher struct {
// If set, each header specified must be one of the
// specified values, with the same logic used by the
- // request header matcher.
+ // [request header matcher](/docs/json/apps/http/servers/routes/match/header/).
Headers http.Header `json:"headers,omitempty"`
}
diff --git a/modules/caddyhttp/templates/templates.go b/modules/caddyhttp/templates/templates.go
index 8f2ea2c..80efded 100644
--- a/modules/caddyhttp/templates/templates.go
+++ b/modules/caddyhttp/templates/templates.go
@@ -237,7 +237,8 @@ type Templates struct {
// Default is text/plain, text/markdown, and text/html.
MIMETypes []string `json:"mime_types,omitempty"`
- // The template action delimiters.
+ // The template action delimiters. If set, must be precisely two elements:
+ // the opening and closing delimiters. Default: `["{{", "}}"]`
Delimiters []string `json:"delimiters,omitempty"`
}
diff --git a/modules/caddyhttp/vars.go b/modules/caddyhttp/vars.go
index 479ef0a..5779b5d 100644
--- a/modules/caddyhttp/vars.go
+++ b/modules/caddyhttp/vars.go
@@ -29,9 +29,14 @@ func init() {
caddy.RegisterModule(MatchVarsRE{})
}
-// VarsMiddleware is an HTTP middleware which sets variables
-// in the context, mainly for use by placeholders. The
-// placeholders have the form: `{http.vars.variable_name}`
+// VarsMiddleware is an HTTP middleware which sets variables to
+// have values that can be used in the HTTP request handler
+// chain. The primary way to access variables is with placeholders,
+// which have the form: `{http.vars.variable_name}`, or with
+// the `vars` and `vars_regexp` request matchers.
+//
+// The key is the variable name, and the value is the value of the
+// variable. Both the name and value may use or contain placeholders.
type VarsMiddleware map[string]string
// CaddyModule returns the Caddy module information.
diff --git a/modules/caddypki/pki.go b/modules/caddypki/pki.go
index b6f08b1..012eaaf 100644
--- a/modules/caddypki/pki.go
+++ b/modules/caddypki/pki.go
@@ -26,10 +26,15 @@ func init() {
}
// PKI provides Public Key Infrastructure facilities for Caddy.
+//
+// This app can define certificate authorities (CAs) which are capable
+// of signing certificates. Other modules can be configured to use
+// the CAs defined by this app for issuing certificates or getting
+// key information needed for establishing trust.
type PKI struct {
- // The CAs to manage. Each CA is keyed by an ID that is used
- // to uniquely identify it from other CAs. The default CA ID
- // is "local".
+ // The certificate authorities to manage. Each CA is keyed by an
+ // ID that is used to uniquely identify it from other CAs.
+ // The default CA ID is "local".
CAs map[string]*CA `json:"certificate_authorities,omitempty"`
ctx caddy.Context
diff --git a/modules/caddytls/acmeissuer.go b/modules/caddytls/acmeissuer.go
index b60e560..9a7e73c 100644
--- a/modules/caddytls/acmeissuer.go
+++ b/modules/caddytls/acmeissuer.go
@@ -36,20 +36,16 @@ func init() {
caddy.RegisterModule(ACMEIssuer{})
}
-// ACMEIssuer makes an ACME manager
-// for managing certificates using ACME.
-//
-// TODO: support multiple ACME endpoints (probably
-// requires an array of these structs) - caddy would
-// also have to load certs from the backup CAs if the
-// first one is expired...
+// ACMEIssuer manages certificates using the ACME protocol (RFC 8555).
type ACMEIssuer struct {
- // The URL to the CA's ACME directory endpoint.
+ // The URL to the CA's ACME directory endpoint. Default:
+ // https://acme-v02.api.letsencrypt.org/directory
CA string `json:"ca,omitempty"`
// The URL to the test CA's ACME directory endpoint.
// This endpoint is only used during retries if there
- // is a failure using the primary CA.
+ // is a failure using the primary CA. Default:
+ // https://acme-staging-v02.api.letsencrypt.org/directory
TestCA string `json:"test_ca,omitempty"`
// Your email address, so the CA can contact you if necessary.
@@ -71,6 +67,7 @@ type ACMEIssuer struct {
ExternalAccount *acme.EAB `json:"external_account,omitempty"`
// Time to wait before timing out an ACME operation.
+ // Default: 0 (no timeout)
ACMETimeout caddy.Duration `json:"acme_timeout,omitempty"`
// Configures the various ACME challenge types.
diff --git a/modules/caddytls/automation.go b/modules/caddytls/automation.go
index c4a90a8..2a701bf 100644
--- a/modules/caddytls/automation.go
+++ b/modules/caddytls/automation.go
@@ -27,8 +27,8 @@ import (
// AutomationConfig governs the automated management of TLS certificates.
type AutomationConfig struct {
- // The list of automation policies. The first matching
- // policy will be applied for a given certificate/name.
+ // The list of automation policies. The first policy matching
+ // a certificate or subject name will be applied.
Policies []*AutomationPolicy `json:"policies,omitempty"`
// On-Demand TLS defers certificate operations to the
@@ -39,7 +39,7 @@ type AutomationConfig struct {
// In 2015, Caddy became the first web server to
// implement this experimental technology.
//
- // Note that this field does not enable on-demand TLS,
+ // Note that this field does not enable on-demand TLS;
// it only configures it for when it is used. To enable
// it, create an automation policy with `on_demand`.
OnDemand *OnDemandConfig `json:"on_demand,omitempty"`
diff --git a/modules/caddytls/tls.go b/modules/caddytls/tls.go
index a93183e..778ae02 100644
--- a/modules/caddytls/tls.go
+++ b/modules/caddytls/tls.go
@@ -47,7 +47,7 @@ type TLS struct {
// have to be refreshed manually before they expire.
CertificatesRaw caddy.ModuleMap `json:"certificates,omitempty" caddy:"namespace=tls.certificates"`
- // Configures the automation of certificate management.
+ // Configures certificate automation.
Automation *AutomationConfig `json:"automation,omitempty"`
// Configures session ticket ephemeral keys (STEKs).
@@ -527,14 +527,14 @@ type Certificate struct {
Tags []string
}
-// AutomateLoader will automatically manage certificates for the names
-// in the list, including obtaining and renewing certificates. Automated
-// certificates are managed according to their matching automation policy,
-// configured elsewhere in this app.
+// AutomateLoader will automatically manage certificates for the names in the
+// list, including obtaining and renewing certificates. Automated certificates
+// are managed according to their matching automation policy, configured
+// elsewhere in this app.
//
-// 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.
+// 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.
type AutomateLoader []string
// CaddyModule returns the Caddy module information.
@@ -549,8 +549,7 @@ func (AutomateLoader) CaddyModule() caddy.ModuleInfo {
type CertCacheOptions struct {
// Maximum number of certificates to allow in the
// cache. If reached, certificates will be randomly
- // evicted to make room for new ones. Default: 0
- // (no limit).
+ // evicted to make room for new ones. Default: 10,000
Capacity int `json:"capacity,omitempty"`
}