From 332a313edbe176f3d1958a0d65f435a393d40e86 Mon Sep 17 00:00:00 2001 From: Matt Holt Date: Mon, 4 Nov 2019 14:38:16 -0700 Subject: [PATCH] Update admin docs --- v2:-Documentation.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/v2:-Documentation.md b/v2:-Documentation.md index 65efd48..d7321b3 100644 --- a/v2:-Documentation.md +++ b/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) - [Admin endpoint](#admin-endpoint) - [POST /load](#post-load) + - [POST /unload](#post-unload) - [POST /stop](#post-stop) - [GET /config/[scope]](#get-configscope) - [POST /config/[scope]](#post-configscope) @@ -276,7 +277,7 @@ $ caddy reverse-proxy --from localhost:2015 --to https://example.com # 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` @@ -304,7 +305,7 @@ $ curl -X POST "http://localhost:2019/load" \ ## 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 @@ -845,15 +846,21 @@ At the top level, you'll find properties needed for Caddy's basic functionality: ## admin -Configures the administration endpoint. +Configures the administration endpoint, also known as the Caddy API. ```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. +- `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", "stacktrace_key": "stacktrace", "line_ending": "\n", - "time_format": "unix_seconds_float", + "time_format": "wall_milli", "duration_format": "seconds", "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_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. -- `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.port`: The port to use (if different) for health checks. -- `health_checks.active.interval`: How frequently to perform active health checks. -- `health_checks.active.timeout`: How long to wait for a response from a backend before considering it unhealthy. +- `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 (default 30s). +- `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.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.