From 1ff0134570b817ff6930d1e50a404534e22b24ad Mon Sep 17 00:00:00 2001 From: Matthew Holt Date: Tue, 7 Apr 2020 07:46:08 -0600 Subject: [PATCH] docs: Clarifications about admin endpoint and reload command See https://github.com/caddyserver/caddy/issues/3234 --- src/docs/markdown/caddyfile/options.md | 2 +- src/docs/markdown/command-line.md | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md index 95cec56..ff7d326 100644 --- a/src/docs/markdown/caddyfile/options.md +++ b/src/docs/markdown/caddyfile/options.md @@ -52,7 +52,7 @@ Possible options are: - **acme_ca** specifies the URL to the ACME CA's directory. It is strongly recommended to set this to Let's Encrypt's [staging endpoint](https://letsencrypt.org/docs/staging-environment/) for testing or development. Default: Let's Encrypt's production endpoint. - **acme_ca_root** specifies a PEM file that contains a trusted root certificate for ACME CA endpoints, if not in the system trust store. - **email** is your email address. Mainly used when creating an ACME account with your CA, and is highly recommended in case there are problems with your certificates. -- **admin** customizes the [admin API endpoint](/docs/api). If `off`, then the admin endpoint will be disabled. +- **admin** customizes the [admin API endpoint](/docs/api). If `off`, then the admin endpoint will be disabled. If disabled, config changes will be impossible without stopping and starting the server. - **on_demand_tls** configures [On-Demand TLS](/docs/automatic-https#on-demand-tls) where it is enabled, but does not enable it (to enable it, use the [on_demand `tls` subdirective](/docs/caddyfile/directives/tls#syntax)). Highly recommended if using in production environments, to prevent abuse. - **ask** will cause Caddy to make an HTTP request to the given URL with a query string of `?domain=` containing the value of the domain name. If the endpoint returns 200 OK, Caddy will be authorized to obtain a certificate for that name. - **interval** and **burst** allows `` certificate operations within `` interval. diff --git a/src/docs/markdown/command-line.md b/src/docs/markdown/command-line.md index 674fe00..dcfb8fd 100644 --- a/src/docs/markdown/command-line.md +++ b/src/docs/markdown/command-line.md @@ -212,11 +212,13 @@ NOTE: Due to [a bug in Go](https://github.com/golang/go/issues/29228), version i Gives the running Caddy instance a new configuration. This has the same effect as POSTing a document to the [/load endpoint](/docs/api#post-load), but this command is convenient for simple workflows revolving around config files. Compared to the `stop`, `start`, and `run` commands, this single command is the correct, semantic way to change/reload the running configuration. +Because this command uses the API, the admin endpoint must not be disabled. + `--config` is the config file to apply. If not specified, it will try a file called `Caddyfile` in the current working directory and, if it exists, it will adapt it using the `caddyfile` config adapter; otherwise, it is an error if there is no config file to load. `--adapter` specifies a config adapter to use, if any. -`--address` needs to be used if the admin endpoint is not listening on the default address and if it is different from the address in the provided config file. +`--address` needs to be used if the admin endpoint is not listening on the default address and if it is different from the address in the provided config file. Note that only TCP addresses are supported at this time. @@ -257,7 +259,7 @@ Runs Caddy and blocks indefinitely; i.e. "daemon" mode. `--environ` prints out the environment before starting. This is the same as the `caddy environ` command, but does not exit after printing. -`--resume` uses the last loaded configuration. This flag is useful primarily in [API](/docs/api)-heavy deployments, and overrides `--config` if a saved config exists. +`--resume` uses the last loaded configuration, overriding the `--config` flag (if present) if a previous config was saved. Using this flag guarantees config durability through machine reboots or process restarts. It is most useful in [API](/docs/api)-heavy deployments. `--watch` will watch the config file and automatically reload it after it changes. ⚠️ This feature is dangerous in production! Only use it in a local development environment.