From bbac50b4c86c19be80286f997fe11d8d69be8127 Mon Sep 17 00:00:00 2001 From: Monviech <79600909+Monviech@users.noreply.github.com> Date: Mon, 8 Apr 2024 15:11:21 +0200 Subject: [PATCH] Update caddy.rst - Add new fields for forward_auth support --- source/manual/how-tos/caddy.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/source/manual/how-tos/caddy.rst b/source/manual/how-tos/caddy.rst index 839f8650..0b9a7a81 100644 --- a/source/manual/how-tos/caddy.rst +++ b/source/manual/how-tos/caddy.rst @@ -25,7 +25,8 @@ Main features of this plugin: * Basic Auth to restrict access by username and password * Syslog-ng integration and HTTP Access Log * NTLM Transport -* Header manipulation with header_up and header_down +* Header manipulation with header_up, header_down and copy_headers +* forward_auth support for Authelia or Tailscale (nginx-auth) -------------- @@ -207,12 +208,13 @@ Option Description **Subdomain** Select a subdomain. This will put the handler on the subdomain instead of the domain. Use only with wildcard domains and subdomains. **Handle Type** `handle` or `handle path` can be chosen. If in doubt, always use `handle`, the most common option. `handle path` is used to strip the path from the URI. **Handle Path** Leave this empty to create a catch all location or enter a location like `/foo/*` or `/foo/bar*`. +**Handle Directive** In most cases, leaving this as "reverse_proxy" will be the best choice. "forward_auth" is an advanced scenario, read the documentation here: https://caddyserver.com/docs/caddyfile/directives/forward_auth **>Header** Header options -**Header Manipulation** Select one or multiple header manipulations. These will be set to this handler. Generally this is not needed. Setting a wrong configuration can be a security risk or break functionality. +**Header Manipulation** Select one or multiple header manipulations. These will be set to this handler. When using "forward_auth", a combination of "header_up" and "copy_headers" is also supported. **>Upstream** Upstream options **Upstream Domain** Should be an internal domain name or an IP Address of the upstream destination that should receive the reverse proxied traffic. **Upstream Port** Should be the port the upstream destination listens on. This can be left empty to use Caddy default port 80. -**Upstream Path** In case the backend application resides in a sub-path of the web root and its path shouldn't be visible in the frontend URL, this setting can be used to prepend an initial path starting with '/' to every backend request. Java applications running in a servlet container like Tomcat are known to behave this way, so set it to e.g. '/guacamole' to access Apache Guacamole at the frontend root URL without needing a redirect. +**Upstream Path** When using "reverse_proxy" (default), in case the backend application resides in a sub-path of the web root and its path shouldn't be visible in the frontend URL, this setting can be used to prepend an initial path starting with '/' to every backend request. Java applications running in a servlet container like Tomcat are known to behave this way, so set it to e.g. '/guacamole' to access Apache Guacamole at the frontend root URL without needing a redirect. When using "forward_auth" and "copy_headers" to send pre-check requests to an authentication provider, e.g. Authelia, enter an uri like: ``/api/verify?rd=https://auth.example.com``. **>Trust** Certificate options **TLS** If the upstream destination only accepts HTTPS, enable this option. If the upstream destination has a globally trusted certificate, this TLS option is the only needed one. **NTLM** If the upstream destination needs NTLM authentication, enable this option together with TLS. For example: Exchange Server. @@ -262,10 +264,10 @@ Reverse Proxy - Headers =========================== ================================ Option Description =========================== ================================ -**Header** ``header_up`` sets, adds (with the + prefix), deletes (with the - prefix), or performs a replacement (by using two arguments, a search and replacement) in a request header going upstream to the backend. ``header_down`` sets, adds (with the + prefix), deletes (with the - prefix), or performs a replacement (by using two arguments, a search and replacement) in a response header coming downstream from the backend. For more information: https://caddyserver.com/docs/caddyfile/directives/reverse_proxy#headers. -**Header Type** Enter a header, for example ``Host``. Use the ``+`` or ``-`` prefix to add or remove this header, for example ``-Host`` or ``+Host``. A suffix match like ``-Host-*`` is also supported. To replace a header, use ``Some-Header`` without ``+`` or ``-``. -**Header Value** Enter a value for the above header. One of the most common options is ``{upstream_hostport}``. It's also possible to use a regular expression to search for a specific value in a header. For example: ``^prefix-([A-Za-z0-9]*)$`` which uses the regular expression language RE2 included in Go. -**Header Replace** If a regular expression is used to search for a `Header Value`, here the replacement string can be set. For example: ``replaced-$1-suffix`` which expands the replacement string, allowing the use of captured values, ``$1`` being the first capture group. +**Header** ``header_up`` sets, adds (with the + prefix), deletes (with the - prefix), or performs a replacement (by using two arguments, a search and replacement) in a request header going upstream to the backend. ``header_down`` sets, adds (with the + prefix), deletes (with the - prefix), or performs a replacement (by using two arguments, a search and replacement) in a response header coming downstream from the backend. ``copy_headers`` is a list of HTTP header fields to copy from the response to the original request, when the request has a success status code. For more information: https://caddyserver.com/docs/caddyfile/directives/reverse_proxy#headers. +**Header Type** Enter a header, for example ``Host``. Use the ``+`` or ``-`` prefix to add or remove this header, for example ``-Host`` or ``+Host``. A suffix match like ``-Host-*`` is also supported. To replace a header, use ``Some-Header`` without ``+`` or ``-``. When using ``copy_headers``, input one header to copy here. For additional entries, create a new header entry. +**Header Value** Enter a value for the above header. One of the most common options is ``{upstream_hostport}``. It's also possible to use a regular expression to search for a specific value in a header. For example: ``^prefix-([A-Za-z0-9]*)$`` which uses the regular expression language RE2 included in Go. When using ``copy_headers``, leave this field empty. +**Header Replace** If a regular expression is used to search for a `Header Value`, here the replacement string can be set. For example: ``replaced-$1-suffix`` which expands the replacement string, allowing the use of captured values, ``$1`` being the first capture group. When using ``copy_headers``, optionally input the replacement for the copied header here. =========================== ================================ .. Attention:: Setting headers to handlers should be considered an advanced option for experts. Please don't set them without any reason. Caddy uses safe defaults. https://caddyserver.com/docs/caddyfile/directives/reverse_proxy#defaults