Cutlery/caddy
1
0
Fork 0
mirror of https://github.com/caddyserver/caddy.git synced 2025-07-09 03:04:57 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update admin docs

Matt Holt 2019-11-04 14:38:16 -07:00
parent d334704652
commit 332a313edb
1 changed files with 16 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
v2:-Documentation.md

@ -19,6 +19,7 @@ This page describes how to use Caddy 2, which is a work-in-progress on the [v2 b
- [reverse-proxy](#reverse-proxy) - [reverse-proxy](#reverse-proxy)
- [Admin endpoint](#admin-endpoint) - [Admin endpoint](#admin-endpoint)
- [POST /load](#post-load) - [POST /load](#post-load)
- [POST /unload](#post-unload)
- [POST /stop](#post-stop) - [POST /stop](#post-stop)
- [GET /config/[scope]](#get-configscope) - [GET /config/[scope]](#get-configscope)
- [POST /config/[scope]](#post-configscope) - [POST /config/[scope]](#post-configscope)
@ -276,7 +277,7 @@ $ caddy reverse-proxy --from localhost:2015 --to https://example.com
# Admin endpoint # Admin endpoint
Caddy is configured through an administration endpoint which is an HTTP listener with a REST API. Caddy is configured through an administration endpoint which is an HTTP listener with a REST API. You can [configure this admin endpoint](#admin) as part of the config structure.
Default address: `localhost:2019` Default address: `localhost:2019`
@ -304,7 +305,7 @@ $ curl -X POST "http://localhost:2019/load" \
## POST /stop ## POST /stop
Gracefully shuts down the server. Gracefully shuts down the server and exits the process. To only shut down the running configuration, use [`DELETE /config/`](#delete-configscope).
### Example ### Example
@ -845,15 +846,21 @@ At the top level, you'll find properties needed for Caddy's basic functionality:
## admin ## admin
Configures the administration endpoint. Configures the administration endpoint, also known as the Caddy API.
```json ```json
{ {
"listen": "localhost:2019" "disabled": false,
"listen": "localhost:2019",
"enforce_origin": false,
"origins": []
} }
``` ```
- `disabled`: If true, the admin endpoint will be completely disabled. Note that this makes any runtime changes to the config impossible, since the interface to do so is through the admin endpoint.
- `listen`: the address to which the admin endpoint's listener should bind itself. Can be [any single network address](#httpserverslisten) that can be parsed by Caddy. - `listen`: the address to which the admin endpoint's listener should bind itself. Can be [any single network address](#httpserverslisten) that can be parsed by Caddy.
- `enforce_origin`: If true, CORS headers will be emitted and requests to the admin API will be rejected if their Host and Origin headers do not match the expected value(s). If `origins` is not set, the `listen` address is the only value allowed by default. Use `origins` to customize which origins/hosts are allowed.
- `origins`: The list of allowed origins for API requests. Only used if `enforce_origin` is `true`. If not set, the listener address will be the default value. If set but empty, no origins will be allowed.
@ -980,7 +987,7 @@ In addition to the properties specific to each encoder, these properties are ava
"caller_key": "caller", "caller_key": "caller",
"stacktrace_key": "stacktrace", "stacktrace_key": "stacktrace",
"line_ending": "\n", "line_ending": "\n",
"time_format": "unix_seconds_float", "time_format": "wall_milli",
"duration_format": "seconds", "duration_format": "seconds",
"level_format": "color" "level_format": "color"
} }
@ -1887,11 +1894,11 @@ A highly flexible and configurable multi-host reverse proxy with load balancing,
- `load_balancing.try_duration`: How long to try selecting available backends for each request if the next available host is down. By default, this retry is disabled. Clients may hang for this long while the load balancer tries to find an available upstream host. - `load_balancing.try_duration`: How long to try selecting available backends for each request if the next available host is down. By default, this retry is disabled. Clients may hang for this long while the load balancer tries to find an available upstream host.
- `load_balancing.try_interval`: How long to wait between selecting the next host from the pool. Default is 250ms. Only relevant when a request to an upstream host fails. Be aware that setting this to 0 with a non-zero `try_duration` can cause the CPU to spin if all backends are down and latency is very low. - `load_balancing.try_interval`: How long to wait between selecting the next host from the pool. Default is 250ms. Only relevant when a request to an upstream host fails. Be aware that setting this to 0 with a non-zero `try_duration` can cause the CPU to spin if all backends are down and latency is very low.
- `load_balancing.retry_match`: A list of matcher sets that restricts with which requests retries are allowed. A request must match any of the given matcher sets in order to be retried if the connection to the upstream succeeded but the subsequent round-trip failed. If the connection to the upstream failed, a retry is always allowed. If unspecified, only GET requests will be allowed to be retried. Note that a retry is done with the next available host according to the load balancing policy. - `load_balancing.retry_match`: A list of matcher sets that restricts with which requests retries are allowed. A request must match any of the given matcher sets in order to be retried if the connection to the upstream succeeded but the subsequent round-trip failed. If the connection to the upstream failed, a retry is always allowed. If unspecified, only GET requests will be allowed to be retried. Note that a retry is done with the next available host according to the load balancing policy.
- `health_checks`: Configures active and passive health checks. Active health checks run in the background on a timer, whereas passive health checks monitor proxied requests. - `health_checks`: Configures active and passive health checks. Active health checks run in the background on a timer, whereas passive health checks monitor proxied requests. One of path or port must be set to enable them.
- `health_checks.active.path`: The URI path to use for health checks. - `health_checks.active.path`: The URI path to use for health checks.
- `health_checks.active.port`: The port to use (if different) for health checks. - `health_checks.active.port`: The port to use (if different from dial address) for health checks.
- `health_checks.active.interval`: How frequently to perform active health checks. - `health_checks.active.interval`: How frequently to perform active health checks (default 30s).
- `health_checks.active.timeout`: How long to wait for a response from a backend before considering it unhealthy. - `health_checks.active.timeout`: How long to wait for a response from a backend before considering it unhealthy (default 10s).
- `health_checks.active.max_size`: The maximum response body to download from the backend during a health check. - `health_checks.active.max_size`: The maximum response body to download from the backend during a health check.
- `health_checks.active.expect_status`: The HTTP status code to expect from a healthy backend. - `health_checks.active.expect_status`: The HTTP status code to expect from a healthy backend.
- `health_checks.active.expect_body`: A regular expression against which to match the response body of a healthy backend. - `health_checks.active.expect_body`: A regular expression against which to match the response body of a healthy backend.