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)

v2.4.0

Caddy v2.4.0 is our first stable release of 2021, ushering in over 110 patches including new features and bug fixes. Thank you to the many contributors who helped make this possible!

Highlights:

• Secure remote management. You can now enable secure remote access to Caddy's admin API! It uses TLS mutual authentication, and you can even define permissions for different users. PR #3994
• Config pull at start. Caddy can be configured to load a different config at startup. This is useful if your config is federated through a separate system that doesn't have the ability to push configs to Caddy. This feature is modular, so configurations can be loaded different ways! PR #3994
• Server identity management. Caddy can automatically manage its own server identity certificate, which can be used when negotiating TLS connections with peers. This is required when enabling the secure admin API. PR #3994
• Self-upgrade command. The new caddy upgrade command will replace the current Caddy binary with an upgraded one from our website, with all the same modules installed, including third-party plugins that are registered on our site! (We can use this code to add/remove modules later, too.)
• Configure other apps from the HTTP Caddyfile. The global options block of the Caddyfile now allows configuration of Caddy apps other than HTTP (for example, dynamic_dns to keep DNS records pointed at your server with a dynamic IP address).
• Caddyfile fmt lint check. When running with a Caddyfile, Caddy will emit a warning if the Caddyfile is not formatted with caddy fmt.
• New abort directive. The abort directive is a special case of the static_response HTTP handler that prevents an HTTP response by aborting the handler chain immediately and forcefully closing the connection.
• New error directive. The error directive returns internal error values in the HTTP handler chain, as if an HTTP error had occurred, causing your error routes to be invoked.
• Configure response interception from Caddyfile. The reverse_proxy is capable of intercepting responses from the backend, and now this is exposed in the Caddyfile with handle_response.
• Better caddy list-modules output. Now modules are organized by standard and non-standard modules, so you can easily see if a Caddy build has been customized.
• Configure logging from Caddyfile. The process logs can now be configured from the global options of the Caddyfile.
• Better content negotiation. The file server can now be configured to serve precompressed sidecar files, and content encoding preferences are better configured and honored.
• Dark mode in directory listings. The file server's "browse" file listings now has a dark mode.
• ⚠️ Removed the logfmt log encoder. It was broken anyways, and its deprecation has been warned in previous releases.
• ⚠️ Deprecated common_log format. It will be removed in a future release. Issue #4148
• ⚠️ Deprecated health_path in reverse_proxy directive. It has been replaced with health_uri and will be removed in the future.
• Numerous bug fixes and improvements. Thanks for the detailed, helpful bug reports! We appreciate your collaboration in making Caddy better.

New content for sponsors

I've started writing high-quality, in-depth chatpers about how to get the most out of Caddy in my new Expert Caddy series, exclusively for sponsors! If you or your company are sponsoring, you can have access to this content, which I'll continue adding to over time.

If you aren't sponsoring yet, please do so! Sponsorships fund my full-time development of Caddy, and that's especially vital if your business relies on Caddy.

Changelog (since RC 1)

For a detailed list of all commits since v2.3.0, please refer to prior pre-release changelogs.

bc22102 caddyfile: Fix caddy fmt nesting not decrementing (#4157)
d4b2f1b caddyhttp: Fix fallback for the error handler chain (#4131)
61642b7 caddytls: Run replacer on ask URL, for env vars (#4154)
7776471 encode: Default to order the formats are enabled for prefer in Caddyfile (#4151)
f5db41c encode: Drop prefer from Caddyfile (#4156)
74f5d66 fileserver: Fix file matcher with empty try_files (#4147)
3cf443f httpcaddyfile: Add grace_period global option (#4152)
a17c3b5 reverseproxy: Minor logging improvements