Mercurial > prosody-modules

comparison mod_net_proxy/README.md @ 5975:fe081789f7b5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
All community modules: Unify file extention of Markdown files to .md
author Menel <menel@snikket.de>
date Tue, 22 Oct 2024 10:26:01 +0200
parents mod_net_proxy/README.markdown@9d65eb3fcb15
children 9d3e6d2f25c7
comparison
equal deleted inserted replaced
5974:5a65a632d5b9 5975:fe081789f7b5
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 --[[
40 Maps TCP ports to a specific Prosody network service. Further information about
41 available service names can be found further down below in the module documentation.
42 ]]--
43 proxy_port_mappings = {
44 [15222] = "c2s",
45 [15269] = "s2s"
46 }
47
48 --[[
49 Specifies a list of trusted hosts or networks which may use the PROXY protocol
50 If not specified, it will default to: 127.0.0.1, ::1 (local connections only)
51 An empty table ({}) can be configured to allow connections from any source.
52 Please read the module documentation about potential security impact.
53 ]]--
54 proxy_trusted_proxies = {
55 "192.168.10.1",
56 "172.16.0.0/16"
57 }
58
59 --[[
60 While you can manually override the ports this module is listening on with
61 the "proxy_ports" directive, it is highly recommended to not set it and instead
62 only configure the appropriate mappings with "proxy_port_mappings", which will
63 automatically start listening on all mapped ports.
64
65 Example: proxy_ports = { 15222, 15269 }
66 ]]--
67 ```
68
69 The above example configuration, which needs to be placed in the global section,
70 would listen on both tcp/15222 and tcp/15269. All incoming connections have to
71 originate from trusted hosts/networks (configured by _proxy_trusted_proxies_) and
72 must be initiated by a PROXYv1 or PROXYv2 sender. After processing the PROXY
73 protocol, those connections will get mapped to the configured service name.
74
75 Please note that each port handled by _mod_net_proxy_ must be mapped to another
76 service name by adding an item to _proxy_port_mappings_, otherwise a warning will
77 be printed during module initialization and all incoming connections to unmapped ports
78 will be dropped after processing the PROXY protocol requests.
79
80 The service name can be found by analyzing the source of the module, as it is the
81 same name as specified within the _name_ attribute when calling
82 `module:provides("net", ...)` to initialize a network listener. The following table
83 shows the names for the most commonly used Prosody modules:
84
85 ------------- --------------------------
86 **Module** **Service Name**
87 c2s c2s (Plain/StartTLS)
88 s2s s2s (Plain/StartTLS)
89 proxy65 proxy65 (Plain)
90 http http (Plain)
91 net_multiplex multiplex (Plain/StartTLS)
92 ------------- --------------------------
93
94 This module should work with all services that are providing ports which either
95 offer plaintext or StartTLS-based encryption. Please note that instead of using
96 this module for HTTP-based services (BOSH/WebSocket) it might be worth resorting
97 to use proxy which is able to process HTTP and insert a _X-Forwarded-For_ header
98 instead.
99
100
101 Example
102 =======
103
104 This example provides you with a Prosody server that accepts regular connections on
105 tcp/5222 (C2S) and tcp/5269 (S2S) while also offering dedicated PROXY protocol ports
106 for both modules, configured as tcp/15222 (C2S) and tcp/15269 (S2S):
107
108 ```lua
109 c2s_ports = {5222}
110 s2s_ports = {5269}
111 proxy_port_mappings = {
112 [15222] = "c2s",
113 [15269] = "s2s"
114 }
115 ```
116
117 After adjusting the global configuration of your Prosody server accordingly, you can
118 configure your desired sender accordingly. Below is an example for a working HAProxy
119 configuration which will listen on the default XMPP ports (5222+5269) and connect to
120 your XMPP backend running on 192.168.10.10 using the PROXYv2 protocol:
121
122 ```
123 defaults d-xmpp
124 log global
125 mode tcp
126 option redispatch
127 option tcplog
128 option tcpka
129 option clitcpka
130 option srvtcpka
131
132 timeout connect 5s
133 timeout client 24h
134 timeout server 60m
135
136 frontend f-xmpp
137 bind :::5222,:::5269 v4v6
138 use_backend b-xmpp-c2s if { dst_port eq 5222 }
139 use_backend b-xmpp-s2s if { dst_port eq 5269 }
140
141 backend b-xmpp-c2s
142 balance roundrobin
143 option independent-streams
144 server mycoolprosodybox 192.168.10.10:15222 send-proxy-v2
145
146 backend b-xmpp-s2s
147 balance roundrobin
148 option independent-streams
149 server mycoolprosodybox 192.168.10.10:15269 send-proxy-v2
150 ```
151
152
153 Limitations
154 ===========
155
156 It is currently not possible to use this module for offering PROXY protocol support
157 on SSL/TLS ports, which will automatically initiate a SSL handshake. This might be
158 possible in the future, but it currently does not look like this could easily be
159 implemented due to the current handling of such connections.
160
161
162 Important Notes
163 ===============
164
165 Please do not expose any ports offering PROXY protocol to the internet - while regular
166 clients will be unable to use them anyways, it is outright dangerous and allows anyone
167 to spoof the actual IP address. It is highly recommended to only allow PROXY
168 connections from trusted sources, e.g. your loadbalancer.
169
170
171 Compatibility
172 =============
173
174 ----- -----
175 trunk Works
176 0.12 Works
177 0.11 Works
178 0.10 Works
179 ----- -----