mirror of
https://github.com/caddyserver/caddy.git
synced 2025-08-07 09:04:04 -04:00
Updated v2: Documentation (markdown)
Matt Holt
parent
4e7ab4eabb
commit
70876007da
@ -29,6 +29,16 @@ Features which are available in Caddy Enterprise are indicated with 🏢
|
||||
- [caddy.storage.file_system]()
|
||||
- [apps]()
|
||||
- [http]()
|
||||
- [http/servers]()
|
||||
- [http/servers/listen]()
|
||||
- [http/servers/routes]()
|
||||
- [HTTP Placeholders]()
|
||||
- [http/servers/routes/match]()
|
||||
- [http/servers/apply]()
|
||||
- [http/servers/respond]()
|
||||
- [http/servers/errors]()
|
||||
- [http/servers/tls_conn_policies]()
|
||||
- [http/servers/auto_https]()
|
||||
- [tls]()
|
||||
|
||||
|
||||
@ -741,106 +751,177 @@ Example:
|
||||
|
||||
#### http/servers/errors
|
||||
|
||||
If a route returns an error, the error along with its recommended status code are bubbled back to the HTTP server which executes a separate error route, if specified. The error routes work exactly like the normal routes, making error handling very powerful and expressive.
|
||||
Specifies how to handle errors returned from the HTTP handlers.
|
||||
|
||||
If a handler returns an error, the error along with its recommended status code are bubbled back to the HTTP server which executes a separate error route, specified using this property. The error routes work exactly like the normal routes.
|
||||
|
||||
```json
|
||||
{
|
||||
"routes": []
|
||||
}
|
||||
```
|
||||
- `routes`: The routes to execute on error. Works just like normal HTTP routes.
|
||||
|
||||
In an error route, extra placeholders are available:
|
||||
|
||||
```
|
||||
{http.error.status_code}
|
||||
The recommended HTTP status code
|
||||
{http.error.status_text}
|
||||
The status text associated with the recommended status code
|
||||
{http.error.message}
|
||||
The error message
|
||||
{http.error.trace}
|
||||
The origin of the error
|
||||
{http.error.id}
|
||||
A short, human-conveyable ID for the error
|
||||
```
|
||||
|
||||
|
||||
#### http/servers/tls_conn_policies
|
||||
|
||||
TODO.
|
||||
|
||||
#### http/servers/auto_https
|
||||
|
||||
TODO.
|
||||
|
||||
--------------
|
||||
|
||||
TODO:
|
||||
An ordered list of policies which specify how to complete TLS handshakes when establishing an HTTPS connection. The first matching policy will be used.
|
||||
|
||||
Most users will not need this; it is an advanced configuration feature.
|
||||
|
||||
```json
|
||||
{
|
||||
"listen": [":8080"],
|
||||
"routes": [
|
||||
{
|
||||
"match": [{
|
||||
"host": ["example.com"],
|
||||
"path": ["/foo/bar", "*.ext"],
|
||||
"path_regexp": {
|
||||
"name": "myre",
|
||||
"pattern": "/foo/(.*)/bar"
|
||||
},
|
||||
"method": ["GET"],
|
||||
"query": {"param": ["value"]},
|
||||
"header": {"Field": ["foo"]},
|
||||
"header_regexp": {
|
||||
"Field": {
|
||||
"pattern": "foo(.*)-bar",
|
||||
"name": "other"
|
||||
},
|
||||
},
|
||||
"protocol": "grpc",
|
||||
"not": {
|
||||
"path": ["/foo/bar"],
|
||||
"...": "(any matchers in here will be negated)"
|
||||
},
|
||||
"remote_ip": {
|
||||
"ranges": ["127.0.0.1", "192.168.0.1/24"]
|
||||
},
|
||||
"starlark_expr": "req.host == 'foo.com' || (req.host != 'example.com' && req.host != 'sub.example.com')"
|
||||
}],
|
||||
"apply": [
|
||||
{
|
||||
"middleware": "rewrite",
|
||||
"method": "FOO",
|
||||
"uri": "/test/abc"
|
||||
},
|
||||
{
|
||||
"middleware": "headers",
|
||||
"response": {
|
||||
"set": {
|
||||
"Foo": ["bar"],
|
||||
"Regexp": ["{http.matchers.path_regexp.myre.0}"]
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"respond": {
|
||||
"responder": "static",
|
||||
"body": "Booyah: {http.request.method} {http.request.uri} Foo: {http.response.header.foo}"
|
||||
},
|
||||
"group": "exclusive",
|
||||
"terminal": true
|
||||
}
|
||||
],
|
||||
"errors": {
|
||||
"routes": [ ... ]
|
||||
},
|
||||
"tls_connection_policies": [
|
||||
{
|
||||
"match": {
|
||||
"host": ["example.com"]
|
||||
},
|
||||
"alpn": ["..."],
|
||||
"cipher_suites": ["..."],
|
||||
"certificate_selection": {
|
||||
"policy": "enterprise",
|
||||
"subject.organization": "O1",
|
||||
"tag": "company1"
|
||||
}
|
||||
}
|
||||
],
|
||||
"automatic_https": {
|
||||
"disabled": false,
|
||||
"disable_redirects": false,
|
||||
"skip": ["exclude", "these", "domains"],
|
||||
"skip_certificates": ["doesn't provision certs for these domains but still does redirects"]
|
||||
},
|
||||
"max_rehandles": 3
|
||||
}
|
||||
}
|
||||
"match": {},
|
||||
"alpn": [],
|
||||
"cipher_suites": [],
|
||||
"certificate_selection": {}
|
||||
}
|
||||
```
|
||||
|
||||
- `match`: Configures how to match this policy with a TLS ClientHello. If the policy matches, it will be used.
|
||||
- `alpn`: The ALPN value(s) to set.
|
||||
- `cipher_suites`: The list of cipher suites to support.
|
||||
- `certificate_selection`: Configures how to choose a certificate if more than one match the given ServerName (SNI) value.
|
||||
|
||||
#### http/servers/auto_https
|
||||
|
||||
Configures automatic HTTPS for this server. Automatic HTTPS consists of:
|
||||
|
||||
- Provisioning certificates
|
||||
- Renewing certificates
|
||||
- Configuring TLS listeners
|
||||
- Redirecting HTTP to HTTPS
|
||||
|
||||
Generally you will not need to change these settings; they are for advanced use.
|
||||
|
||||
```json
|
||||
{
|
||||
"disable": false,
|
||||
"disable_redirects": false,
|
||||
"skip": [],
|
||||
"skip_certificates": []
|
||||
}
|
||||
```
|
||||
|
||||
- `disable`: If true, automatic HTTPS will be completely disabled.
|
||||
- `disable_redirects`: If true, automatic HTTP->HTTPS redirects will be disabled, but automated certificate management will still be enabled.
|
||||
- `skip`: A list of hosts (domain names) to not include in automatic HTTPS.
|
||||
- `skip_certificates`: A list of hosts (domain names) to still enable automatic HTTPS for, except for managing certificates.
|
||||
|
||||
|
||||
### tls
|
||||
|
||||
Caddy's TLS app is an immensely powerful way to configure your server's security and privacy policies with regards to network connections. It enables you to load TLS certificates into the cache so they can be used to complete TLS handshakes. You can customize how certificates are managed or automated, and you can even configure how TLS session tickets are handled.
|
||||
|
||||
Most users will not need to configure the TLS app at all, since HTTPS is automatic and on by default.
|
||||
|
||||
The app is structured like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"certificates": {},
|
||||
"automation": {},
|
||||
"session_tickets": {}
|
||||
}
|
||||
```
|
||||
|
||||
- `certificates`: Caches certificates in memory for quick use during TLS handshakes. Each key is the name of a certificate loader module.
|
||||
- `automation`: Configures certificate automation.
|
||||
- `session_tickets`: Configures session ticket ephemeral keys (STEKs)
|
||||
|
||||
|
||||
#### tls/certificates
|
||||
|
||||
Configures how certificates are loaded into memory. There are several loader modules available.
|
||||
|
||||
|
||||
##### tls.certificates.load_files
|
||||
|
||||
Loads certificates and their keys from files. Is a list of objects which specify how to load each cert+key pair.
|
||||
|
||||
```json
|
||||
"load_files": [
|
||||
{
|
||||
"certificate": "",
|
||||
"key": "",
|
||||
"format": "pem",
|
||||
"tags": []
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
- `certificate`: The certificate file.
|
||||
- `key`: The private key file.
|
||||
- `format`: The format of the certificate and key. Values: pem
|
||||
- `tags`: Optionally associate this certificate with tags ( as strings) to keep track of them. Useful for advanced certificate selection.
|
||||
|
||||
|
||||
##### tls.certificates.load_folders
|
||||
|
||||
Load all certificates and keys that can be found in the specified folders. Certificates and key pairs should be bundled in the same `.pem` files. This is a quick way to load a bunch of certificates at once.
|
||||
|
||||
```json
|
||||
"load_folders": ["/folder1", "folder2"]
|
||||
```
|
||||
|
||||
- Simply specify the folder paths in the array.
|
||||
|
||||
##### tls.certificates.automate
|
||||
|
||||
A special case, this instructs the TLS app to automate certificates for the specified host/domain names. Certificates will be automated according to their matching automation policy.
|
||||
|
||||
```json
|
||||
"automate": ["example.com", "foo.example.com"]
|
||||
```
|
||||
|
||||
- Specify the names to automate certificates for in the array.
|
||||
|
||||
|
||||
##### tls.certificates.pem_loader
|
||||
|
||||
🏢 _Enterprise_
|
||||
|
||||
Loads certificate and key pairs directly as presented in the config, without needing to access disk. This allows you to securely transmit private keys without having to persist them to storage; you can keep them entirely in memory.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"certificate": "",
|
||||
"key": "",
|
||||
"tags": []
|
||||
}
|
||||
]
|
||||
```
|
||||
- `certificate`: The PEM encoding of the certificate.
|
||||
- `key`: The PEM encoding of the private key.
|
||||
- `tags`: Optionally associate this certificate with tags ( as strings) to keep track of them. Useful for advanced certificate selection.
|
||||
|
||||
|
||||
#### tls/automation
|
||||
|
||||
Configures TLS asset automation.
|
||||
|
||||
|
||||
TODO.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
# FIN
|
||||
@ -857,23 +938,8 @@ What follows is the original ad-hoc documentation that we sent some early tester
|
||||
TLS App
|
||||
=========
|
||||
|
||||
Caddy's TLS app is an immensely powerful way to configure your server's security and
|
||||
privacy policies. It enables you to load TLS certificates into the cache so they can
|
||||
be used to complete TLS handshakes. You can customize how certificates are managed or
|
||||
automated, and you can even configure how TLS session tickets are handled.
|
||||
|
||||
Most users will not need to configure the TLS app at all, since HTTPS is automatic
|
||||
and on by default.
|
||||
|
||||
TLS is structured like this:
|
||||
|
||||
```
|
||||
"tls": {
|
||||
"certificates": {},
|
||||
"automation": {},
|
||||
"session_tickets": {},
|
||||
}
|
||||
```
|
||||
|
||||
Here is a contrived example showing all fields:
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user