prosody-modules
9a62780e7ee2
mod_net_proxy/README.markdown

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Comparison

mod_net_proxy/README.markdown @ 2930:9a62780e7ee2

mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
author Pascal Mathis <mail@pascalmathis.com>
date Thu, 15 Mar 2018 15:26:30 +0100
child 2932:4bb3a4b726c9
comparison
equal deleted inserted replaced
2929:3a104a900af1 2930:9a62780e7ee2
1 ---
2 labels:
3 - 'Stage-Alpha'
4 summary: 'Implementation of PROXY protocol versions 1 and 2'
5 ...
6
7 Introduction
8 ============
9
10 This module implements the PROXY protocol in versions 1 and 2, which fulfills
11 the following usecase as described within the official protocol specifications:
12
13 > Relaying TCP connections through proxies generally involves a loss of the
14 > original TCP connection parameters such as source and destination addresses,
15 > ports, and so on.
16 >
17 > The PROXY protocol's goal is to fill the server's internal structures with the
18 > information collected by the proxy that the server would have been able to get
19 > by itself if the client was connecting directly to the server instead of via a
20 > proxy.
21
22 You can find more information about the PROXY protocol on
23 [the official website](https://www.haproxy.com/blog/haproxy/proxy-protocol/)
24 or within
25 [the official protocol specifications.](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt)
26
27
28 Usage
29 =====
30
31 Copy the plugin into your prosody's modules directory. And add it
32 between your enabled modules into the global section (modules\_enabled).
33
34 As the PROXY protocol specifications do not allow guessing if the PROXY protocol
35 shall be used or not, you need to configure separate ports for all the services
36 that should be exposed with PROXY protocol support:
37
38 ```lua
39 proxy_ports = {15222, 15269}
40 proxy_port_mappings = {
41 [15222] = "c2s",
42 [15269] = "s2s"
43 }
44 ```
45
46 The above example configuration, which needs to be placed in the global section,
47 would listen on both tcp/15222 and tcp/15269. All incoming connections to these ports
48 have to be initiated by a PROXYv1 or PROXYv2 sender and will get mapped to the
49 configured service name after initializating the connection.
50
51 Please note that each port handled by _mod_net_proxy_ must be mapped to another
52 service name by adding an item to _proxy_port_mappings_, otherwise a warning will
53 be printed during module initialization and all incoming connections to unmapped ports
54 will be dropped after processing the PROXY protocol requests.
55
56 The service name can be found by analyzing the source of the module, as it is the
57 same name as specified within the _name_ attribute when calling
58 `module:provides("net", ...)` to initialize a network listener. The following table
59 shows the names for the most commonly used Prosody modules:
60
61 ------------- --------------------------
62 **Module** **Service Name**
63 c2s c2s (Plain/StartTLS)
64 s2s s2s (Plain/StartTLS)
65 proxy65 proxy65 (Plain)
66 http http (Plain)
67 net_multiplex multiplex (Plain/StartTLS)
68 ------------- --------------------------
69
70 This module should work with all services that are providing ports which either
71 offer plaintext or StartTLS-based encryption. Please note that instead of using
72 this module for HTTP-based services (BOSH/WebSocket) it might be worth resorting
73 to use proxy which is able to process HTTP and insert a _X-Forwarded-For_ header
74 instead.
75
76
77 Example
78 =======
79
80 This example provides you with a Prosody server that accepts regular connections on
81 tcp/5222 (C2S) and tcp/5269 (S2S) while also offering dedicated PROXY protocol ports
82 for both modules, configured as tcp/15222 (C2S) and tcp/15269 (S2S):
83
84 ```lua
85 c2s_ports = {5222}
86 s2s_ports = {5269}
87 proxy_ports = {15222, 15269}
88 proxy_port_mappings = {
89 [15222] = "c2s",
90 [15269] = "s2s"
91 }
92 ```
93
94 After adjusting the global configuration of your Prosody server accordingly, you can
95 configure your desired sender accordingly. Below is an example for a working HAProxy
96 configuration which will listen on the default XMPP ports (5222+5269) and connect to
97 your XMPP backend running on 192.168.10.10 using the PROXYv2 protocol:
98
99 ```
100 defaults d-xmpp
101 mode tcp
102 option redispatch
103 option tcplog
104 option tcpka
105 option clitcpka
106 option srvtcpka
107
108 timeout connect 5s
109 timeout client 24h
110 timeout server 60m
111
112 frontend f-xmpp
113 bind :5222,:5269
114 use_backend b-xmpp-c2s if { dst_port eq 5222 }
115 use_backend b-xmpp-s2s if { dst_port eq 5269 }
116
117 backend b-xmpp-c2s
118 balance roundrobin
119 option independant-streams
120 server mycoolprosodybox 192.168.10.10:15222 send-proxy-v2
121
122 backend b-xmpp-s2s
123 balance roundrobin
124 option independant-streams
125 server mycoolprosodybox 192.168.10.10:15269 send-proxy-v2
126 ```
127
128
129 Limitations
130 ===========
131
132 It is currently not possible to use this module for offering PROXY protocol support
133 on SSL/TLS ports, which will automatically initiate a SSL handshake. This might be
134 possible in the future, but it currently does not look like this could easily be
135 implemented due to the current handling of such connections.
136
137
138 Important Notes
139 ===============
140
141 Please do not expose any ports offering PROXY protocol to the internet - while regular
142 clients will be unable to use them anyways, it is outright dangerous and allows anyone
143 to spoof the actual IP address. It is highly recommended to only allow PROXY
144 connections from trusted sources, e.g. your loadbalancer.
145
146
147 Compatibility
148 =============
149
150 ----- -----
151 trunk Works
152 0.10 Works
153 ----- -----