Skip to content

Releases: caddyserver/caddy


07 May 16:53
Choose a tag to compare
v2.8.0-beta.2 Pre-release

Caddy 2.8 is (almost) here! We've made a ton of improvements and fixes and implemented some pretty awesome new features based on your feedback.

Thank you to our sponsors and everyone in the community who contributed! We couldn't have done it without your help. In particular, we'd like to recognize sponsors Stripe, Framer, and ZeroSSL for their positive influence which have greatly enhanced the project.

We've had a lot of documented-deprecated code in place for a long time now, so this version introduces a few more breaking changes than usual; please review the notes below.

This is a beta release, so expect some rough edges. Test in staging before deploying to production, but please try it out! As usual, please file bugs for any issues you encounter. Thank you and have a great day!

⚠️ Breaking changes:

  • ZeroSSL (#6229) (this is one overall change, but requires some explanation):
    • Up to now, Caddy used both Let's Encrypt and ZeroSSL by default to get certificates without any configuration. In 2.8, this is changing slightly. Due to upcoming changes to ZeroSSL accounting policies, ZeroSSL now requires your email address to be able to access their free ACME endpoint.
    • As such, Caddy will only implicitly add the ZeroSSL issuer to your config if you provide an email address in your Caddyfile using the email global option. (We have already recommended this for years.) If you already do this, you don't have to make any changes and you'll still get Let's Encrypt and ZeroSSL automatically as defaults.
    • If you use JSON to configure certificate automation policies, you will need to ensure you use the acme issuer with your email filled out, and the ca field set to ZeroSSL's ACME server URL.
    • The zerossl issuer module is no longer ACME-capable and is now exclusively for the ZeroSSL API. An API key from your ZeroSSL account is required. (The ZeroSSL ACME server can still be used with the acme module pointed to ZeroSSL's ACME server. You can provide your account email and/or EAB as well.) If you were using the ZeroSSL issuer with an API key, it will now start using ZeroSSL's API, which was probably the expected behavior anyways. The API has several advantages over the ACME endpoint, but may require payment:
      • Faster response times
      • IP certificates
      • Management tools in your ZeroSSL account dashboard
      • Technical support
    • To clarify, Let's Encrypt is still a default issuer even if you don't provide an email address (but we have always strongly recommended to do so).
    • You can still use ZeroSSL's ACME endpoint with your own External Account Binding (EAB) credentials.
    • See notes in #6229 for some examples and further explanations.
  • Removed support for the lego_deprecated DNS provider module. It has been deprecated for 4 years. Use caddy-dns modules instead; there are over 50 to choose from already. They are more flexible, compile much leaner, and are easier to implement and support. If yours is not supported it can be easily implemented. Sponsors at or above the Business tier can request to have their provider implemented for free.
  • On-demand TLS: The ask option in the JSON has been deprecated in favor of a permission module (Caddyfile unchanged) (#6055), and Caddyfile support for permission modules is added (6a02999)
  • Admin API: Etag (used for concurrency control) is now a header, not a trailer. This is less efficient, but virtually no clients properly implement trailer support.
  • For consistency, the basicauth Caddyfile directive has been renamed to basic_auth (#6092), and skip_log has been renamed to log_skip (#6066).
  • The basic_auth handler no longer supports scrypt (deprecated for over a year) (#6091)
  • The forwarded option has been deprecated for a long time and has now been removed from the remote_ip matcher (#6085)
  • Reverse proxy: The buffer_requests, buffer_responses, and max_buffer_size settings have been removed after being deprecated for 14 months. Use request_buffers and response_buffers instead if you need buffering.

Notable changes:

  • http: New fs directive can declare a file system plugin to use (#5057)
  • http: Sensitive headers in the logs are now replaced with ["REDACTED"] instead of empty array. (#5669)
  • http: Several improvements to size logging, websockets, flushing, 1xx statuses, and QUIC. (#6173, #6175, #6202, #6150, #6164, #6168)
  • http: Can now write access logs for a hostname to more than one logger (#6088)
  • http: The log_append handler can add fields to the access logs (#6066)
  • http: Add uuid field to access logs when the {http.request.uuid} placeholder is used (#5859)
  • http: Changed PROXY protocol libraries add TLV support (#5915)
  • caddyfile: Plugin authors can now specify a default ordering for directives, making manual ordering by users less necessary (#5865)
  • replacer: A new {file.*} global placeholder is available, where * is a path to a file on disk which contains a value (generally used for secrets) (#5463)
  • root, rewrite: A * matcher token is no longer required in the Caddyfile (#5844)
  • encode: More media types are now compressed by default (#6081)
  • encode: Modify ETag when encoding to comply with RFC 9110 section 8.8.3 (#5849)
  • encode: Configurable compression level for zstd (#6140)
  • uri: Can now perform structured query rewrites with uri query (#6120, #6165)
  • cmd: The --adapter flag is not needed for config files ending with .caddyfile (#5919)
  • file_server: The browse feature can now return a plaintext response (useful for terminals) (#6093)
  • file_server: File listings can dereference symlinks if enabled (#5973)
  • file_server: Directory listings now include total file size (#6003)
  • file_server: Can use precomputed ETags from sidecar files (#6222)
  • reverse_proxy: Active health checks can now be configured with consecutive passes/fails to change status (#6154)
  • reverse_proxy: A forward proxy can now be specified in config other than a single env var (#6114)
  • reverse_proxy: Configurable trusted root CAs is now modular (#6065)
  • reverse_proxy: SRV upstreams now support failovers/grace period with cache (#5832)
  • reverse_proxy: TLS curves can now be configured (potential preparation for post-quantum) (#5851)
  • handle_errors: Handling can now be filtered by response status code more easily (#5965)
  • tls: Client authentication validation methods are now modular/pluggable (#6050)
  • tls: Trusted CA providers are now modular (#5784)
  • tls: New local_ip connection matcher (#6074)
  • tls: Improvements and fixes when certificate managers are configured (#6229)
  • tls: Refactor the On-Demand TLS ask endpoint into a permission module, making it pluggable (#6055)
  • tls: Storage cleaning is now synced across instances that share the storage (#5940)
  • tls: Supports ACME Renewal Information (ARI) draft spec, together with cert lifetime and OCSP/revocation status, to trigger certificate renewals
  • acme_server: Configurable allow/deny policies (#5796)
  • acme_server: Specify allowed challenge types (#5794)


  • ac0ad4d Upgrade acmeserver to (#5913)
  • 931656b acmeserver: add policy field to define allow/deny rules (#5796)
  • e1aa862 acmeserver: support specifying the allowed challenge types (#5794)
  • 4a0492f admin: Make Etag a header, not a trailer (#6208)
  • 1217449 admin: Use xxhash for etag (#6207)
  • 7e2510e build(deps): bump golangci/golangci-lint-action from 4 to 5 (#6289)
  • 4f3f6e3 build(deps): bump actions/setup-go from 4 to 5 (#6012)
  • 8a50f19 build(deps): bump actions/upload-artifact from 3 to 4 (#6013)
  • 1bf72db build(deps): bump from 0.16.0 to 0.17.0 (#5994)
  • 223f314 build(deps): bump peter-evans/repository-dispatch from 2 to 3 (#6080)
  • 30d6364 caddyauth: Drop support for scrypt (#6091)
  • f9e1115 caddyauth: Rename basicauth to basic_auth (#6092)
  • f4840cf caddyconfig: Use empty struct instead of bool in map (close #6224) (#6227)
  • c0273f1 caddyfile: Add heredoc support to fmt command (#6056)
  • d9aded0 caddyfile: Allow heredoc blank lines (#6051)
  • 8bbf8ec caddyfile: Assert having a space after heredoc marker to simply check (#6117)
  • c369df5 caddyfile: Correctly close the heredoc when the closing marker appears immediately (#6062)
  • 1f60328 caddyfile: Fix variadic placeholder false positive when token contains : (#5883)
  • 750d0b8 caddyfile: Normalize & flatten all unmarshalers (#6037)
  • 9cd472c caddyfile: Populate regexp matcher names by default (#6145)
  • b893c8c caddyfile: Reject directives in the place of site addresses (#6104)
  • e7a534d caddyfile: Reject long heredoc markers (#6098)
  • 7c48b5f caddyfile: Switch to slices.Equal for better performance (#6061)
  • 63d597c caddyhttp: Accept XFF header values with ports, when parsing client IP (#6183)
  • 3d7d60f caddyhttp: Add uuid to access logs when used (#5859)
  • 45132c5 caddyhttp: Add plaintext response to file_server browse (#6093)
  • 6d97d8d caddyhttp: Address some Go 1.20 features (#6252)
  • 4c10a05 caddyhttp: Adjust scheme placeholder docs (#5910)
  • 97a56d8 caddyhttp: Allow header replacement with empty string (#6163)
  • 83ef61d caddyhttp: Apply auto HTTPS redir to all interfaces (fix #6226)
  • 2fc620d caddyhttp: F...
Read more

v2.8.0 beta 1

01 May 00:27
Choose a tag to compare
v2.8.0 beta 1 Pre-release

This release is obsolete. Please see the next release for the notes.


08 Dec 01:03
Choose a tag to compare

In this version we've made several fixes and enhancements with help from several contributors. Most changes are small, but some notable ones:

  • The templates middleware is now officially extensible (experimentally). This means modules can add custom functions/actions for templates to execute.
  • TLS storage cleaning is now synchronized across the cluster and remembered across restarts. This should greatly lower costs for expensive storage backends like DynamoDB.
  • Placeholders are now evaluated in config for certificate loaders.
  • Numerous bug fixes.

Thank you to everyone who contributed!


  • 65c489a Upgrade acmeserver to (#5913)
  • ae5e2d9 caddyfile: Fix variadic placeholder false positive when token contains : (#5883)
  • db55da5 caddyhttp: Adjust scheme placeholder docs (#5910)
  • df5edf6 caddytls: Context to DecisionFunc (#5923)
  • 6d9a833 caddytls: Sync distributed storage cleaning (#5940)
  • 11a082c cmd: Add newline character to version string in CLI output (#5895)
  • 979c413 cmd: upgrade: resolve symlink of the executable (#5891)
  • 6482070 core: Apply SO_REUSEPORT to UDP sockets (#5725)
  • 15adb89 core: quic listener will manage the underlying socket by itself (#5749)
  • 801ec75 fileserver: Add .m4v for browse template icon
  • b809ed7 go.mod: CVE-2023-45142 Update opentelemetry (#5908)
  • b4c7313 go.mod: Upgrade quic-go to v0.39.1
  • 36fce3f go.mod: update quic-go version to v0.40.0 (#5922)
  • ec2de22 httpcaddyfile: Fix TLS automation policy merging with get_certificate (#5896)
  • f0ea489 httpcaddyfile: Remove port from logger names (#5881)
  • 87f63b1 httpredirectlistener: Only set read limit for when request is HTTP (#5917)
  • 16834d6 templates: Clarify include args docs, add .ClientIP (#5898)
  • 0259853 templates: Delete headers on httpError to reset to clean slate (#5905)
  • 2f7ceb5 templates: Offically make templates extensible (#5939)
  • 908e956 tls: accept placeholders in string values of certificate loaders (#5963)

Full Changelog: v2.7.5...v2.7.6


11 Oct 22:27
Choose a tag to compare

In this release, we've fixed quite a few small bugs and annoyances, including HTTP/2 Rapid Reset which affected most HTTP/2 implementations.

On a personal note (from @mholt): I recently became a dad! I want to thank our maintainers for helping in so many ways while I've been taking extra time for family. Francis, Matthew, Mohammed, and others -- including all the contributors below, and then some -- are to thank for shipping this release.


  • Updated from v0.37.5 to v0.39.0, including many performance improvements. GSO and ECN are now enabled by default, but you may turn them off by setting the QUIC_GO_DISABLE_GSO=true and QUIC_GO_DISABLE_ECN=true environment variables respectively, if they cause you problems. See the quic-go release notes for more details.
  • The file server's fileserver.BrowseTemplate is now exported, so it may be customized by programs embedding Caddy. (ed8bb13)
  • Environment variables loaded with --envfile no longer override existing variables. (#5803)
  • The encode handler now compresses application/wasm* content types by default. (#5869)
  • The reverse_proxy handler can now emit very detailed logs for debugging streaming and buffering. To enable it, set the verbose_logs subdirective, and set logging to debug level. Since the logs from this are very noisy, using verbose_logs to opt-in is necessary. We may ask you to enable this when asking for support! (#5793)
  • You can now check the version with caddy -v, like most other CLI utilities! (#5874)

Caddy is on feature freeze until after 2.8 so we can improve our testing situation. These patches have all been tried to ensure they work as intended, but if you notice any issues please report them!


  • 0e204b7 admin: Respond with 4xx on non-existing config path (#5870)
  • 89c407a build(deps): bump actions/checkout from 3 to 4 (#5846)
  • 1405683 build(deps): bump goreleaser/goreleaser-action from 4 to 5 (#5847)
  • 38a7b6b caddyfile: Adjust error formatting (#5765)
  • 7103ea0 caddyfile: Fix case where heredoc marker is empty after newline (#5769)
  • 10053f7 caddyfile: Loosen heredoc parsing (#5761)
  • 58ab3a0 caddyhttp: Use LimitedReader for HTTPRedirectListener (thank you to Bartek Nowotarski for reporting)
  • 9c419f1 cmd: Fix exiting with custom status code, add caddy -v (#5874)
  • f2ab709 cmd: Prevent overwriting existing env vars with --envfile (#5803)
  • e0aaefa encode: Add application/wasm* to the default content types (#5869)
  • fa5a579 fileserver: Add command shortcuts -l and -a (#5854)
  • ed8bb13 fileserver: Export BrowseTemplate
  • 130f6d1 fileserver: Set canonical URL on browse template (#5867)
  • a306c5f fileserver: browse template SVG icons and UI tweaks (#5812)
  • 0a6d333 fileserver: docs: clarify the ability to produce JSON array with browse (#5751)
  • 82c356f fix: caddytest.AssertResponseCode error message (#5853)
  • 888c6d7 go.mod: Update quic-go to v0.38.0 (#5772)
  • 88b4fbf go.mod: Upgrade dependencies incl. x/net/http
  • df99502 httpcaddyfile: Enable TLS for catch-all site if tls directive is specified (#5808)
  • 33d8d2c httpcaddyfile: Sort TLS SNI matcher for deterministic JSON output (#5860)
  • 288216e httpcaddyfile: Stricter errors for site and upstream address schemes (#5757)
  • 2cac3c5 httpcaddyfile: fix placeholder shorthands in named routes (#5791)
  • c46ec3b logging: Clone array on log filters, prevent side-effects (#5786)
  • 1b73e38 logging: query filter for array of strings (#5779)
  • 4776f62 replacer: change timezone to UTC for "" placeholders (#5774)
  • a8586b0 reverseproxy: Add logging for dynamic A upstreams (#5857)
  • 3a3182f reverseproxy: Add more debug logs (#5793)
  • 4feac4d reverseproxy: Allow fallthrough for response handlers without routes (#5780)
  • e8b8d4a reverseproxy: Fix least_conn policy regression (#5862)
  • 2a6859a reverseproxy: Fix retries on "upstreams unavailable" error (#5841)
  • 05dbe1c reverseproxy: Replace health header placeholders (#5861)
  • 1e0dea5 reverseproxy: fix nil pointer dereference in AUpstreams.GetUpstreams (#5811)
  • b245ecd reverseproxy: fix parsing Caddyfile fails for unlimited request/response buffers (#5828)
  • 5653c36 templates: Add dummy RemoteAddr to httpInclude request, proxy compatibility (#5845)
  • 289934f tls: Add X25519Kyber768Draft00 PQ "curve" behind build tag (#5852)

New Contributors

Full Changelog: v2.7.4...v2.7.5


17 Aug 18:20
Choose a tag to compare

Caddy 2.7.4 rounds out some bug fixes from the 2.7 release. For example, Go made a last-minute breaking change to a new API that broke quic-go (HTTP/3) on Go 1.21 just before Go 1.21 was released; we resolved a few issues with on-demand TLS that are now much improved from the 2.6 tree; a couple race conditions were fixed in dynamic reverse proxy upstreams. We hope you will be pleased with this new version!

Caddy is on feature freeze until after 2.8 so we can improve our testing situation. These patches have all been tried to ensure they work as intended, but if you notice any issues please report them!

We encourage all users to test this new version and then upgrade. Thanks to all who get involved!


  • 080db93 caddytls: Update docs for on-demand config
  • d813550 cmd: Require config for caddy validate (fix #5612) (#5614)
  • a8492c0 fileserver: Don't repeat error for invalid method inside error context (#5705)
  • 2d7d806 fileserver: Slightly more fitting icons
  • f11c3c9 go.mod: Upgrade CertMagic and quic-go
  • 5b9c850 go.mod: Upgrade to 0.14.0 (#5718)
  • 936ee91 reverseproxy: Always return new upstreams (fix #5736) (#5752)
  • 431adc0 templates: Fix httpInclude (fix #5698)

New Contributors

Full Changelog: v2.7.3...v2.7.4


06 Aug 00:49
Choose a tag to compare

We're pleased to present Caddy 2.7, which makes significant strides in areas of scaling, performance, and niche features.

Special thank-you to @francislavoie, @mohammed90, and other core team members for the ongoing dedication of their time to help maintain the project and help in our forums.

And a big thank-you to everyone else who contributed! You're awesome, and we're glad this project has so many contributors and sponsors to make it possible.

Docs are being updated and will be pushed live shortly. Thank you for your patience and for using Caddy!

(Note: Versions 2.7.0-2.7.2 contain bugs that were hotfixed within minutes and hours and a day of the release. Thank you to everyone who helped with that! And sorry for the trouble, we have learned lessons to help mitigate that in the future.)


  • The in-memory TLS certificate cache is no longer purged and recreated during config reloads, making reloads extremely lightweight even when managing thousands of certificates.
  • Significant HTTP/3 performance improvements (upstream in quic-go) including enabling 0-RTT. Caddy users should notice significantly better throughput for HTTP/3. Thanks for the fantastic work, @marten-seemann!
  • New default template for the file server's "browse" listings - more modern, easier to use, grid view, filetype-specific icons, and better dark mode (see #5427 for more screenshots and info)
    list view
    grid view
  • The reverse proxy now supports the PROXY protocol. Using external modules is no longer required; specifically, the plugin by @mastercactapus is now built-in. (#5424)
  • Caddyfile now supports Heredoc syntax for long embedded strings/documents. (#5385)
  • @francislavoie implemented a suite of enhancements to bring you more reliable, trustworthy client IP information, even through proxies and CDNs (#5104)
  • Certificate private keys will no longer be reused when renewing certificates.
  • Caddyfile import arg placeholders support slice syntax, e.g. {args[2:]} (#5249)
  • Customizable "fallback" policy for reverse proxy in case the primary policy isn't applicable. (#5488)
  • Etags are generated more sensibly for NixOS environments which all have Modified time of 1; and if you set your own Etag, it will not be overwritten.
  • EXPERIMENTAL: New short flags for the CLI. (#5379)
  • EXPERIMENTAL: The reverse proxy may be configured to keep hijacked connections (streams, WebSockets, etc.) open through config reloads. (#5567)
  • EXPERIMENTAL: Define "named routes" to reuse them without copying. Caddyfile snippets are useful for reusing config, but reusing the same HTTP routes involves lots of copied config and memory bloat. Named routes let you define a route once and reuse it throughout your HTTP server without copying. It is available for JSON and Caddyfile configs. (#5107)
  • EXPERIMENTAL: You can specify permissions for unix sockets. (#4741)
  • Many many bug fixes you may or may not notice 🙃

Deprecations and possible breaking changes for some:

  • ⚠️ The ask endpoint is now required to enable On-Demand TLS (b97c76f) for catch-all or wildcard hosts. Our docs have always mentioned this is required in production environments, but now the code enforces it. The ask endpoint is not required for local-only or internal-only names (#5384 and a7af7c4).
  • ⚠️ The on-demand config's throttle options are now deprecated because the 'ask' endpoint is required. Additionally, the 'ask' endpoint is checked and the throttle is applied before storage is queried for a certificate in order to limit load on the storage backend.
  • ⚠️ The long-deprecated lookup_srv feature of the reverse proxy has been removed. It was replaced with the dynamic upstreams feature in 2.6. (#5396)
  • ⚠️ The remote_ip forwarded matcher has been deprecated because it assumes trusting downstream proxies. Instead, the client_ip matcher should be used along with trusted_proxies configuration. (#5103 and #5104)
  • ⚠️ Placeholder syntax {args.0} is now deprecated in favor of {args[0]}.
  • ⚠️ Plugin authors will now need to use http.ResponseController to call Flush() or Hijack() on the response writer. (#5654)

Thank you to everyone who contributed! And thank you to our sponsors who truly make this project possible.

New Contributors

Full Changelog: v2.6.4...v2.7.3


  • 3f20a7c acmeserver: Configurable resolvers, fix smallstep deprecations (#5500)
  • b1366c7 build(deps): bump actions/setup-go from 3 to 4 (#5474)
  • dfe17c3 caddyconfig: Specify config adapter for HTTP loader (close #5607)
  • f3379f6 caddyfile: Fix heredoc fuzz crasher, drop trailing newline (#5404)
  • 960150b caddyfile: Implement heredoc support (#5385)
  • 8bc05e5 caddyfile: Implement variadics for import args placeholders (#5249)
  • 53b6fab caddyfile: Stricter parsing, error for brace on new line (#5505)
  • cee4441 caddyfile: Do not replace import tokens if they are part of a snippet (#5539)
  • 9cde715 caddyfile: Track import name instead of modifying filename (#5540)
  • bbe1952 caddyfile: Fix comparing if two tokens are on the same line (#5626)
  • 9f34383 caddyfile: check that matched key is not a substring of the replacement key (#5685)
  • cfc85ae caddyhttp: Add a getter for (#5531)
  • 05e9974 caddyhttp: Determine real client IP if trusted proxies configured (#5104)
  • c05e389 caddyhttp: Enable 0-RTT QUIC (#5425)
  • 8537586 caddyhttp: Fix vars_regexp matcher with placeholders (#5408)
  • 1c9ea01 caddyhttp: Impl ResponseWriter.Unwrap(), prep for Go 1.20's ResponseController (#5509)
  • cbf16f6 caddyhttp: Implement named routes, invoke directive (#5107)
  • 2b3046d caddyhttp: Log request body bytes read (#5461)
  • 96919ac caddyhttp: Refactor cert Managers (fix #5415) (#5533)
  • d8d87a3 caddyhttp: Serve http2 when listener wrapper doesn't return *tls.Conn (#4929)
  • 808b05c caddyhttp: Update quic's TLS configs after reload (#5517) (fix #4849)
  • 2945264 caddyhttp: Fix h3 shutdown (#5541)
  • 6a41b62 caddyhttp: Support custom network for HTTP/3 (#5573)
  • a7af7c4 caddytls: Allow on-demand w/o ask for internal-only
  • cd486c2 caddyhttp: Make use of http.ResponseController (#5654)
  • 18c309b caddyhttp: Preserve original error (fix #5652)
  • 66114cb caddyhttp: Trim dot/space only on Windows (fix #5613)
  • a02ecb0 caddytls: Check for nil ALPN; close #5470 (#5473)
  • faf0399 caddytls: Configurable fallback SNI (#5527)
  • e16a886 caddytls: Eval replacer on automation policy subjects (#5459)
  • be53e43 caddytls: Relax the warning for on-demand (#5384)
  • b97c76f caddytls: Require 'ask' endpoint for on-demand TLS
  • 0cc49c0 caddytls: Zero out throttle window first (#5443)
  • 4ba03c9 caddytls: Clarify some JSON config docs
  • 0e2c7e1 caddytls: Reuse certificate cache through reloads (#5623)
  • b301a3d celmatcher: Implement pkix.Name conversion to string (#5492)
  • 096971e ci/cd: ship tarballs with vendored deps (#5403)
  • 5ded580 cmd: Adjust documentation for commands (#5377)
  • 508cf2a cmd: Create pidfile before config load (close #5477)
  • 9e69195 cmd: Exp...
Read more


03 Aug 04:43
Choose a tag to compare

Do not use this release, use v2.7.3 instead which contains several hot fixes.


03 Aug 01:17
Choose a tag to compare

Do not use this release; use v2.7.3 instead. It contains a hotfix for a WebSocket issue.


02 Aug 21:01
Choose a tag to compare

Do not use this release, use v2.7.3 instead which contains hot fixes.


22 Jun 01:03
Choose a tag to compare
v2.7.0-beta.2 Pre-release

This release is obsolete. Please see the next release for the notes.