Auth events on HTTP layer use TCP remote IP instead of X-Forwarded-For client IP when behind reverse proxy

[LinkPhoenix]

Issue Description

When Stalwart is behind Traefik with http.use-x-forwarded = true, HTTP request handling correctly uses the client IP from X-Forwarded-For / X-Real-IP, but authentication events (auth.success, auth.failed) still use the TCP remote IP (the proxy) instead of the client IP.

Environment

Stalwart behind Traefik reverse proxy
http.use-x-forwarded = true in Stalwart config
Traefik sends X-Forwarded-For and X-Real-IP headers

Expected behavior

All HTTP-related events (including auth) should use the client IP from the forwarded headers when http.use-x-forwarded is enabled.
Actual behavior:
http.request-url correctly shows both IPs: TCP remote IP (proxy) and client IP from headers
auth.success and auth.failed only show the TCP remote IP (proxy), not the client IP from the headers

Example logs: 203.0.113.50 Is a random IP address that I chose to anonymize my log

Correct: http.request-url shows both IPs (client IP from X-Forwarded-For is used)

DEBUG HTTP request URL (http.request-url) listenerId = "http", localPort = 8080, remoteIp = 172.30.0.2, remotePort = 47392, remoteIp = 203.0.113.50, url = "/api/oauth"

Incorrect: auth.success uses only TCP layer IP (proxy), ignores X-Forwarded-For

INFO Authentication successful (auth.success) listenerId = "http", localPort = 8080, remoteIp = 172.30.0.2, remotePort = 47392, accountName = "admin"

Additional context

Other TCP protocols (SMTP, IMAP, POP3, etc.) work correctly with Proxy Protocol
Proxy Protocol is not usable for HTTP(S), so X-Forwarded-For is the only way to get the real client IP
http.request-body logs confirm Traefik sends X-Forwarded-For and X-Real-IP correctly
The issue appears limited to auth-related events, which seem to use the raw TCP remote_ip instead of the resolved client IP from the forwarded headers

And here http.quest-body exemple to confirm that Traefik is sending the headers correctly X-Forwarded-For and X-Real-IP correctly

2026-02-13T13:37:15Z TRACE HTTP request body (http.request-body) listenerId = "http", localPort = 8080, remoteIp = 172.30.0.2, remotePort = 56420, details = [["host", "mail.domain.com"], ["user-agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Safari/537.36"], ["accept", "*/*"], ["accept-encoding", "gzip, deflate, br, zstd"], ["accept-language", "en-US,en;q=0.8"], ["authorization", "Bearer vY3...lu"], ["dnt", "1"], ["priority", "u=1, i"], ["referer", "https://mail.domain.com/login"], ["sec-ch-ua", ""Not:A-Brand";v="99", "Brave";v="145", "Chromium";v="145""], ["sec-ch-ua-mobile", "?0"], ["sec-ch-ua-platform", ""Windows""], ["sec-fetch-dest", "empty"], ["sec-fetch-mode", "cors"], ["sec-fetch-site", "same-origin"], ["sec-gpc", "1"], ["x-forwarded-for", "203.0.113.50"], ["x-forwarded-host", "mail.domain.com"], ["x-forwarded-port", "443"], ["x-forwarded-proto", "https"], ["x-forwarded-server", "3...a"], ["x-real-ip", "203.0.113.50"]], contents = "", size = 0

Context 1 : Connection on the dashboard

Context 2 : Connect with mail client to show that everything works well with TCP protocols and that Stalwart does what it should for all other sports and correctly retrieves the client's IP address.

Expected Behavior

When http.use-x-forwarded = true is set, Stalwart should use the client IP from the x-real-ip or X-Forwarded-For HTTP header instead of the socket source address (the proxy IP) for all events HTTP-related.

Actual Behavior

No response

Reproduction Steps

No response

Relevant Log Output

No response

Stalwart Version

v0.15.x

Installation Method

Docker

Database Backend

RocksDB

Blob Storage

RocksDB

Search Engine

Internal

Directory Backend

Internal

Additional Context

No response

I acknowledge that:

• I have reviewed the documentation and FAQ and confirm that my issue is NOT addressed there.
• I have searched the Stalwart repository (both open and closed Discussions and Issues) and confirm this is not a duplicate.
• I have set the logging level to trace and included relevant log output if applicable.
• I agree to follow the project's Code of Conduct.

