Sync docs

[mohammed90]

We've fallen behind on updating the docs. This is an attempt to sync the docs.

Maintainers can push directly to the branch. Other contributors may send PRs against this branch.

Documentation Checklist

The checklist is generated by copilot for the missing feature documentation between v2.8.0 and v2.10.2. It's likely not accurate (e.g. argon2id isn't released yet), but it's a starter.

Command Line Tools

• caddy adapt reading from stdin (cmd: Allow caddy adapt to read from stdin caddy#7163) - Bobby Dhillon
• caddy hash-password cost parameter for bcrypt (feat: add bcrypt cost parameter to hash-password caddy#7149) - GreyXor

Authentication & Security

• argon2id support in basic_auth (Argon2id Support for Basic Auth caddy#7186) - GreyXor
• Encrypted ClientHello (ECH) (caddytls: Encrypted ClientHello (ECH) caddy#6862) - Matt Holt
• sni_regexp matcher (caddytls: Add sni_regexp matcher caddy#6569) - vnxme (nothing to do, this is JSON only for now, we don't have Caddyfile support for TLS matchers)
• client_auth leaf verifier in Caddyfile (client_auth: wire up leaf verifier Caddyfile caddy#6772) - Mohammed Al Sahaf

Logging & Monitoring

• timberjack with time-rolling options (logging: Switch from lumberjack to timberjack, add time-rolling options caddy#7244) - aeris
• Buffered logging (logging: Buffer the logs before config is loaded caddy#7245) - Francis Lavoie
• Log sampling configuration (httpcaddyfile: Implement log sampling config caddy#6682) - Nikolai K
• spanID in tracing (tracing: Add spanID field to access logs and http.vars.span_id placeholder caddy#6646) - Yifan Yang
• go and process metrics collectors (metrics: add go and process collectors caddy#6704) - Mohammed Al Sahaf
• Per-host metrics (metrics: scope metrics to active config, add optional per-host metrics caddy#6531) - Mohammed Al Sahaf

Reverse Proxy

• http.Protocols for h1, h2, h2c (reverseproxy: use http.Protocols to handle h2c requests caddy#6990, caddyhttp: use the new http.Protocols to handle h1, h2 and h2c requests caddy#6961) - WeidiDeng
• trusted_proxies_unix (caddyhttp: Add trusted_proxies_unix for trusting unix socket X-Forwarded-* headers caddy#7265) - Chris Seufert
• Via header (reverse_proxy leads to duplicate Server headers caddy#6275) - Matthew Holt
• http.reverse_proxy.retries placeholder (reverse_proxy: add placeholder http.reverse_proxy.retries caddy#6553) - Steffen Busch
• Active health checks request body option (reverseproxy: Active health checks request body option caddy#6520) - Jesper Brix Rosenkilde
• Allow 0 as weights for weighted_round_robin (reverseproxy: Allow 0 as weights for weighted_round_robin caddy#6681) - Sucipto
• HTTP/1.1 upgrade for websocket extended connect (reverseproxy: Use http1.1 upgrade for websocket for extended connect of http2 and http3. caddy#7305) - Anthony Biondo
• HTTP/1 for outbound TLS requests with websocket placeholders (reverse_proxy: use http1 for outbound tls requests with placeholder t… caddy#7296) - WeidiDeng

TLS & ACME

• acme_dns directive (httpcaddyfile: Add missing DNS challenge check for acme_dns caddy#7270, ACME DNS Challenge no longer takes dns config from top-level dns key caddy#7091) - Aditya Bhargava, Matthew Holt
• tls.context module (caddytls: Support new tls.context module caddy#6369) - Matt Holt

Server Options

• keepalive_idle and keepalive_count (caddyhttp: Add server options keepalive_idle and keepalive_count caddy#7298) - joshuamcbeth
• keepalive_interval (Use KeepAliveConfig to pass keepalive_interval to listener's accepted sockets caddy#7151) - joshuamcbeth

File Server

• first_exist_fallback strategy (fileserver: Add first_exist_fallback strategy for try_files caddy#6699) - Kévin Dunglas
• file_limit for browse (fileserver: Add file_limit option for browse caddy#6648) - Atakan Yenel
• AVIF image format support (fileserver: Add support for .avif image format caddy#6988) - Steffen Busch
• Sort buttons in grid mode ([ADD] sort buttons in grid mode caddy#7089) - filipRatajczak
• Range header handling for precompressed static files (file_server: set Range header for precompressed static files to force Content Length header to appear caddy#7042) - WeidiDeng

Placeholders & Matchers

• Escaped value placeholders (caddyhttp: add replacer placeholders for escaped values caddy#7181) - Bang Lee
• {?query} placeholder (caddyhttp: Add {?query} placeholder caddy#6714) - Francis Lavoie
• MatchWithError (caddyhttp: Add MatchWithError to replace SetVar hack caddy#6596) - Francis Lavoie
• vars and vars_regexp in CEL (caddyhttp: Escaping placeholders in CEL, add vars and vars_regexp caddy#6594) - Francis Lavoie
• Placeholders in TLS/HTTP matchers (Runtime placeholders for selected TLS and HTTP matchers caddy#6480) - vnxme
• {file.*} newline stripping behavior (replacer: {file.*} global placeholder strips trailing newline caddy#6411) - Steffen Busch

Core Features

• Socket activation (named and general) (listeners: Add support for named socket activation caddy#7243, Implement issue #6296 passing FDs / socket activation caddy#6573) - Pavel, Aaron Paterson
• network_proxy module (core: add modular network_proxy support caddy#6399) - Mohammed Al Sahaf
• SIGUSR1 reload behavior (core: Reloading with SIGUSR1 if config never changed via admin caddy#7258) - Francis Lavoie
• GOMEMLIMIT automatic setting (feat: automatically set GOMEMLIMIT caddy#6809) - Kévin Dunglas
• force_automate option (httpcaddyfile: Implement force_automate caddy#6712) - Francis Lavoie
• prefer_wildcard in auto_https (autohttps: Implement auto_https prefer_wildcard option caddy#6146) - Francis Lavoie

Headers

• Support placeholders in replacement search patterns (Fix: Support placeholders in header replacement search patterns caddy#7117) - Zongze Wu

Request/Response Handling

• request_body set option (requestbody: Add replace for optional body replacement caddy#5795) - Adrien Pensart
• header match subdirective (header: match subdirective for response matching caddy#6765) - Arsh

Tracing

• OpenTelemetry autoexport (feat: switch to autoexport for OpenTelemetry span exporter caddy#7317) - Philipp Keidel

[steffenbusch]

Regarding this one:

• http.reverse_proxy.retries placeholder (reverse_proxy: add placeholder http.reverse_proxy.retries caddy#6553) - Steffen Busch

The http.reverse_proxy.retries placeholder is already documented here:
https://caddyserver.com/docs/json/apps/http/servers/routes/handle/reverse_proxy/#docs

I would propose adding a reference link to that section here as well, for better discoverability:
https://caddyserver.com/docs/conventions#placeholders

If that approach is acceptable, I will open a PR against the sync-docs branch.

Regarding this one:

• AVIF image format support (fileserver: Add support for .avif image format caddy#6988) - Steffen Busch

I am unsure where this should be reflected in the documentation. I did not find any dedicated mention of supported file extensions for the browse templates in general, so there is no existing list to update. Do you have a suggestion as to where this should be noted, if at all?

[mholt]

The placeholder improvements sound good to me, @steffenbusch -- as for the file formats in the template, I don't personally feel a need to document which image extensions we recognize, since ultimately it's up to the browser to decode them anyway -- we should just support all the common ones, I think.

[mholt]

I'll work on the ECH docs soon. I've been doing a lot of things but I'm hoping to get ECH key rotation working and then update all the docs together.

[mohammed90]

I'll work on the network_proxy in the coming days

[mohammed90]

I'll work on the network_proxy in the coming days

Copilot must be hallucinating. It's already there.

[francislavoie]

Yeah it got some wrong in the list that I just checked off, no biggie.

I'll do the SIGUSR1 and trusted_proxies_unix and timberjack docs later cause they're not released yet. I can do request_body and header match stuff at some point, those are released I think.

I'm not even sure where we're at with force_automate/prefer_wildcard now 🤣 it's been a while since I was deep in the weeds on that and Matt made a change on top of it so I need to look into it again. We have examples for idiomatic wildcard setup in the common patterns page that needs to be touched up for that.

Socket activation stuff still seems up in the air, there's competing PRs open and I don't know where that will land. I'll want help with that, I only have a surface-level understanding of how that all works.

[mohammed90]

For documentation, the last doc update was for v2.8.0. It was done in PRs #419, #389, and #390.