From 57b3739a210226b0fdbcc4d3e006f2a405e0f853 Mon Sep 17 00:00:00 2001 From: Matthew Holt Date: Wed, 17 Feb 2021 11:34:28 -0700 Subject: [PATCH] docs: Various updates for 2.3, 2.4 beta, and Go 1.16 Steps on #139 (sorry) --- src/docs/markdown/caddyfile/directives.md | 1 + .../markdown/caddyfile/directives/abort.md | 22 +++++++++++++++++++ .../caddyfile/directives/acme_server.md | 9 ++++++-- src/docs/markdown/caddyfile/directives/tls.md | 2 ++ src/docs/markdown/caddyfile/options.md | 6 ++--- src/docs/markdown/command-line.md | 19 ++++++++++++++++ src/docs/markdown/install.md | 10 +++++++++ src/download.html | 3 ++- 8 files changed, 66 insertions(+), 6 deletions(-) create mode 100644 src/docs/markdown/caddyfile/directives/abort.md diff --git a/src/docs/markdown/caddyfile/directives.md b/src/docs/markdown/caddyfile/directives.md index 270449b..26e5670 100644 --- a/src/docs/markdown/caddyfile/directives.md +++ b/src/docs/markdown/caddyfile/directives.md @@ -8,6 +8,7 @@ The following directives come standard with Caddy, and can be used in the HTTP C Directive | Description ----------|------------ +**[abort](/docs/caddyfile/directives/abort)** | Aborts the HTTP request **[acme_server](/docs/caddyfile/directives/acme_server)** | An embedded ACME server **[basicauth](/docs/caddyfile/directives/basicauth)** | Enforces HTTP Basic Authentication **[bind](/docs/caddyfile/directives/bind)** | Customize the server's socket address diff --git a/src/docs/markdown/caddyfile/directives/abort.md b/src/docs/markdown/caddyfile/directives/abort.md new file mode 100644 index 0000000..601ace8 --- /dev/null +++ b/src/docs/markdown/caddyfile/directives/abort.md @@ -0,0 +1,22 @@ +--- +title: abort (Caddyfile directive) +--- + +# abort + +Prevents any response to the client by immediately aborting the HTTP handler chain and closing the connection. Any concurrent, active HTTP streams on the same connection are interrupted. + + +## Syntax + +```caddy-d +abort [] +``` + +## Examples + +Abort all requests for paths starting with `/foo`: + +```caddy-d +abort /foo* +``` diff --git a/src/docs/markdown/caddyfile/directives/acme_server.md b/src/docs/markdown/caddyfile/directives/acme_server.md index e46a766..d8802d3 100644 --- a/src/docs/markdown/caddyfile/directives/acme_server.md +++ b/src/docs/markdown/caddyfile/directives/acme_server.md @@ -11,11 +11,16 @@ When enabled, requests matching the path `/acme/*` will be handled by the ACME s ## Client configuration -Using ACME server defaults, ACME clients should simply be configured to use `https://localhost/acme/local/directory` as their ACME endpoint. (`local` is the name of Caddy's default CA.) +Using ACME server defaults, ACME clients should simply be configured to use `https://localhost/acme/local/directory` as their ACME endpoint. (`local` is the ID of Caddy's default CA.) ## Syntax ```caddy-d -acme_server [] +acme_server [] { + ca +} ``` + +- **ca** specifies the ID of the certificate authority with which to sign certificates. The default is `local`, which is Caddy's default CA, intended for locally-used, self-signed certificates, which is most common in dev environments. For broader use, it is recommended to specify a different CA to avoid confusion. If the CA with the given ID does not already exist, it will be created. + diff --git a/src/docs/markdown/caddyfile/directives/tls.md b/src/docs/markdown/caddyfile/directives/tls.md index 7eb960c..696933e 100644 --- a/src/docs/markdown/caddyfile/directives/tls.md +++ b/src/docs/markdown/caddyfile/directives/tls.md @@ -107,6 +107,7 @@ Obtains certificates using the ACME protocol. test_dir email timeout + key_type ed25519|p256|p384|rsa2048|rsa4096 disable_http_challenge disable_tlsalpn_challenge alt_http_port @@ -122,6 +123,7 @@ Obtains certificates using the ACME protocol. - **test_dir** is an optional fallback directory to use when retrying challenges; if all challenges fail, this endpoint will be used during retries; useful if a CA has a staging endpoint where you want to avoid rate limits on their production endpoint. Default: `https://acme-staging-v02.api.letsencrypt.org/directory` - **email** is the ACME account contact email address. - **timeout** is how long to wait before timing out an ACME operation. +- **key_type** is the type of key to use when generating CSRs. Only set this if you have a specific requirement. - **disable_http_challenge** will disable the HTTP challenge. - **disable_tlsalpn_challenge** will disable the TLS-ALPN challenge. - **alt_http_port** is an alternate port on which to serve the HTTP challenge; it has to happen on port 80 so you must forward packets to this alternate port. diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md index 063c4fc..65ccff9 100644 --- a/src/docs/markdown/caddyfile/options.md +++ b/src/docs/markdown/caddyfile/options.md @@ -41,7 +41,7 @@ Possible options are: acme_ca acme_ca_root acme_eab - acme_dns + acme_dns ... on_demand_tls { ask interval @@ -121,7 +121,7 @@ Specifies a PEM file that contains a trusted root certificate for ACME CA endpoi Specifies an External Account Binding to use for all ACME transactions. ##### `acme_dns` -Configures the DNS challenge to use for all ACME transactions. +Configures the ACME DNS challenge provider to use for all ACME transactions. The tokens following the name of the provider set up the provider the same as if specified in the [`tls` directive's `acme` issuer](/docs/caddyfile/directives/tls#acme). ##### `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. @@ -134,7 +134,7 @@ Configures [On-Demand TLS](/docs/automatic-https#on-demand-tls) where it is enab Specifies the type of key to generate for TLS certificates; only change this if you have a specific need to customize it. ##### `cert_issuer` -Defines the issuer (or source) of TLS certificates. +Defines the issuer (or source) of TLS certificates. The tokens following the name of the issuer set up the issuer the same as if specified in the [`tls` directive](/docs/caddyfile/directives/tls#issuer). diff --git a/src/docs/markdown/command-line.md b/src/docs/markdown/command-line.md index 2f492d9..9cfd4a2 100644 --- a/src/docs/markdown/command-line.md +++ b/src/docs/markdown/command-line.md @@ -119,6 +119,13 @@ To adapt a Caddyfile to JSON that you can easily read and tweak manually: +### `caddy build-info` + +
caddy build-info
+ +Prints information provided by Go about the build (main module path, package versions, replacements). + + ### `caddy environ` @@ -201,6 +208,7 @@ Prints CLI help text, optionally for a specific subcommand, then exits. ### `caddy list-modules` 
caddy list-modules
+	[--packages]
 	[--versions]
