Mercurial > prosody-modules

annotate mod_net_proxy/README.md @ 6549:d2e50b587721

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_firewall: marks: switch to keyval+ store API
author Matthew Wild <mwild1@gmail.com>
date Sun, 24 May 2026 10:49:09 +0100
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 ----- -----