[LinkPhoenix]

I see that the answer is always:

If you do not want to see the proxy server IP in the logs, then enable the proxy protocol in both your proxy and Stalwart.

But the proxy protocol cannot and will never be able to be used on the HTTP layer. If it is enabled, the dashboard will no longer work because the dashboard expects a proxy protocol that cannot and will never be able to exist on the HTTP layer.

[andreymal]

You can actually use proxy_protocol on in nginx (although I think it's pretty useless)

The "both IPs" problem has been reported many times but mdecimus doesn't want to fix this for some reason

[LinkPhoenix]

I use traefik and I would like stay on traefik

[ovizii]

I see that the answer is always:

If you do not want to see the proxy server IP in the logs, then enable the proxy protocol in both your proxy and Stalwart.

But the proxy protocol cannot and will never be able to be used on the HTTP layer. If it is enabled, the dashboard will no longer work because the dashboard expects a proxy protocol that cannot and will never be able to exist on the HTTP layer

.

I've been trying to fix this same issue for days on my own until I found this and similar discussions. I felt the same frustration when the answer was: use proxy protocol and no matter how often one replies that that doesn't work for this case, it just never sinks in :-(

[LinkPhoenix]

Proxy Protocol preserves the original client IP and connection details across proxies, load balancers, or NAT layers. It adds a header at TCP connection start for accurate logging, security, rate limiting, and access control on backends. Works for any TCP protocol (HTTP, SMTP, databases), unlike HTTP-only headers like X-Forwarded-For.

That why is a good practies

[LinkPhoenix]

I think I've found a solution, but I need to understand it first.

2026-02-13T22:47:58Z INFO Authentication successful (auth.success) listenerId = "https", localPort = 443, remoteIp = 203.0.113.50, remotePort = 1851, accountName = "admin"

Note : 203.0.113.50 is a randome IP I use for send log here

Dynamic traefik file

tcp:
  routers:
    stalwart-mail-passthrough:
      rule: "HostSNI(`mail.domain.com`)"
      entryPoints:
        - websecure
      service: stalwart-https
      tls:
        passthrough: true

  services:
    stalwart-https:
      loadBalancer:
        servers:
          - address: "stalwart:443"
        serversTransport: stalwart-proxy

  serversTransports:
    stalwart-proxy:
      proxyProtocol:
        version: 2

[LinkPhoenix]

🚨🚨🚨 CRITICAL NOTICE BEFORE SOLUTION 🚨🚨🚨

⚠️ ALWAYS WHITELIST THE PROXY NETWORK OR PROXY IP ⚠️

You must always add to the whitelist:

• ✅ The proxy IP address
  OR
• ✅ The entire network (subnet) where the proxy is hosted

Failure to do so may result in:

• ❌ The proxy being blocked
• ❌ Service disruption
• ❌ Unexpected connection failures

🔴 THIS STEP IS MANDATORY 🔴

Do not proceed without verifying that the proxy IP or its network is properly whitelisted.

Complete Solution: Correct Client IP in auth.success/auth.failed When Connecting to the Stalwart Dashboard Behind Traefik

1. Problem

When Stalwart runs behind Traefik and you connect to the web dashboard (e.g. https://mail.domain.com), the events auth.success and auth.failed log the proxy IP (e.g. 172.30.0.2) instead of the real client IP even if you have enabled the HTTP option Obtain remote IP from Forwarded header

Example of the issue:

INFO Authentication successful (auth.success) listenerId = "http", localPort = 8080, remoteIp = 172.30.0.2, ...

The real client IP is used correctly for fail2ban, rate limiting, and other logic, but the auth events still show the proxy IP because the logging span is created when the TCP connection is accepted, before the HTTP handler reads X-Forwarded-For. More info here

2. Why Proxy Protocol on the HTTP Listener (8080) Doesn't Work

If Proxy Protocol were used on the HTTP listener (port 8080), Traefik would send:

1. Proxy Protocol header (client IP)
2. Raw TLS stream (encrypted HTTPS data)

The HTTP listener expects plain HTTP, not TLS. It cannot decrypt the stream, so the connection would fail. Proxy Protocol on 8080 is not viable for HTTPS traffic.

We assume here that you are a brilliant person and that your connections are always HTTPS. More information can be found in the post below this one.

3. Solution: TCP Passthrough for the Dashboard Domains

Configure Traefik so that traffic for the dashboard mail domains (e.g. mail.domain1.com, mail.domain2.com) is handled by a TCP router with TLS passthrough instead of an HTTP router.

Flow:

1. Client connects to https://mail.domain.com (dashboard).
2. Traefik matches the SNI with a TCP router and does not terminate TLS.
3. Traefik forwards the raw TLS stream to Stalwart:443 and prepends Proxy Protocol (with the real client IP).
4. Stalwart receives: [Proxy Protocol header] + [TLS stream].
5. Stalwart reads Proxy Protocol first → gets the real client IP.
6. Stalwart terminates TLS on the HTTPS listener (443) and processes HTTP.

Because the HTTPS listener (443) supports both Proxy Protocol and TLS, it can handle this flow correctly.

Officiel traefik documentation : https://doc.traefik.io/traefik/reference/routing-configuration/tcp/tls/#opt-passthrough

4. Result

• The real client IP is known as soon as the connection is accepted.
• auth.success and auth.failed log the real client IP instead of the proxy IP when connecting to the dashboard.
• Fail2ban, rate limiting, and other logic continue to use the correct IP.

5. Architecture Overview

Without Passthrough (autodiscover, autoconfig, mta-sts)

Client ──[HTTPS encrypted]──► Traefik ──[HTTP + X-Forwarded-For]──► Stalwart
                │                    │                              :8080
                │                    │
                │                    └── Traefik terminates TLS, reads request,
                │                        forwards as plain HTTP
                │
                └── Client sends HTTPS (encrypted)

With Passthrough (mail.domain1.com, mail.domain2.com – dashboard)

Client ──[HTTPS encrypted]──► Traefik ──[Proxy Protocol + raw stream]──► Stalwart
                │                    │                              :443
                │                    │
                │                    └── Traefik does not decrypt,
                │                        forwards as tunnel
                │
                └── Encrypted stream stays encrypted until Stalwart
                    Stalwart decrypts and processes everything

6. Configuration

Context: Traefik Proxy Network

The proxy.trusted-networks setting in Stalwart must include the network (or IP) of the Traefik proxy so it accepts Proxy Protocol from it.

• Network (CIDR): e.g. 172.20.0.0/24 for the Traefik Docker network.
• Single IP: if Traefik has a fixed IP on that network, you can use that IP instead (e.g. 172.20.0.2).

Use the CIDR if Traefik’s IP can change; use the fixed IP if it is static.

---

Option A: Full Configuration in Dynamic File

Create a file in your Traefik dynamic config directory (e.g. /dynamic/stalwart-https-passthrough.yml):

# =============================================================================
# Stalwart Dashboard - TCP Passthrough + Proxy Protocol
# =============================================================================
# Routes dashboard mail domains to Stalwart:443 with Proxy Protocol so that
# auth.success and auth.failed display the real client IP instead of the proxy IP
# when users log in to the web dashboard.
#
# Prerequisites:
# - Stalwart: Enable Proxy Protocol on HTTPS listener (config.toml)
#   server.listener.https.proxy.override = true
#   server.listener.https.proxy.trusted-networks = "172.20.0.0/24"  # Traefik network
#   # Or use Traefik's fixed IP: server.listener.https.proxy.trusted-networks = "172.20.0.2"
#
# - Stalwart must have TLS certificates for mail.domain1.com and mail.domain2.com
#
# - Remove mail.domain1.com and mail.domain2.com from your HTTP router rule
#   (Docker labels) so they are only handled by this TCP router
# =============================================================================

tcp:
  routers:
    stalwart-mail-passthrough:
      rule: "HostSNI(`mail.domain1.com`) || HostSNI(`mail.domain2.com`)"
      entryPoints:
        - websecure
      service: stalwart-https
      tls:
        passthrough: true

  services:
    stalwart-https:
      loadBalancer:
        servers:
          - address: "stalwart:443"
        serversTransport: stalwart-proxy

  serversTransports:
    stalwart-proxy:
      proxyProtocol:
        version: 2

Note: Replace mail.domain1.com, mail.domain2.com, and stalwart with your actual domains and container name.

---

Option B: Docker Labels + Minimal Dynamic File

Traefik cannot define TCP ServersTransport via Docker labels; it must be in a file. Use labels for the router and service, and keep only the ServersTransport in a dynamic file. More information here

1. Dynamic file (e.g. /dynamic/stalwart-proxy-transport.yml):

# ServersTransport must be defined in a file - not supported via Docker labels
tcp:
  serversTransports:
    stalwart-proxy:
      proxyProtocol:
        version: 2

2. Docker labels on the Stalwart container:

# ==============================================
# MAIL DASHBOARD - TCP Passthrough + Proxy Protocol
# Fixes auth.success and auth.failed showing proxy IP instead of client IP
# ==============================================
- "traefik.tcp.routers.stalwart-mail-passthrough.rule=HostSNI(`mail.domain1.com`) || HostSNI(`mail.domain2.com`)"
- "traefik.tcp.routers.stalwart-mail-passthrough.entrypoints=websecure"
- "traefik.tcp.routers.stalwart-mail-passthrough.service=stalwart-https"
- "traefik.tcp.routers.stalwart-mail-passthrough.tls.passthrough=true"
- "traefik.tcp.services.stalwart-https.loadbalancer.server.port=443"
- "traefik.tcp.services.stalwart-https.loadbalancer.serverstransport=stalwart-proxy@file"

The @file suffix tells Traefik that stalwart-proxy is defined in the File provider.

---

7. Stalwart Configuration

Add to your Stalwart config.toml:

server.listener.https.proxy.override = true
server.listener.https.proxy.trusted-networks = "172.20.0.0/24"

Or in the Web Ui

Explanation:

• 172.20.0.0/24 is the Traefik proxy network. Stalwart will accept Proxy Protocol only from IPs in this range.
• If Traefik has a fixed IP on that network (e.g. 172.20.0.2), you can use it instead:

server.listener.https.proxy.trusted-networks = "172.20.0.2"

Use the CIDR if Traefik’s IP can change; use the fixed IP if it is static.

---

8. Remove Dashboard Domains from HTTP Router

Remove mail.domain1.com and mail.domain2.com from the HTTP router rule so they are only handled by the TCP passthrough router.

Before:

- "traefik.http.routers.mailserver.rule=Host(`mail.${DOMAIN_1}`) || Host(`autodiscover.${DOMAIN_1}`) || ..."

After:

- "traefik.http.routers.mailserver.rule=Host(`autodiscover.${DOMAIN_1}`) || Host(`autoconfig.${DOMAIN_1}`) || Host(`mta-sts.${DOMAIN_1}`) || ..."

---

9. Summary

The solution therefore allows you to send the customer's real IP address, as your logs will show:
2026-02-14T00:00:41Z INFO Authentication successful (auth.success) listenerId = "https", localPort = 443, remoteIp = 203.0.113.50, remotePort = 52612, accountName = "admin"

Component	Action
Traefik	TCP router with HostSNI for dashboard mail domains, TLS passthrough, and Proxy Protocol v2
Stalwart	Enable Proxy Protocol on HTTPS listener (443) and set proxy.trusted-networks to the Traefik network (e.g. 172.20.0.0/24) or Traefik’s fixed IP
HTTP router	Remove mail domains so dashboard traffic is only routed via TCP passthrough

With this setup, auth.success and auth.failed will log the real client IP instead of the proxy IP when users connect to the web dashboard.

[LinkPhoenix]

NOTE : Since you are a highly intelligent individual with an enormous brain and are aware that websites must always be secure, you always use websecure (443) and even your web entry point (80) has a redirection instruction to websecure, so we want to communicate with Stalwart via its HTTPS 443 port.

Logically, if we do 80 (traefik)<443(traefik)<8080(Stalwart), there will be some issues with our package.

Why Not Use the HTTP Port (8080) with Proxy Protocol?

An alternative would be to use a TCP router with passthrough: false, so that Traefik terminates TLS and forwards decrypted HTTP to Stalwart:8080 with Proxy Protocol. This approach fails in practice for the following reasons.

tcp:
  routers:
    stalwart-mail:
      rule: "HostSNI(`mail.domain1.com`) || HostSNI(`mail.domain2.com`)"
      entryPoints: websecure
      service: stalwart-http
      tls:
        passthrough: false
        certResolver: cloudflare
  services:
    stalwart-http:
      loadBalancer:
        servers: address: "stalwart:8080" 
        serversTransport: stalwart-proxy

  serversTransports:
    stalwart-proxy:
      proxyProtocol:
        version: 2

1. HTTP/2 vs HTTP/1.1

With passthrough: false, Traefik:

1. Terminates TLS
2. Forwards the decrypted stream to Stalwart:8080

Modern browsers use HTTP/2 over HTTPS. The decrypted stream is therefore HTTP/2, not HTTP/1.1. Stalwart’s HTTP listener (port 8080) expects HTTP/1.1 and does not handle HTTP/2.

Resulting error:

2026-02-14T00:41:10Z DEBUG HTTP error occurred (http.error) listenerId = "http", localPort = 8080, 
remoteIp = 203.0.113.50, remotePort = 9804, reason = "invalid HTTP version parsed (found HTTP2 preface)"

The HTTP listener tries to parse the HTTP/2 preface as HTTP/1.1 and fails.

2. Why Passthrough to 443 Works

With passthrough: true to port 443:

• Traefik forwards the raw TLS stream without decrypting it
• Stalwart receives it on the HTTPS listener (443)
• Stalwart terminates TLS and handles HTTP/1.1 and HTTP/2 as usual

The HTTPS listener is designed to support both protocols after TLS termination.

3. Summary

Approach	Traefik sends to Stalwart	Stalwart listener	Result
passthrough: false → 8080	Proxy Protocol + decrypted stream (HTTP/2)	HTTP (8080) – HTTP/1.1 only	Fails: "invalid HTTP version parsed (found HTTP2 preface)"
passthrough: true → 443	Proxy Protocol + raw TLS stream	HTTPS (443) – HTTP/1.1 and HTTP/2	Works

4. Conclusion

Using the HTTP port (8080) with Proxy Protocol is not viable because:

1. Traefik would forward decrypted HTTP/2 traffic
2. Stalwart’s HTTP listener on 8080 only supports HTTP/1.1
3. The connection fails when the client uses HTTP/2 (typical for modern browsers)

The solution is to use TLS passthrough to port 443, where Stalwart terminates TLS and correctly handles both HTTP/1.1 and HTTP/2.

[chris-russell773]

Im using traefik too, I used a version of the config found in the docs. Whilst everything mostly worked, my JMAP mail clients seemed "flakey". Having to reconnect them and not updating inboxes quickly.

I followed this post to configure traefik. So now the only http router i have is for the autoconfig endpoints. Im using the tcp router for all https traffic to my mail domain.

Everything seems to be running a lot more smoothly. Only thing I did that isn't on this post (but is probably implied) is setup TLS within Stalwart so Stalwart has the certs for my domain (or have I got this wrong and I dont need to do that?)

Thanks for your post

[LinkPhoenix]

I don't mention this in my documentation, but for Stalwart to work, you need to provide the certificates in the correct format—which is why the official documentation uses “image: ghcr.io/kereis/traefik-certs-dumper:latest.” This formats the certificates into a format that Stalwart accepts, We mount the “image: ghcr.io/kereis/traefik-certs-dumper:latest” container volume as read-only to Stalwart. This aspect didn’t need to be in this documentation because the documentation guides you on the proper use of the proxy protocol with Traefik so that the auth.* events retrieve the correct IP. I also assume that doing it this way resolves issues I hadn’t anticipated. For example, I don’t use JMAP, so I don’t know if the correct use of the proxy protocol, as demonstrated in my documentation, is the answer to your issue, which appears to have been resolved.

[chris-russell773]

I was reading the docker doc (https://stalw.art/docs/install/platform/docker#next-steps) which lead me to the https://stalw.art/docs/install/security .

Here it says you shouldnt leave 8080 open, its for setup only. So I went down the path of trying to get everything through the https listener.

I came across this post wondering if you need to use the https listener for everything to work correctly. Thinking about it now, these docs may just be referring to non-proxied setups.

So, at the moment using your setup does work for me. I don't know if Stalwart treats 8080 differently to 443? If not, TLS termination at traefik would match my other services, so using 8080 would be what I'd do.

Thanks

[ovizii]

which is why the official documentation uses “image: ghcr.io/kereis/traefik-certs-dumper:latest.”

Do you mind explaining a bit where/who needs those certificates?

All email ports go straight to stalwart, only port 443 is TLS terminated at traefik and passed through to stalwart:8080.
I have set up stalwart => TLS => ACME providers to get a letsencrypt certificate. I “assume” it uses it for any TLS connection except for the stalwart web interface where traefik'S certificate is being used.

Just checking if I missed anything but this works fine for me without any cert-dumper setup.

[LinkPhoenix]

I said STALWART need certificat i can't help you more than this information