Mercurial > prosody-modules

annotate mod_net_proxy/README.markdown @ 4078:2f0c8670d2fa

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_invites: Add API to create account reset invites (from Snikket)
author Matthew Wild <mwild1@gmail.com>
date Mon, 07 Sep 2020 13:00:43 +0100
parents cd36b16f6b35
children 9d65eb3fcb15
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2930
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
1 ---
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
2 labels:
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
3 - 'Stage-Alpha'
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
4 summary: 'Implementation of PROXY protocol versions 1 and 2'
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
5 ...
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
6
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
7 Introduction
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
8 ============
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
9
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
10 This module implements the PROXY protocol in versions 1 and 2, which fulfills
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
11 the following usecase as described within the official protocol specifications:
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
12
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
13 > Relaying TCP connections through proxies generally involves a loss of the
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
14 > original TCP connection parameters such as source and destination addresses,
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
15 > ports, and so on.
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
16 >
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
17 > The PROXY protocol's goal is to fill the server's internal structures with the
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
18 > information collected by the proxy that the server would have been able to get
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
19 > by itself if the client was connecting directly to the server instead of via a
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
20 > proxy.
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
21
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
22 You can find more information about the PROXY protocol on
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
23 [the official website](https://www.haproxy.com/blog/haproxy/proxy-protocol/)
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
24 or within
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
25 [the official protocol specifications.](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt)
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
26
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
27
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
28 Usage
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
29 =====
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
30
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
31 Copy the plugin into your prosody's modules directory. And add it
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
32 between your enabled modules into the global section (modules\_enabled).
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
33
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
34 As the PROXY protocol specifications do not allow guessing if the PROXY protocol
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
35 shall be used or not, you need to configure separate ports for all the services
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
36 that should be exposed with PROXY protocol support:
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
37
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
38 ```lua
2961
33227efa2cdc mod_net_proxy: Automatically listen on all mapped ports if proxy_ports was not configured
Pascal Mathis <mail@pascalmathis.com>
parents: 2959
diff changeset
39 --[[
2963
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
40 Maps TCP ports to a specific Prosody network service. Further information about
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
41 available service names can be found further down below in the module documentation.
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
42 ]]--
2930
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
43 proxy_port_mappings = {
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
44 [15222] = "c2s",
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
45 [15269] = "s2s"
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
46 }
2963
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
47
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
48 --[[
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
49 Specifies a list of trusted hosts or networks which may use the PROXY protocol
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
50 If not specified, it will default to: 127.0.0.1, ::1 (local connections only)
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
51 An empty table ({}) can be configured to allow connections from any source.
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
52 Please read the module documentation about potential security impact.
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
53 ]]--
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
54 proxy_trusted_proxies = {
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
55 "192.168.10.1",
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
56 "172.16.0.0/16"
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
57 }
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
58
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
59 --[[
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
60 While you can manually override the ports this module is listening on with
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
61 the "proxy_ports" directive, it is highly recommended to not set it and instead
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
62 only configure the appropriate mappings with "proxy_port_mappings", which will
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
63 automatically start listening on all mapped ports.
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
64
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
65 Example: proxy_ports = { 15222, 15269 }
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
66 ]]--
2930
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
67 ```
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
68
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
69 The above example configuration, which needs to be placed in the global section,
2963
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
70 would listen on both tcp/15222 and tcp/15269. All incoming connections have to
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
71 originate from trusted hosts/networks (configured by _proxy_trusted_proxies_) and
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
72 must be initiated by a PROXYv1 or PROXYv2 sender. After processing the PROXY
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
73 protocol, those connections will get mapped to the configured service name.
2930
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
74
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
75 Please note that each port handled by _mod_net_proxy_ must be mapped to another
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
76 service name by adding an item to _proxy_port_mappings_, otherwise a warning will
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
77 be printed during module initialization and all incoming connections to unmapped ports
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
78 will be dropped after processing the PROXY protocol requests.
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
79
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
80 The service name can be found by analyzing the source of the module, as it is the
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
81 same name as specified within the _name_ attribute when calling
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
82 `module:provides("net", ...)` to initialize a network listener. The following table
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
83 shows the names for the most commonly used Prosody modules:
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
84
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
85 ------------- --------------------------
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
86 **Module** **Service Name**
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
87 c2s c2s (Plain/StartTLS)
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
88 s2s s2s (Plain/StartTLS)
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
89 proxy65 proxy65 (Plain)
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
90 http http (Plain)
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
91 net_multiplex multiplex (Plain/StartTLS)
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
92 ------------- --------------------------
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
93
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
94 This module should work with all services that are providing ports which either
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
95 offer plaintext or StartTLS-based encryption. Please note that instead of using
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
96 this module for HTTP-based services (BOSH/WebSocket) it might be worth resorting
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
97 to use proxy which is able to process HTTP and insert a _X-Forwarded-For_ header
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
98 instead.
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
99
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
100
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
101 Example
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
102 =======
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
103
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
104 This example provides you with a Prosody server that accepts regular connections on
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
105 tcp/5222 (C2S) and tcp/5269 (S2S) while also offering dedicated PROXY protocol ports
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
106 for both modules, configured as tcp/15222 (C2S) and tcp/15269 (S2S):
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
107
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
108 ```lua
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
109 c2s_ports = {5222}
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
110 s2s_ports = {5269}
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
111 proxy_port_mappings = {
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
112 [15222] = "c2s",
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
113 [15269] = "s2s"
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
114 }
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
115 ```
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
116
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
117 After adjusting the global configuration of your Prosody server accordingly, you can
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
118 configure your desired sender accordingly. Below is an example for a working HAProxy
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
119 configuration which will listen on the default XMPP ports (5222+5269) and connect to
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
120 your XMPP backend running on 192.168.10.10 using the PROXYv2 protocol:
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
121
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
122 ```
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
123 defaults d-xmpp
2964
1c336d0d0214 mod_net_proxy: Fixed small indentation mistake in docs
Pascal Mathis <mail@pascalmathis.com>
parents: 2963
diff changeset
124 log global
2930
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
125 mode tcp
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
126 option redispatch
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
127 option tcplog
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
128 option tcpka
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
129 option clitcpka
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
130 option srvtcpka
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
131
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
132 timeout connect 5s
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
133 timeout client 24h
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
134 timeout server 60m
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
135
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
136 frontend f-xmpp
2974
cd36b16f6b35 mod_net_proxy: Updated HAProxy example configuration to listen on v4+v6
Pascal Mathis <mail@pascalmathis.com>
parents: 2964
diff changeset
137 bind :::5222,:::5269 v4v6
2930
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
138 use_backend b-xmpp-c2s if { dst_port eq 5222 }
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
139 use_backend b-xmpp-s2s if { dst_port eq 5269 }
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
140
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
141 backend b-xmpp-c2s
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
142 balance roundrobin
2932
4bb3a4b726c9 mod_net_proxy: Fixed typo in example HAProxy configuration within README
Pascal Mathis <mail@pascalmathis.com>
parents: 2930
diff changeset
143 option independent-streams
2930
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
144 server mycoolprosodybox 192.168.10.10:15222 send-proxy-v2
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
145
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
146 backend b-xmpp-s2s
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
147 balance roundrobin
2932
4bb3a4b726c9 mod_net_proxy: Fixed typo in example HAProxy configuration within README
Pascal Mathis <mail@pascalmathis.com>
parents: 2930
diff changeset
148 option independent-streams
2930
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
149 server mycoolprosodybox 192.168.10.10:15269 send-proxy-v2
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
150 ```
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
151
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
152
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
153 Limitations
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
154 ===========
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
155
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
156 It is currently not possible to use this module for offering PROXY protocol support
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
157 on SSL/TLS ports, which will automatically initiate a SSL handshake. This might be
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
158 possible in the future, but it currently does not look like this could easily be
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
159 implemented due to the current handling of such connections.
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
160
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
161
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
162 Important Notes
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
163 ===============
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
164
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
165 Please do not expose any ports offering PROXY protocol to the internet - while regular
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
166 clients will be unable to use them anyways, it is outright dangerous and allows anyone
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
167 to spoof the actual IP address. It is highly recommended to only allow PROXY
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
168 connections from trusted sources, e.g. your loadbalancer.
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
169
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
170
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
171 Compatibility
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
172 =============
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
173
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
174 ----- -----
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
175 trunk Works
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
176 0.10 Works
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
177 ----- -----