v2.5.1

This is a minor patch release that fixes some bugs and also enhances reverse_proxy with capabilities that weren't ready in time for v2.5.0.

Highlights

• Fixed regression in Unix socket admin endpoints.
• Fixed regression in caddy trust commands.
• Hash-based load balancing policies (ip_hash, uri_hash, header, and cookie) use an improved highest-random-weight (HRW) algorithm for increased consistency. The new rendezvous hash will ensure a client or request is consistently mapped to a particular upstream even if the list of upstreams changes.
• The reverse proxy is now able to rewrite the method and URI on its internal copy of the request that goes to the upstream. Combined with new handle_response capabilities, this enables the reverse proxy to fire off "pre-check requests" (for lack of a better term) to make routing decisions based on the results of that call. This enables a commonly-emerging pattern called forward authentication wherein a backend is queried to assess a client's authorization to be proxied. The full, verbose config for this is very flexible but tedious, so we made a new wrapper directive called forward_auth that eliminates the boilerplate (very similar to the php_fastcgi directive):

forward_auth authelia:9091 {
	uri /api/verify?rd=https://auth.example.com
	copy_headers Remote-User Remote-Groups Remote-Name Remote-Email
}

This works with authentication providers like Authelia, and more.

What's Changed

• caddypki: Fix caddy trust command to use the correct API endpoint by @francislavoie in #4730
• reverseproxy: Improve hashing LB policies with HRW by @mholt in #4724
• Add missing backticks by @mahgoh in #4737
• caddyhttp: Improve listen addr error message for IPv6 by @francislavoie in #4740
• cmd: Fix unix socket addresses for admin API requests by @francislavoie in #4742
• logging: Use RedirectStdLog by @francislavoie in #4732
• logging: Implement rename filter, changes field key names by @francislavoie in #4745
• httpcaddyfile: Fix duplicate access log when debug is on by @francislavoie in #4746
• reverseproxy: Fix Caddyfile support for replace_status by @francislavoie in #4754
• templates: Add custom template function registration by @kroppt in #4757
• reverseproxy: Permit resolver addresses to not specify a port by @francislavoie in #4760
• caddyfile: Shortcut for remote_ip for private IP ranges by @francislavoie in #4753
• reverseproxy: Support performing pre-check requests by @francislavoie in #4739
• map: Prevent output destinations overlap with Caddyfile shorthands by @francislavoie in #4657

New Contributors

• @mahgoh made their first contribution in #4737

Changelog