Prints the Caddy modules that are installed, optionally with package and/or version information from their associated Go modules, then exits. @@ -337,6 +345,17 @@ Untrusts a root certificate from the local trust store(s). Intended for developm +### `caddy upgrade` + +
caddy upgrade
+ +Replaces the current Caddy binary with the latest version from [our download page](https://caddyserver.com/download) with the same modules installed, including all third-party plugins that are registered on the Caddy website. + +Upgrades do not interrupt running servers; currently, the command only replaces the binary on disk. This might change in the future if we can figure out a good way to do it. + +The upgrade process is fault tolerant; the current binary is backed up first and automatically restored if anything goes wrong. + +This command may require elevated privileges if your user does not have permission to write to the executable file. ### `caddy validate` diff --git a/src/docs/markdown/install.md b/src/docs/markdown/install.md index ead42ae..56be2ed 100644 --- a/src/docs/markdown/install.md +++ b/src/docs/markdown/install.md @@ -25,6 +25,7 @@ This page describes various methods for installing Caddy on your system. - [Homebrew](#homebrew) - [Webi](#webi) - [Chocolatey](#chocolatey) +- [Ansible](#ansible) ## Static binaries @@ -183,3 +184,12 @@ _Note: This is a community-maintained installation method._ 
choco install caddy
[**View the Chocolatey package**](https://chocolatey.org/packages/caddy) + + +## Ansible + +_Note: This is a community-maintained installation method._ + +
ansible-galaxy install nvjacobo.caddy
+ +[**View the Ansible role repository**](https://github.com/nvjacobo/caddy) diff --git a/src/download.html b/src/download.html index 2a59dc3..7cabea6 100644 --- a/src/download.html +++ b/src/download.html @@ -42,7 +42,8 @@ - + +