Caddy: Allow setting `servers.client_ip_headers` so that alternatives to `X-Forwarded-For` (like Cloudflare's `Cf-Connecting-Ip`) work

[Nezteb]

Important notices

• I have read the contributing guide lines at https://github.com/opnsense/plugins/blob/master/CONTRIBUTING.md
• I have searched the existing issues, open and closed, and I'm convinced that mine is new.
• When the request is meant for an existing plugin, I've added its name to the title.

Is your feature request related to a problem? Please describe.

I use OPNsense with the Caddy plugin (dynamic DNS enabled through Cloudflare) and have Cloudflare's orange cloud/proxy enabled pointing at my public IP. Because of this, the X-Forwarded-For header is somewhat spoofed.

The Caddy and Authelia docs describe the issue in more detail:

• https://caddyserver.com/docs/caddyfile/directives/reverse_proxy#defaults
• https://www.authelia.com/integration/proxies/forwarded-headers/#cloudflare

I've found plenty of threads about this on the OPNsense forums, the Caddy forums, the Cloudflare forums, etc. Most threads end with the OP disabling Cloudflare's orange cloud/proxy toggle, but I don't think that should be totally necessary for what I'm trying to do? A few examples:

• https://caddy.community/t/global-directives-on-custom-ports/24485/28
• https://caddy.community/t/cloudflare-proxy-x-forwarded-for-client-ip-issue/25154/16

I tried the header rewrite rule described in the Authelia docs, but Cloudflare still appends their proxy IP to the header.

Cloudflare docs suggest to instead use the Cf-Connecting-Ip header:

• https://developers.cloudflare.com/fundamentals/reference/http-headers/#x-forwarded-for
• https://developers.cloudflare.com/fundamentals/reference/http-headers/#cf-connecting-ip
• https://developers.cloudflare.com/support/troubleshooting/restoring-visitor-ips/restoring-original-visitor-ips/

However, it seems that the OPNsense Caddy plugin doesn't currently support this.

Describe the solution you'd like

I would like a way to effectively update my /usr/local/etc/caddy/Caddyfile to use client_ip_headers:

{
    # ...
    servers {
        protocols h1 h2 h3
        trusted_proxies static <ips> # https://www.cloudflare.com/ips/
        client_ip_headers Cf-Connecting-Ip X-Forwarded-For
    }
    # ...
}

I can think of two options:

1. Add a plugin UI element that takes a string like "Cf-Connecting-Ip X-Forwarded-For" and it simply puts it into the Caddyfile as is.
2. Add some sort of template/import that allows users to still put config in /usr/local/etc/caddy/caddy.d/ that accomplishes this somehow.

Describe alternatives you've considered

I tried to do this by creating a custom config file as mentioned in the docs: https://docs.opnsense.org/manual/how-tos/caddy.html#custom-configuration-files

$ cat /usr/local/etc/caddy/caddy.d/client_ip_headers.global
servers {
        protocols h1 h2 h3
        trusted_proxies static <ips> # https://www.cloudflare.com/ips/
        client_ip_headers Cf-Connecting-Ip X-Forwarded-For
}

However, running caddy validate gives an error:

$ caddy validate --config /usr/local/etc/caddy/Caddyfile
2025/01/31 20:16:39.483 INFO    using config from file  {"file": "/usr/local/etc/caddy/Caddyfile"}
2025/01/31 20:16:39.483 WARN    No files matching import glob pattern   {"pattern": "/usr/local/etc/caddy/caddy.d/*.conf"}
Error: adapting config using caddyfile: cannot have 'servers' global options with duplicate listener addresses:

Reading more into the Caddy docs, I realize that import can't be used to overwrite previous blocks, which makes sense.

[Monviech]

Could we feed these headers from the existing headers grid, like we do with access lists for the trusted_proxies?

Then it would be a model relation field in the Model and almost the same logic in the template as the trusted_proxies.

If we want it static instead, provide a list of all important client IP headers to choose from in a dropdown selectpicker.

EDIT: I've looked a bit into it and most CDN have their own headers, so I'll go with the model relation field in order not having to add headers manually in the future.

[Monviech]

I've added a PR for you to test when you have time.

[Nezteb]

Are there docs I can refer to for how to test custom builds of an official plugin? I assume I have to set up https://github.com/opnsense/tools on my OPNsense device? I'm just not sure on how to try a new local version, revert to an old release version, etc.

[Monviech]

If you are on os-caddy 1.8.1, you can use:

opnsense-patch -c plugins 20f6ed0
opnsense-patch -c plugins 2ee451e

To revert you can execute the patches again.

If you are on a previous version you might need this in addition before executing the top two patches:

opnsense-patch -c plugins 7745e63

[Nezteb]

Updated and applied patches, and set up two hearders:

X-Forwarded-For:

Cf-Connecting-Ip:

And then set them up in the UI:

And here is the diagnostic Caddyfile:

This passes caddy validate --config /usr/local/etc/caddy/Caddyfile

I assume having two separate lines for each header would work given the spec? https://caddyserver.com/docs/json/apps/http/servers/client_ip_headers/

[Monviech]

Ive checked the JSON which gets generated from the Caddyfile and multiple lines get adapted in there. Thats always a sign these things work as expected.

Thanks for testing, Ill merge this soon. :)