# HAProxy PROXY protocol

Bongo accepts HAProxy PROXY protocol version 1 and version 2 on its mail
client listeners. It is disabled by default and is available for SMTP,
submission, the internal SMTP relay, SMTPS, IMAP/IMAPS, POP3/POP3S, and
ManageSieve. The header is consumed before an application greeting and before
an implicit TLS handshake.

Enable it separately in each applicable service configuration. For example,
if HAProxy connects to Bongo from `172.16.11.7`:

```json
"proxy_protocol_enabled": true,
"proxy_protocol_networks": ["172.16.11.7/32"]
```

The networks contain the addresses of the trusted HAProxy instances as seen by
Bongo, not the addresses of mail clients. A connection from a configured proxy
must provide a complete, valid PROXY header within five seconds. Bongo closes
the connection otherwise. Connections from other source addresses remain
normal native-protocol connections and cannot submit a trusted PROXY header.

A minimal HAProxy TCP backend looks like this:

```haproxy
frontend smtp_in
    mode tcp
    bind :25
    default_backend bongo_smtp

backend bongo_smtp
    mode tcp
    server bongo 172.16.11.14:25 check send-proxy-v2
```

TLS passthrough uses the same arrangement. HAProxy places the PROXY block
before the untouched TLS stream:

```haproxy
frontend imaps_in
    mode tcp
    bind :993
    default_backend bongo_imaps

backend bongo_imaps
    mode tcp
    server bongo 172.16.11.14:993 check send-proxy-v2
```

For SMTP on port 26, `internal_relay_networks` continues to describe the
original devices which may relay. Bongo applies the PROXY address first and
then performs the internal-relay ACL, device mapping, DNS identification, and
per-client rate limiting.

Bongo 0.7 supports the `TCP4` address family as well as the v1 `UNKNOWN` and
v2 `LOCAL`/`UNSPEC` passthrough forms. A header carrying `TCP6` is rejected
explicitly. Native IPv6 listeners and PROXY-provided IPv6 identities are
planned together for Bongo 0.9 so every authentication, SPF, logging, ACL, and
rate-limit path uses the same IPv6-capable address representation.

The web application is normally served by Apache or another HTTP reverse
proxy. Configure PROXY protocol or forwarded headers at that HTTP layer;
Bongo's mail-listener setting does not alter HTTP handling.