proxy/haproxy: Update haproxy documentation#1499
Open
cmouse wants to merge 1 commit into
Open
Conversation
This comment has been minimized.
This comment has been minimized.
cmouse
force-pushed
the
haproxy
branch
2 times, most recently
from
e9171b4 to
c8da05b
Compare
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
cmouse
force-pushed
the
haproxy
branch
2 times, most recently
from
3b7c4da to
943faf4
Compare
sirainen
requested changes
Apr 9, 2026
cmouse
commented
Apr 10, 2026
sirainen
requested changes
Apr 20, 2026
sirainen
requested changes
Apr 20, 2026
sirainen
requested changes
Apr 21, 2026
cmouse
force-pushed
the
haproxy
branch
2 times, most recently
from
8228946 to
a57f3eb
Compare
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
sirainen
requested changes
May 26, 2026
|
|
||
| Dovecot must be configured to accept PROXY protocol headers: | ||
|
|
||
| - Set `haproxy = yes` on the listener |
Contributor
There was a problem hiding this comment.
Set [[setting,inet_listener_haproxy,yes]] on the [[setting,inet_listener]].
| - Set [[setting,haproxy_trusted_networks]] to the IP address(es) or CIDR | ||
| range(s) of HAProxy. The value is a space-separated list and accepts CIDR | ||
| notation, e.g. `haproxy_trusted_networks = 127.0.0.1 10.0.0.0/24 | ||
| 2001:db8::/32`. Dovecot rejects PROXY headers from any unlisted address. |
Contributor
There was a problem hiding this comment.
Could expand what "rejects" means: If a client from unlisted address connects to a haproxy listener, a warning is logged and the client is disconnected.
|
|
||
| * Consistent TLS handling at a single point | ||
| * End-to-end encryption (client → HAProxy → Dovecot) | ||
| * Reduced risk of configuration drift |
Contributor
There was a problem hiding this comment.
What configuration drift? Does this mean it avoids having to keep ssl settings in sync between Dovecot and HAProxy when STARTTLS is provided by Dovecot? Should say that clearly.
| Backend TLS only adds security when the HAProxy ↔ Dovecot path can be observed | ||
| or tampered with. When both run on the same host and traffic stays on | ||
| `127.0.0.1`, backend TLS adds CPU overhead with no threat-model benefit; a | ||
| plaintext backend with the PROXY protocol is acceptable in that case. |
Contributor
There was a problem hiding this comment.
"plaintext connection to backend"?
| ``` | ||
|
|
||
| ```doveconf[dovecot_tls_listener] | ||
| # ssl = required: HAProxy always connects via TLS, so Dovecot can enforce it |
Contributor
There was a problem hiding this comment.
A bit repetitive to have ssl = required: here
| perform SNI-based routing, or do TLS offloading. | ||
|
|
||
| Because HAProxy never decrypts the stream, the PROXYv2 header is the only way | ||
| for Dovecot to learn the original client IP. Add `send-proxy-v2` on the |
Contributor
There was a problem hiding this comment.
First sentence is confusing. PROXYv2 header is always the only way to learn the original client IP.
|
|
||
| backend dovecot_imap_tls | ||
| mode tcp | ||
| server dovecot1 127.0.0.1:993 send-proxy-v2 |
Contributor
There was a problem hiding this comment.
Again an issue with bind *:993 conflicting with Dovecot's 127.0.0.1:993.
| defaults | ||
| mode tcp | ||
| timeout client 1h | ||
| timeout server 1h |
Contributor
There was a problem hiding this comment.
How about 31min? There is hardcoded 30 min timeout in Dovecot, suggested also by IMAP RFC.
| backend dovecot_imap_tls | ||
| mode tcp | ||
| option ssl-hello-chk | ||
| server dovecot1 127.0.0.1:993 check ssl verify required \ |
Contributor
There was a problem hiding this comment.
Again here better to use non-127.0.0.1
| mode tcp | ||
| option tcp-check | ||
| tcp-check expect string * OK | ||
| server dovecot1 127.0.0.1:143 check send-proxy-v2 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
JIRA: DOV-6879