Mercurial > prosody-modules

annotate mod_net_proxy/README.md @ 6513:5fb466693e85

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_storage_xmlarchive: Ensure list index files are removed using os.remove() on the list files leaves the new index files behind since util.datamanager does not know they are removed. Thanks Link Mauve
author Kim Alvefur <zash@zash.se>
date Tue, 07 Apr 2026 21:10:54 +0200
parents 9d3e6d2f25c7
children
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
6348
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
27 It also allows to set an outgoing (s2s) proxy, and optionally mark any of these connections secure.
2930
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
28
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
29 Usage
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
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
32 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
33 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
34
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
35 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
36 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
37 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
38
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
39 ```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
40 --[[
2963
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
41 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
42 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
43 ]]--
2930
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
44 proxy_port_mappings = {
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
45 [15222] = "c2s",
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
46 [15269] = "s2s"
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
47 }
2963
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 --[[
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
50 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
51 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
52 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
53 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
54 ]]--
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
55 proxy_trusted_proxies = {
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
56 "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
57 "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
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 --[[
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
61 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
62 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
63 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
64 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
65
504bb330e910 mod_net_proxy: Added proxy_trusted_proxies for whitelisting incoming connections
Pascal Mathis <mail@pascalmathis.com>
parents: 2961
diff changeset
66 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
67 ]]--
6348
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
68
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
69 -- make all outgoing s2s connections directly to here instead
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
70 proxy_out = { "192.168.10.1", 15270 }
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
71
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
72 --[[
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
73 Mark incoming/outgoing connections from/to proxy as secure.
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
74 This is just shorthand to override `proxy_secure_in` and `proxy_secure_out` below.
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
75 ]]--
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
76 proxy_secure = true
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
77
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
78 --[[
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
79 Mark incoming connections from proxy as secure.
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
80 The proxy must guarantee this by requiring encryption and properly validating
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
81 incoming s2s certs.
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
82 ]]--
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
83 proxy_secure_in = true
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
84
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
85 --[[
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
86 Mark outgoing connections to proxy as secure.
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
87 The proxy must guarantee this by requiring encryption, and sending client cert
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
88 for s2s connections.
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
89 ]]--
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
90 proxy_secure_out = true
2930
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
91 ```
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 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
94 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
95 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
96 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
97 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
98
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
99 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
100 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
101 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
102 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
103
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
104 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
105 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
106 `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
107 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
108
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
109 ------------- --------------------------
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
110 **Module** **Service Name**
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
111 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
112 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
113 proxy65 proxy65 (Plain)
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
114 http http (Plain)
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
115 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
116 ------------- --------------------------
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
117
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
118 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
119 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
120 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
121 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
122 instead.
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
123
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
124
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
125 Example
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
126 =======
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
127
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
128 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
129 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
130 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
131
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
132 ```lua
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
133 c2s_ports = {5222}
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
134 s2s_ports = {5269}
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
135 proxy_port_mappings = {
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
136 [15222] = "c2s",
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
137 [15269] = "s2s"
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
138 }
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
139 ```
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 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
142 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
143 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
144 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
145
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
146 ```
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
147 defaults d-xmpp
2964
1c336d0d0214 mod_net_proxy: Fixed small indentation mistake in docs
Pascal Mathis <mail@pascalmathis.com>
parents: 2963
diff changeset
148 log global
2930
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
149 mode tcp
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
150 option redispatch
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
151 option tcplog
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
152 option tcpka
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
153 option clitcpka
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
154 option srvtcpka
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 timeout connect 5s
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
157 timeout client 24h
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
158 timeout server 60m
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
159
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
160 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
161 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
162 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
163 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
164
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
165 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
166 balance roundrobin
2932
4bb3a4b726c9 mod_net_proxy: Fixed typo in example HAProxy configuration within README
Pascal Mathis <mail@pascalmathis.com>
parents: 2930
diff changeset
167 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
168 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
169
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
170 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
171 balance roundrobin
2932
4bb3a4b726c9 mod_net_proxy: Fixed typo in example HAProxy configuration within README
Pascal Mathis <mail@pascalmathis.com>
parents: 2930
diff changeset
172 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
173 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
174 ```
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
175
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
176
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
177 Limitations
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
178 ===========
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
179
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
180 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
181 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
182 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
183 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
184
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
185
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
186 Important Notes
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
187 ===============
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
188
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
189 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
190 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
191 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
192 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
193
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
194
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
195 Compatibility
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
196 =============
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
197
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
198 ----- -----
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
199 trunk Works
6348
9d3e6d2f25c7 mod_net_proxy: Add support for `proxy_out` and `proxy_secure`
moparisthebest <admin@moparisthebest.com>
parents: 5975
diff changeset
200 13 Works
4944
9d65eb3fcb15 mod_net_proxy: Fix for bitop with Lua 5.4
moparisthebest <admin@moparisthebest.com>
parents: 2974
diff changeset
201 0.12 Works
9d65eb3fcb15 mod_net_proxy: Fix for bitop with Lua 5.4
moparisthebest <admin@moparisthebest.com>
parents: 2974
diff changeset
202 0.11 Works
2930
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
203 0.10 Works
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
204 ----- -----