prosody-modules: mod_net_proxy/README.markdown annotate

annotate mod_net_proxy/README.markdown @ 4738:5aee8d86629a

mod_bookmarks2: Fix handling of nick and password elements This form of child retrieval fails when the stanza elements internally don't have an 'xmlns' attribute, which can happen sometimes for some reason, including when they have been constructed via the stanza builder API. When that is the case then the explicit namespace arguemnt does not match the nil value of the internal attribute. Calling `:get_child()` without the namespace argument does the right thing here, with both nil and the parent namespace as valid values for the internal attribute.

author	Kim Alvefur <zash@zash.se>
date	Wed, 03 Nov 2021 21:11:55 +0100
parents	cd36b16f6b35
children	9d65eb3fcb15

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

Mercurial > prosody-modules

annotate mod_net_proxy/README.markdown @ 4738:5aee8d86629a