diff options
Diffstat (limited to 'modules')
| -rw-r--r-- | modules/caddyhttp/matchers.go | 12 | ||||
| -rw-r--r-- | modules/caddyhttp/responsematchers.go | 2 | ||||
| -rw-r--r-- | modules/caddyhttp/templates/templates.go | 3 | ||||
| -rw-r--r-- | modules/caddyhttp/vars.go | 11 | ||||
| -rw-r--r-- | modules/caddypki/pki.go | 11 | ||||
| -rw-r--r-- | modules/caddytls/acmeissuer.go | 15 | ||||
| -rw-r--r-- | modules/caddytls/automation.go | 6 | ||||
| -rw-r--r-- | modules/caddytls/tls.go | 19 |
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"` } |