• ec86a2f caddyfile: Shortcut for remote_ip for private IP ranges (#4753)
• dcc98da caddyhttp: Improve listen addr error message for IPv6 (#4740)
• d543ad1 caddypki: Fix caddy trust command to use the correct API endpoint (#4730)
• 2e4c091 cmd: Fix unix socket addresses for admin API requests (#4742)
• af73215 httpcaddyfile: Fix duplicate access log when debug is on (#4746)
• 0be3d99 logging: Implement rename filter, changes field key names (#4745)
• 3017b24 logging: Use RedirectStdLog to capture more stdlib logs (#4732)
• f7be0ee map: Prevent output destinations overlap with Caddyfile shorthands (#4657)
• 4a223f5 reverseproxy: Fix Caddyfile support for replace_status (#4754)
• 40b193f reverseproxy: Improve hashing LB policies with HRW (#4724)
• e7fbee8 reverseproxy: Permit resolver addresses to not specify a port (#4760)
• f6900fc reverseproxy: Support performing pre-check requests (#4739)
• e84e19a templates: Add custom template function registration (#4757)
• 3ab6483 templates: Add missing backticks in docs (#4737)

Full Changelog: v2.5.0...v2.5.1

v2.5.0

Caddy 2.5 introduces new features you'll love as well as a huge number of bug fixes and enhancements. Thank you to everyone who contributed!

Feel free to ask on the forum if you have any questions or feedback.

Highlights

• Reverse proxy: ✨ Dynamic upstreams, which is the ability to get the list of upstreams at every request (more specifically, every iteration in the proxy loop of every request) rather than just once at config-load time. Dynamic upstream modules can be plugged in to provide Caddy with the latest list of backends in real-time. Two standard modules have been implemented which can get upstreams from SRV and A/AAAA record lookups.
  • ⚠️ This deprecates the lookup_srv JSON field for upstreams (and srv+ scheme prefix in the Caddyfile), which will be removed in the future.
• Automatic HTTPS: Caddy will automatically try to get relevant certificates from the local Tailscale instance (if running with permission to access the Tailscale socket). This makes services running on a Tailscale network automatically available over trusted HTTPS with Caddy.
• Tracing: New OpenTelemetry integration with the tracing handler module and associated tracing directive.
• Reverse proxy: When using the response handlers, a new handler copy_response is available to copy the proxy's response back to the client, and copy_response_headers may be used to selectively copy header values from the proxy's response.
• API: Added new endpoints /pki/ca/<id> and /pki/ca/<id>/certificates for getting information about Caddy's managed CAs, including the chain of root and intermediate certificates.

Notable

• Reverse proxy: The X-Forwarded-Host header will now be automatically set, along with X-Forwarded-For and X-Forwarded-Proto.
• ⚠️ Reverse proxy: Incoming X-Forwarded-* headers will no longer be automatically trusted, to prevent spoofing. Now, trusted_proxies must be configured to specify a list of downstream proxies which are trusted to have sent good values. You only need to configure trusted proxies if Caddy is not the first server being connected to. For example, if you have Cloudflare in front of Caddy, then you should configure this with Cloudflare's list of IP ranges.
• Automatic HTTPS: Revoked certificates will be automatically replaced more reliably.
• Automatic HTTPS: Can now get certificates from Managers. As opposed to Issuers (such as the default ACME issuers) which give Caddy certificates to manage from a CSR, Managers give Caddy certificates to serve (rather than manage) during TLS handshakes.
• Automatic HTTPS: A DNS challenge domain override can be configured to delegate the solving of the challenge to a different domain.
• Automatic HTTPS: The DNS challenge propagation checks can now be delayed or disabled by setting propagation_delay or propagation_timeout to -1, respectively.
• Reverse proxy: The default dial timeout for the HTTP transport has been adjusted down to 3s (was 10s), which should allow for more easily configuring load balancing retries.
• Logging: HTTP access logs will now render empty values for often-sensitive HTTP headers such as Cookie, Authorization, and Proxy-Authorization. Logging such credentials is now opt-in with the log_credentials global option in the Caddyfile, or the server's logs > should_log_credentials field in JSON.
• Logging: Logs can now be filtered by query string parameters, cookie values, and regular expressions; and log values can be hashed. These features are useful for redacting sensitive information.
• Logging: Errors during request handling will now be logged at DEBUG level if the error was handled via errors routes (handle_errors in Caddyfile).
• ⚠️ Logging: Removed the deprecated common_log field from HTTP access logs, and the single_field encoder. If you relied on this, you may use the transform encoder plugin to encode logs in Common Log format.
• ⚠️ Logging: The remote_addr field has been replaced by remote_ip and remote_port fields in HTTP access logs, which split up the two parts of the remote address. This improves ease of use for some tooling which only expect an IP address, without a port.
• HTTP server: The vars matcher can now match on multiple possible values.
• HTTP server: Requests can now be assigned a random and unique UUID from the new {http.request.uuid} placeholder.
• HTTP server: New http_redirect listener wrapper which can be used to redirect HTTP requests that come in on a server listening for HTTPS requests to be redirected to https://.
• ⚠️ Caddyfile: Deprecated paths in site addresses. Prefer using path matchers within your site block instead.
• Caddyfile: New default_bind global option lets you specify the default interface all sockets should bind to.
• Caddyfile: New pki global option lets you configure the properties of the internal CAs managed by Caddy.
• Caddyfile: New method directive allows rewriting the request method via Caddyfile.
• ⚠️ Caddyfile: The reverse_proxy directive's handle_response subdirective has had its status replacement functionality moved to a new replace_status subdirective. This makes sure that the functionality of handle_response is not overloaded, and usage is clearer.
• Caddyfile: The map directive now casts outputs to the appropriate scalar type if possible (int, float, bool). If you need to force a string, you may use double quotes or backticks #4643.
• Caddyfile: New vars directive allows setting some variables during request handling for later use in another handler or matcher.
• Caddyfile: The Caddyfile adapter is now stricter about curly braces for block openers to try to prevent parsing ambiguities.
• Caddyfile: The caddy fmt CLI command now has a --diff option which lets you visually see the formatting differences.
• ⚠️ Admin: Renamed experimental property load_interval ➡️ load_delay for clarification, and improved dynamic config loading.

---

🛡️ Thanks to David Leadbeater for reporting a security vulnerability related to HTTP methods and metrics cardinality, which was fixed in this release.

New Contributors

• @adamburgess made their first contribution in #4460
• @12f23eddde made their first contribution in #4444
• @rayjlinden made their first contribution in #4023
• @GallopingKylin made their first contribution in #4522
• @ForestJohnson made their first contribution in #4534
• @VojtechVitek made their first contribution in #4535
• @Ikke made their first contribution in #4544
• @YourTechBud made their first contribution in #4603
• @BitWuehler made their first contribution in #4597
• @ttys3 made their first contribution in #4572
• @crccw made their first contribution in #4596
• @andriikushch made their first contribution in #4361
• @renbou made their first contribution in #4654
• @cuishuang made their first contribution in #4702

Changelog

• 2e46c2a admin, reverseproxy: Stop timers if canceled to avoid goroutine leak (#448...

v2.5.0-rc.1

Please see the release notes for v2.5.0. In fact, just use v2.5.0 instead.

Interim Changelog: v2.5.0-beta.1...v2.5.0-rc.1

v2.5.0-beta.1

Please see the release notes for v2.5.0-rc.1. In fact, just use v2.5.0-rc.1 instead.

Interim Changelog: v2.4.6...v2.5.0-beta.1

v2.4.6

This release contains bug fixes and minor enhancements, including one patch with potential security implications related to path matching.

Notable patches:

• Path matchers unescape/clean URI paths to normalize match space
• Fix regex matching in map handler

Notable enhancements:

• try_files can now accept =nnn (e.g. =404) to yield a status code instead of a file.
• Template actions httpError (stop eval and return HTTP error) and import (like include but changes template context) were added
• New placeholder {http.request.tls.client.certificate_der_base64}

Changelog

749e55c caddycmd: Add --keep-backup to upgrade commands (#4387)
062657d caddycmd: Add --skip-standard to list-modules command, quieter output (#4386)
be5f77e caddycmd: fix caddy validate/fmt help message (#4377)
907e2d8 caddyhttp: Add support for triggering errors from try_files (#4346)
cbb045a caddyhttp: Placeholder for client cert in DER + base64 format (#4241)
e7457b4 caddyhttp: Sanitize the path before evaluating path matchers (#4407)
837cdc5 caddyhttp: reverseproxy: clarify warning for -insecure (#4379)
24fda75 caddytls: Mark storage clean timestamp at end of routine (#4401)
a779e1b fastcgi: Fix Caddyfile parsing when handle_response is used (#4342)
3f2c3ec fastcgi: Implement try_files override in Caddyfile directive (#4347)
64f8b55 fileserver: Fix compression breaks using httpInclude (#4352) (#4358)
d3a0259 fileserver: Fix displayed file size if it is symlink (#4354)
0a5f7a6 fileserver: Make file listing links purple once visited (#4356)
a21d5a0 fileserver: Prevent focusing filter from scrolling on page load (#4393)
33c70f4 fileserver: properly handle escaped/non-ascii paths (#4332)
c4790d7 go.mod: Carefully upgrade some dependencies (fix #4251)
997e41d go.mod: Replace promptui with Apache-compatible fork (fix #4394)
f376a38 go.mod: Update ACMEz and CertMagic
a437206 headers: Canonicalize case in replace (fix #4330)
012d235 httpcaddyfile: Empty tls policy for internal http localhost (#4398)
0ffb222 httpcaddyfile: Preserve IPv6 addresses through normalization (fix #4381)
a2119c0 map: Fix 95c0350 (avoid repeated expansions)
95c0350 map: Fix regex mappings
3336faf reverseproxy: Log error at error level (fix #4360)
b092061 reverseproxy: Prevent copying the response if a response handler ran (#4388)
f73f55d reverseproxy: Sanitize scheme and host on incoming requests (#4237)
5fda961 templates: Add 'import' action (#4321)
16f7521 templates: Add tests for funcInclude and funcImport (#4357)
2392478 templates: Propagate httpError to HTTP response

v2.4.5

A hotfix for a regression introduced in v2.4.4 related to combining the encode and reverse_proxy directives. Please see the v2.4.4 release notes for a more complete changelog.

Changelog

9f6393c cmd: export CaddyVersion(), Commands() (#4316)
4ebf100 encode: ignore flushing until after first write (#4318)
46ab93b go.mod: Update CertMagic

v2.4.4

This release contains numerous bug fixes, updated dependencies, and QoL improvements.

Update: This release contains a known regression in the combination of encode and reverse_proxy modules; please use v2.4.5 instead.

Thanks to all contributors, and a special thanks to @francislavoie and @mohammed90 for their dedication in helping to maintain the project and help others.

Changelog

0bdb8aa acmeserver: Don't set host for directory links by default
2de7e14 acmeserver: Trim slashes from path prefix
c131339 admin: Implement load_interval to pull config on a timer (#4246)
a10910f admin: Sync server variables (fix #4260) (#4274)
51f125b caddyfile: Better error message for missing site block braces (#4301)
d74913f caddyfile: Error on invalid site addresses containing comma (#4302)
b6f5125 caddyfile: keep error chain info in Dispenser.Errf (#4233)
1c6c771 caddyhttp: Fix edgecase with auto HTTP->HTTPS logic (#4243)
42e140b caddyhttp: Fix incorrect determination of gRPC protocol (#4236)
c1cd192 caddyhttp: Updated the documentation for MatchQuery (#4295)
81e5318 caddytls: Remove "IssuerRaw" field
ce5a45d cmd: Fix paths when using an env file (#4296)
68c5c71 cmd: New add-package and remove-package commands (#4226)
9e333c3 cmd: use net.ErrClosed for matching returned error (#4289)
1b1e625 core: Unix ns and Unix ms time placeholders (#4280)
69c9144 encode: Tweak compression settings (#4215)
4245ceb fileserver: Add disable_canonical_uris Caddyfile subdirective (#4222)
191dc86 fileserver: Clarify docs about canonicalization
9e16e80 fileserver: Fix browse name_dir_first sorting (#4218)
885a9aa go.mod: Update dependencies (close #4216)
f43fd6f go.mod: Upgrade CertMagic to v0.14.4
84b906a go.mod: Upgrade some dependencies
ab32440 httpcaddyfile: Add shortcut for proxy hostport placeholder (#4263)
b3d35a4 httpcaddyfile: Don't put localhost in public APs (fix #4220)
569ecdb httpcaddyfile: Ensure hosts to skip for logs can always be collected (#4258)
bfbc459 httpcaddyfile: Improve unrecognized directive errors
403732c httpcaddyfile: Reorder some directives (#4311)
46d99ab logging: Add missing interface guards for replace filter (#4244)
124ba1b logging: Prep for common_log removal (#4149)
8a974a4 logging: Warn for deprecated single_field encoder
e6c29ce reverseproxy: Incorporate latest proxy changes from stdlib (#4266)
d882211 reverseproxy: Keep path to unix socket as dial address (#4232)
f70a757 reverseproxy: Remove redundant flushing (#4299)

v2.4.3

Guess what: this is our 100th release! 🎉 🥳 🎊

A bug fix for the bug fix, and a couple other bug fixes, including one security fix for PHP sites. We think all users should upgrade after giving it a whirl in their test environments. Please note some changes in this patch:

• ⚠️ In reverse_proxy, the max_idle_conns_per_host option has been removed (both Caddyfile and JSON). This may be a breaking change for a few of you, but it only breaks configs that relied on a bug. Instead of silently failing, you will get an error if you continue using the property. For Caddyfile, we basically renamed the property to keepalive_idle_conns_per_host. In JSON, we simply removed the property, and you should instead set keep_alive/max_idle_conns_per_host if you weren't already. Previously, the Caddyfile subdirective set both MaxConnsPerHost and MaxIdleConnsPerHost, which was confusing; and the JSON properties overwrote each other, so one was removed. Issue #4201.
• 🛡️ Security patch in the FastCGI transport that now sanitizes paths against directory traversal outside the site root. PR #4207.
• 🐛 Fix canonicalization redirects in file_server. v2.4.2 introduced a bugfix (#4179) for these redirects when used inside handle_path (i.e. rewriting the path by stripping a prefix), but caused a regression for many other use cases. This release includes a proper fix for all known, tested cases. Basically: these redirects are not issued if the filename of a path was rewritten internally. Issue #4205.

Changelog

9d4ed3a caddyhttp: Refactor and export SanitizedPathJoin for use in fastcgi (#4207)
e8ae80a fileserver: Don't persist parsed template (fix #4202)
fbd6560 fileserver: Only redirect if filename not rewritten (fix #4205)
32c284b reverseproxy: Adjust test related to #4201
7c68809 reverseproxy: Fix overwriting of max_idle_conns_per_host (closes #4201)

v2.4.2

A few enhancements and bug fixes. Thanks to all who contributed to this release!

Changelog

323ffd2 admin: Replace admin cert cache when reloading (fix #4184)
4c2da18 caddytls: Add Caddyfile support for propagation_timeout (#4178)
76913b1 fileserver: Fix browse not redirecting query parameters (#4196)
f9b5445 fileserver: Redirect within the original URL (#4179)
ecd5eea go.mod: Update direct dependencies
89aa3a5 go.mod: Use CertMagic v0.14.0 (fix #4191)
1e92258 httpcaddyfile: Add preferred_chains global option and issuer subdirective (#4192)
658772f httpcaddyfile: Add skip_install_trust global option (#4153)
05656a6 httpcaddyfile: Don't add HTTP hosts to TLS APs (fix #4176 and fix #4198)
94b7120 logging: Actually use level_key (#4189)
7b500e7 metrics: use buildinfo collector from new collectors pkg (#4187)
2a81094 reverseproxy: Always remove hop-by-hop headers

v2.4.1

A small patch release that contains a few noncritical but pleasant fixes (unless you're using /id/ endpoints in the admin API; then you should definitely get this update).

Changelog

7f26a6b admin: Reinstate internal redirect for /id/ requests
b82db99 caddyfile: Add parse error on site address with trailing { (#4163)
2aefe15 cmd: upgrade: inherit the permissions of the original executable (#4160)
dbe164d httpcaddyfile: Fix automation policy consolidation again (fix #4161)
e3c369d logging: Implement dial timeout for net writer (fix #4083) (#4172)
aef8d4d reverseproxy: Set the headers in the replacer before handle_response (#4165)