annotate mod_net_proxy/README.markdown @ 5551:8bfcedd93a72

mod_rest: List all error conditions in OpenAPI spec These are not handled by datamanager but by util.stanza and util.error, so they are not represented in the JSON schema file.
author Kim Alvefur <zash@zash.se>
date Sat, 17 Jun 2023 16:26:33 +0200
parents 9d65eb3fcb15
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
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
4945
9d65eb3fcb15 mod_net_proxy: Fix for bitop with Lua 5.4
moparisthebest <admin@moparisthebest.com>
parents: 2974
diff changeset
176 0.12 Works
9d65eb3fcb15 mod_net_proxy: Fix for bitop with Lua 5.4
moparisthebest <admin@moparisthebest.com>
parents: 2974
diff changeset
177 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
178 0.10 Works
9a62780e7ee2 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2
Pascal Mathis <mail@pascalmathis.com>
parents:
diff changeset
179 ----- -----