github caddyserver/caddy v2.8.0
on GitHub

latest releases: v2.9.0-beta.3, v2.9.0-beta.2, v2.9.0-beta.1...
5 months ago

Caddy 2.8 is here! With hundreds of improvements, Caddy is more scalable and capable than ever before. Featuring ACME Renewal Information (ARI) support, HTTP/3 to proxy backends, and so much more than we can list in a sentence, we are pleased to bring you one of the biggest Caddy updates yet. Documentation on our website will be updated in the coming days.

We've implemented a ton of improvements, fixes, and awesome new features based on your feedback. While some of them aren't particularly visible changes, they allow Caddy to scale better and be more reliable in demanding deployments. Many of the changes are quality-of-life improvements we hope you'll appreciate. Then there's improvements to ACMEz, CertMagic, and other dependencies which make Caddy better that may not show up in this list.

There was a lot of code that had been documented as deprecated in place for a long time, so this version introduces a few more breaking changes than usual; please review the notes below.

Thank you to our sponsors and everyone in the community who contributed -- over 40 of you made your first contribution for this release. 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. Caddy 2.8 is already being used in our sponsors' large-scale, multi-region production deployments.

Want to join those ranks? Sponsor the Caddy project and benefit from development priority, dedicated private support, and much more.

As with any server upgrades, please be sure to test and validate your configurations in a staging or test environment before deploying to production. 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 still 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. The old names will continue to work for now, with a deprecation warning in the logs. (#6066).
  • The basic_auth handler no longer supports scrypt (deprecated for nearly two years) (#6091)
  • The forwarded option has been deprecated for a long time and has now been removed from the remote_ip matcher. Use the client_ip matcher instead. (#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.
  • Go API: If you called caddy.Context.AppIfConfigured(), it now returns an error, as part of a bug fix. (#6292)

Notable changes:

  • acme_server: Configurable allow/deny policies (#5796)
  • acme_server: Specify allowed challenge types (#5794)
  • caddyfile: Plugin authors can now specify a default ordering for directives, making manual ordering by users less necessary (#5865)
  • cmd: The --adapter flag is not needed for config files ending with .caddyfile (#5919)
  • 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)
  • handle_errors: Handling can now be filtered by response status code more easily (#5965)
  • 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)
  • http: A new tracing mode writes each individual middleware handler to logs (#6313)
  • http: Access logs use a different message ("unhandled") when an HTTP request is a no-op (#5182)
  • 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)
  • 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)
  • reverse_proxy: HTTP/3 supported to backends (experimental) (#6312)
  • 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)
  • root, rewrite: A * matcher token is no longer required in the Caddyfile (#5844)
  • 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
  • uri: Can now perform structured query rewrites with uri query (#6120, #6165)

Changelog

Full Changelog: v2.7.6...v2.8.0

  • ac0ad4d Upgrade acmeserver to github.com/go-chi/chi/v5 (#5913)
  • 931656b acmeserver: add policy field to define allow/deny rules (#5796)
  • e1aa862 acmeserver: support specifying the allowed challenge types (#5794)
  • e6f46c8 acmeserver: Add sign_with_root for Caddyfile (#6345)
  • 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 golang.org/x/crypto 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)
  • f6d2c29 caddyfile: Reject global request matchers earlier (#6339)
  • 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: Fix linter warning about deprecation
  • f5344f8 caddyhttp: Fix panic when request missing ClientIPVarKey (#6040)
  • 2c48dda caddyhttp: Only attempt to enable full duplex for HTTP/1.x (#6102)
  • 1277888 caddyhttp: Register post-shutdown callbacks (#5948)
  • 7b48ce0 caddyhttp: Replace sensitive headers with REDACTED (close #5669)
  • cc0c0cf caddyhttp: Security enhancements for client IP parsing (#5805)
  • 70953e8 caddyhttp: Support multiple logger names per host (#6088)
  • bde4621 caddyhttp: Test cases for %2F and %252F (#6084)
  • c8559c4 caddyhttp: Use sync.Pool to reduce lengthReader allocations (#5848)
  • ddb1d2c caddyhttp: add http.request.local{,.host,.port} placeholder (#6182)
  • 924010c caddyhttp: close quic connections when server closes (#6202)
  • e0daa39 caddyhttp: record num. bytes read when response writer is hijacked (#6173)
  • 654a3bb caddyhttp: remove duplicate strings.Count in path matcher (fixes #6233) (#6234)
  • b568a10 caddyhttp: support unix sockets in caddy respond command (#6010)
  • c93e304 caddyhttp: suppress flushing if the response is being buffered (#6150)
  • 52822a4 caddyhttp: upgrade to cel v0.20.0 (#6161)
  • 224316e caddyhttp: Move log WARN to INFO, reduce confusion (#6185)
  • 6dce493 caddyhttp: Alter log message when request is unhandled (close #5182)
  • 4af38e5 caddyhttp: Log 4xx as INFO; 5xx as ERROR (close #6106)
  • fb63e2e caddyhttp: New experimental handler for intercepting responses (#6232)
  • 9ba9991 caddyhttp: Trace individual middleware handlers (#6313)
  • c97292b caddypki: Allow use of root CA without a key. Fixes #6290 (#6298)
  • 4512be4 caddytest: Rename adapt tests to *.caddyfiletest extension (#6119)
  • 4c90f14 caddytest: normalize the JSON config (#6316)
  • 8d7ac18 caddytls: Ability to drop connections (close #6294)
  • 6a02999 caddytls: Add Caddyfile support for on-demand permission module (close #6260)
  • b24ae63 caddytls: Context to DecisionFunc (#5923)
  • d129ae6 caddytls: Evict internal certs from cache based on issuer (#6266)
  • 57c5b92 caddytls: Make on-demand 'ask' permission modular (#6055)
  • 76c4cf5 caddytls: Option to configure certificate lifetime (#6253)
  • 3609a4a caddytls: Remove shim code supporting deprecated lego-dns (#6231)
  • dc9dd2e caddytls: Still provision permission module if ask is specified
  • 4a09cf0 caddytls: Sync distributed storage cleaning (#5940)
  • 81413ca caddytls: Upgrade ACMEz to v2; support ZeroSSL API; various fixes (#6229)
  • 3ae07a7 caddytls: clientauth: leaf verifier: make trusted leaf certs source pluggable (#6050)
  • 03f703a caddytls: verifier: caddyfile: re-add Caddyfile support (#6127)
  • db3e19b caddytls: fix permission requirement with AutomationPolicy (#6328)
  • 1fc151f caddytls: remove ClientHelloSNICtxKey (#6326)
  • e66040a caddytls: set server name in context (#6324)
  • b359ca5 ci/cd: use the build tag nobadger to exclude badgerdb (#6031)
  • 24b0ecc cmd: Add newline character to version string in CLI output (#5895)
  • e473ae6 cmd: Adjust config load logs/errors (#6032)
  • 185ed6f cmd: Assume Caddyfile based on filename prefix and suffix (#5919)
  • e1f4b83 cmd: Fix panic related to config filename (fix #5919)
  • 8f87c5d cmd: Only validate config is proper JSON if config slice has data (#6250)
  • 56c6b3f cmd: Preserve LastModified date when exporting storage (#5968)
  • de4959f cmd: fix the output of the Usage section (#6138)
  • 54823f5 cmd: reverseproxy: log: use caddy logger (#6042)
  • d70608b cmd: upgrade: resolve symlink of the executable (#5891)
  • d54dcf1 cmd: use automaxprocs for better perf in containers (#5711)
  • e1b9a9d core: Add ctx.Slogger() which returns an slog logger (#5945)
  • cbbd1df core: Always make AppDataDir for InstanceID (#5976)
  • 174c19a core: Apply SO_REUSEPORT to UDP sockets (#5725)
  • 46c5db9 core: OnExit hooks (#6128)
  • a747930 core: Support NO_COLOR env var to disable log coloring (#6078)
  • 7c82e26 core: quic listener will manage the underlying socket by itself (#5749)
  • a6a45ff core: AppIfConfigured returns error; consider not-yet-provisioned modules (#6292)
  • 2ce5c65 core: Fix bug in AppIfConfigured (fix #6336)
  • 03e0a01 encode: Configurable compression level for zstd (#6140)
  • 3067074 encode: Improve Etag handling (fix #5849)
  • 9ab0943 encode: Slight fix for the previous commit
  • e698ec5 encode: write status immediately when status code is informational (#6164)
  • ba58114 events: Add debug log
  • 7e52db8 fileserver: Add .m4v for browse template icon
  • 8f9ffc5 fileserver: Add total file size to directory listing (#6003)
  • feb07a7 fileserver: Browse can show symlink target if enabled (#5973)
  • b16aba5 fileserver: Enable compression for command by default (#5855)
  • 5d8b45c fileserver: Escape # and ? in img src (fix #6237)
  • f3e849e fileserver: Implement caddyfile.Unmarshaler interface (#5850)
  • d00824f fileserver: Improve Vary handling (#5849)
  • 362f33d fileserver: New --precompressed flag (#5880)
  • 5a4374b fileserver: Preserve query during canonicalization redirect (#6109)
  • cabb5d7 fileserver: Set "Vary: Accept-Encoding" header (see #5849)
  • 567d96c fileserver: read etags from precomputed files (#6222)
  • c839a98 filesystem: Globally declared filesystems, fs directive (#5833)
  • 60abd72 fix: add back text/*
  • b8f729b fix: add more media types to the compressed by default list
  • a4a64a6 gitignore: Add rule for caddyfile.go (#6225)
  • 9fc55a9 go.mod: CVE-2023-45142 Update opentelemetry (#5908)
  • fe2a02b go.mod: Upgrade quic-go to v0.39.1
  • b49ec05 go.mod: Updated quic-go to v0.40.1 (#5983)
  • ee35855 go.mod: update quic-go version to v0.40.0 (#5922)
  • a46ff50 go.mod: Upgrade to quic-go v0.43.0
  • b522710 go.mod: Upgrade to quic-go v0.43.1
  • dd203ad go.mod: CertMagic v0.21.0
  • d79c0f0 go.mod: Upgrade dependencies
  • abdf1ae go.mod: go 1.22.3
  • 258d906 httpcaddyfile: Add RegisterDirectiveOrder function for plugin authors (#5865)
  • 4181c79 httpcaddyfile: Add optional status code argument to handle_errors directive (#5965)
  • 2a78c9c httpcaddyfile: Allow nameless regexp placeholder shorthand (#6113)
  • 7984e6f httpcaddyfile: Fix TLS automation policy merging with get_certificate (#5896)
  • f976c84 httpcaddyfile: Fix cert file decoding to load multiple PEM in one file (#5997)
  • c2d889f httpcaddyfile: Fix redir html (#6001)
  • c27425e httpcaddyfile: Keep deprecated skip_log in directive order (#6153)
  • ac1f20b httpcaddyfile: Remove port from logger names (#5881)
  • 5e2f1b5 httpcaddyfile: Rewrite root and rewrite parsing to allow omitting matcher (#5844)
  • 3efda6f httpcaddyfile: Skip automate loader if disable_certs is specified (fix #6148)
  • da7d8cb httpcaddyfile: Sort skip_hosts for deterministic JSON (#5990)
  • cb86319 httpcaddyfile: Support client auth verifiers (#6022)
  • feeb6af httpcaddyfile: Fix expression matcher shortcut in snippets (#6288)
  • 583c585 httpcaddyfile: Set challenge ports when http_port or https_port are used
  • 96f638e httpredirectlistener: Only set read limit for when request is HTTP (#5917)
  • 3248e4c logging: Add zap.Option support (#5944)
  • b9c40e7 logging: Automatic wrap default for filter encoder (#5980)
  • 726a9a8 logging: Fix default access logger (#6251)
  • 01d5568 logging: Implement append encoder, allow flatter filters config (#6069)
  • 0d44e3e logging: Implement log_append handler (#6066)
  • 91ec754 logging: Inline Caddyfile syntax for ip_mask filter (#6094)
  • 0c01547 logging: support ms duration format and add docs (#6187)
  • 4356635 logging: Add support for additional logger filters other than hostname (#6082)
  • 8c2a72a caddyhttp: Drop forwarded option from remote_ip matcher (#6085)
  • ed7e3c9 caddyhttp: query matcher now ANDs multiple keys (#6054)
  • 387545a metrics: Record request metrics on HTTP errors (#5979)
  • e0bf179 modules: fix some typo in conments (#6206)
  • dc12bd9 proxyprotocol: use github.com/pires/go-proxyproto (#5915)
  • dba556f refactor: move automaxprocs init in caddycmd.Main()
  • 80acf1b replacer: Fix escaped closing braces (#5995)
  • 7979739 replacer: Implement file.* global replacements (#5463)
  • e7336cc replacer: use RWMutex to protect static provider (#6184)
  • 868af6a reverseproxy: Add grace_period for SRV upstreams to Caddyfile (#6264)
  • 613d544 reverseproxy: Accept EOF when buffering
  • f658fd0 reverseproxy: Add tls_curves option to HTTP transport (#5851)
  • a9768d2 reverseproxy: Configurable forward proxy URL (#6114)
  • 0b381eb reverseproxy: Implement modular CA provider for TLS transport (#6065)
  • d9ff7b1 reverseproxy: Only change Content-Length when full request is buffered (#5830)
  • 9f97df2 reverseproxy: Remove long-deprecated buffering properties
  • d93e027 reverseproxy: Reuse buffered request body even if partially drained
  • 72ce78d reverseproxy: SRV dynamic upstream failover (#5832)
  • 74949fb reverseproxy: Use xxhash instead of fnv32 for LB (#6203)
  • b40cacf reverseproxy: Wait for both ends of websocket to close (#6175)
  • e65b97f reverseproxy: configurable active health_passes and health_fails (#6154)
  • da6a569 reverseproxy: cookie should be Secure and SameSite=None when TLS (#6115)
  • 1b9042b reverseproxy: handle buffered data during hijack (#6274)
  • 53f7035 reverseproxy: use context.WithoutCancel (#6116)
  • d05d715 reverseproxy: HTTP transport: fix PROXY protocol initialization (#6301)
  • b2b29dc reverseproxy: Implement health_follow_redirects (#6302)
  • e60148e reverseproxy: Pointer to struct when loading modules; remove LazyCertPool (#6307)
  • 5f6758d reverseproxy: Support HTTP/3 transport to backend (#6312)
  • 69290d2 rewrite: Implement uri query operations (#6120)
  • 29f57fa rewrite: uri query replace operation (#6165)
  • c6673ad staticresp: Use the evaluated response body for sniffing JSON content-type (#6249)
  • 0900844 templates: Clarify include args docs, add .ClientIP (#5898)
  • 4e8245d templates: Delete headers on httpError to reset to clean slate (#5905)
  • 18f3429 templates: Offically make templates extensible (#5939)
  • f98f449 templates: Add pathEscape template function and use it in file browser (#6278)
  • 4173e2c tls: accept placeholders in string values of certificate loaders (#5963)
  • ed41c92 tls: add reuse_private_keys (#6025)
  • e965b11 tls: modularize trusted CA providers (#5784)
  • 0b5720f tracing: add trace_id var (http.vars.trace_id placeholder) (#6308)
  • 5ed8689 vars: Allow overriding http.auth.user.id in replacer as a special case (#6108)
  • d132584 vars: Make nil values act as empty string instead of "<nil>" (#6174)

New Contributors

Check out latest releases or
releases around caddyserver/caddy v2.8.0

Don't miss a new caddy release

NewReleases is sending notifications on new releases.

Get notifications