Fast and extensible multi-platform HTTP/1-2-3 web server with automatic HTTPS
Mirrored from https://github.com/Slazee/caddy.git
Synced Nov 14, 04:00 UTC
General minor improvements to docs
Matthew Holt committed
Sep 24, 2021 at 18:31 UTC
501da21f209c9fad92c65c8ba02a969a03ec5379
9 files changed
+46
-35
README.md
+2
@@ -176,6 +176,8 @@ Please use our [issue tracker](https://github.com/caddyserver/caddy/issues) only
176
177
## About
178
179
+Matthew Holt began developing Caddy in 2014 while studying computer science at Brigham Young University. It soon became the first web server to use HTTPS automatically and by default, and now has hundreds of contributors and has served trillions of HTTPS requests.
180
+
181
**The name "Caddy" is trademarked.** The name of the software is "Caddy", not "Caddy Server" or "CaddyServer". Please call it "Caddy" or, if you wish to clarify, "the Caddy web server". Caddy is a registered trademark of Stack Holdings GmbH.
182
183
- _Project on Twitter: [@caddyserver](https://twitter.com/caddyserver)_
modules/caddyhttp/matchers.go
+7
-5
@@ -97,7 +97,8 @@ type (
97
// ```
98
MatchQuery url.Values
99
100
- // MatchHeader matches requests by header fields. It performs fast,
100
+ // MatchHeader matches requests by header fields. The key is the field
101
+ // name and the array is the list of field values. It performs fast,
102
// exact string comparisons of the field values. Fast prefix, suffix,
103
// and substring matches can also be done by suffixing, prefixing, or
104
// surrounding the value with the wildcard `*` character, respectively.
@@ -114,7 +115,8 @@ type (
115
// (potentially leading to collisions).
116
MatchHeaderRE map[string]*MatchRegexp
117
117
- // MatchProtocol matches requests by protocol.
118
+ // MatchProtocol matches requests by protocol. Recognized values are
119
+ // "http", "https", and "grpc".
120
MatchProtocol string
121
122
// MatchRemoteIP matches requests by client IP (or CIDR range).
@@ -139,9 +141,9 @@ type (
141
// matchers within a set work the same (i.e. different matchers in
142
// the same set are AND'ed).
143
//
142
- // Note that the generated docs which describe the structure of
143
- // this module are wrong because of how this type unmarshals JSON
144
- // in a custom way. The correct structure is:
144
+ // NOTE: The generated docs which describe the structure of this
145
+ // module are wrong because of how this type unmarshals JSON in a
146
+ // custom way. The correct structure is:
147
//
148
// ```json
149
// [
modules/caddyhttp/responsematchers.go
+1
-1
@@ -32,7 +32,7 @@ type ResponseMatcher struct {
32
33
// If set, each header specified must be one of the
34
// specified values, with the same logic used by the
35
- // request header matcher.
35
+ // [request header matcher](/docs/json/apps/http/servers/routes/match/header/).
36
Headers http.Header `json:"headers,omitempty"`
37
}
38
modules/caddyhttp/templates/templates.go
+2
-1
@@ -237,7 +237,8 @@ type Templates struct {
237
// Default is text/plain, text/markdown, and text/html.
238
MIMETypes []string `json:"mime_types,omitempty"`
239
240
- // The template action delimiters.
240
+ // The template action delimiters. If set, must be precisely two elements:
241
+ // the opening and closing delimiters. Default: `["{{", "}}"]`
242
Delimiters []string `json:"delimiters,omitempty"`
243
}
244
modules/caddyhttp/vars.go
+8
-3
@@ -29,9 +29,14 @@ func init() {
29
caddy.RegisterModule(MatchVarsRE{})
30
}
31
32
-// VarsMiddleware is an HTTP middleware which sets variables
33
-// in the context, mainly for use by placeholders. The
34
-// placeholders have the form: `{http.vars.variable_name}`
32
+// VarsMiddleware is an HTTP middleware which sets variables to
33
+// have values that can be used in the HTTP request handler
34
+// chain. The primary way to access variables is with placeholders,
35
+// which have the form: `{http.vars.variable_name}`, or with
36
+// the `vars` and `vars_regexp` request matchers.
37
+//
38
+// The key is the variable name, and the value is the value of the
39
+// variable. Both the name and value may use or contain placeholders.
40
type VarsMiddleware map[string]string
41
42
// CaddyModule returns the Caddy module information.
modules/caddypki/pki.go
+8
-3
@@ -26,10 +26,15 @@ func init() {
26
}
27
28
// PKI provides Public Key Infrastructure facilities for Caddy.
29
+//
30
+// This app can define certificate authorities (CAs) which are capable
31
+// of signing certificates. Other modules can be configured to use
32
+// the CAs defined by this app for issuing certificates or getting
33
+// key information needed for establishing trust.
34
type PKI struct {
30
- // The CAs to manage. Each CA is keyed by an ID that is used
31
- // to uniquely identify it from other CAs. The default CA ID
32
- // is "local".
35
+ // The certificate authorities to manage. Each CA is keyed by an
36
+ // ID that is used to uniquely identify it from other CAs.
37
+ // The default CA ID is "local".
38
CAs map[string]*CA `json:"certificate_authorities,omitempty"`
39
40
ctx caddy.Context
modules/caddytls/acmeissuer.go
+6
-9
@@ -36,20 +36,16 @@ func init() {
36
caddy.RegisterModule(ACMEIssuer{})
37
}
38
39
-// ACMEIssuer makes an ACME manager
40
-// for managing certificates using ACME.
41
-//
42
-// TODO: support multiple ACME endpoints (probably
43
-// requires an array of these structs) - caddy would
44
-// also have to load certs from the backup CAs if the
45
-// first one is expired...
39
+// ACMEIssuer manages certificates using the ACME protocol (RFC 8555).
40
type ACMEIssuer struct {
47
- // The URL to the CA's ACME directory endpoint.
41
+ // The URL to the CA's ACME directory endpoint. Default:
42
+ // https://acme-v02.api.letsencrypt.org/directory
43
CA string `json:"ca,omitempty"`
44
45
// The URL to the test CA's ACME directory endpoint.
46
// This endpoint is only used during retries if there
52
- // is a failure using the primary CA.
47
+ // is a failure using the primary CA. Default:
48
+ // https://acme-staging-v02.api.letsencrypt.org/directory
49
TestCA string `json:"test_ca,omitempty"`
50
51
// Your email address, so the CA can contact you if necessary.
@@ -71,6 +67,7 @@ type ACMEIssuer struct {
67
ExternalAccount *acme.EAB `json:"external_account,omitempty"`
68
69
// Time to wait before timing out an ACME operation.
70
+ // Default: 0 (no timeout)
71
ACMETimeout caddy.Duration `json:"acme_timeout,omitempty"`
72
73
// Configures the various ACME challenge types.
modules/caddytls/automation.go
+3
-3
@@ -27,8 +27,8 @@ import (
27
28
// AutomationConfig governs the automated management of TLS certificates.
29
type AutomationConfig struct {
30
- // The list of automation policies. The first matching
31
- // policy will be applied for a given certificate/name.
30
+ // The list of automation policies. The first policy matching
31
+ // a certificate or subject name will be applied.
32
Policies []*AutomationPolicy `json:"policies,omitempty"`
33
34
// On-Demand TLS defers certificate operations to the
@@ -39,7 +39,7 @@ type AutomationConfig struct {
39
// In 2015, Caddy became the first web server to
40
// implement this experimental technology.
41
//
42
- // Note that this field does not enable on-demand TLS,
42
+ // Note that this field does not enable on-demand TLS;
43
// it only configures it for when it is used. To enable
44
// it, create an automation policy with `on_demand`.
45
OnDemand *OnDemandConfig `json:"on_demand,omitempty"`
modules/caddytls/tls.go
+9
-10
@@ -47,7 +47,7 @@ type TLS struct {
47
// have to be refreshed manually before they expire.
48
CertificatesRaw caddy.ModuleMap `json:"certificates,omitempty" caddy:"namespace=tls.certificates"`
49
50
- // Configures the automation of certificate management.
50
+ // Configures certificate automation.
51
Automation *AutomationConfig `json:"automation,omitempty"`
52
53
// Configures session ticket ephemeral keys (STEKs).
@@ -527,14 +527,14 @@ type Certificate struct {
527
Tags []string
528
}
529
530
-// AutomateLoader will automatically manage certificates for the names
531
-// in the list, including obtaining and renewing certificates. Automated
532
-// certificates are managed according to their matching automation policy,
533
-// configured elsewhere in this app.
530
+// AutomateLoader will automatically manage certificates for the names in the
531
+// list, including obtaining and renewing certificates. Automated certificates
532
+// are managed according to their matching automation policy, configured
533
+// elsewhere in this app.
534
//
535
-// This is a no-op certificate loader module that is treated as a special
536
-// case: it uses this app's automation features to load certificates for the
537
-// list of hostnames, rather than loading certificates manually.
535
+// Technically, this is a no-op certificate loader module that is treated as
536
+// a special case: it uses this app's automation features to load certificates
537
+// for the list of hostnames, rather than loading certificates manually.
538
type AutomateLoader []string
539
540
// CaddyModule returns the Caddy module information.
@@ -549,8 +549,7 @@ func (AutomateLoader) CaddyModule() caddy.ModuleInfo {
549
type CertCacheOptions struct {
550
// Maximum number of certificates to allow in the
551
// cache. If reached, certificates will be randomly
552
- // evicted to make room for new ones. Default: 0
553
- // (no limit).
552
+ // evicted to make room for new ones. Default: 10,000
553
Capacity int `json:"capacity,omitempty"`
554
}
555