# HG changeset patch # User Pascal Mathis # Date 1521123990 -3600 # Node ID 9a62780e7ee27ab91d3b69e83c0833bc23e34570 # Parent 3a104a900af111af29cec9114f2418dd7287cfe4 mod_net_proxy: New module implementing PROXY protocol versions 1 and 2 diff -r 3a104a900af1 -r 9a62780e7ee2 mod_net_proxy/README.markdown --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_net_proxy/README.markdown Thu Mar 15 15:26:30 2018 +0100 @@ -0,0 +1,153 @@ +--- +labels: +- 'Stage-Alpha' +summary: 'Implementation of PROXY protocol versions 1 and 2' +... + +Introduction +============ + +This module implements the PROXY protocol in versions 1 and 2, which fulfills +the following usecase as described within the official protocol specifications: + +> Relaying TCP connections through proxies generally involves a loss of the +> original TCP connection parameters such as source and destination addresses, +> ports, and so on. +> +> The PROXY protocol's goal is to fill the server's internal structures with the +> information collected by the proxy that the server would have been able to get +> by itself if the client was connecting directly to the server instead of via a +> proxy. + +You can find more information about the PROXY protocol on +[the official website](https://www.haproxy.com/blog/haproxy/proxy-protocol/) +or within +[the official protocol specifications.](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) + + +Usage +===== + +Copy the plugin into your prosody's modules directory. And add it +between your enabled modules into the global section (modules\_enabled). + +As the PROXY protocol specifications do not allow guessing if the PROXY protocol +shall be used or not, you need to configure separate ports for all the services +that should be exposed with PROXY protocol support: + +```lua +proxy_ports = {15222, 15269} +proxy_port_mappings = { + [15222] = "c2s", + [15269] = "s2s" +} +``` + +The above example configuration, which needs to be placed in the global section, +would listen on both tcp/15222 and tcp/15269. All incoming connections to these ports +have to be initiated by a PROXYv1 or PROXYv2 sender and will get mapped to the +configured service name after initializating the connection. + +Please note that each port handled by _mod_net_proxy_ must be mapped to another +service name by adding an item to _proxy_port_mappings_, otherwise a warning will +be printed during module initialization and all incoming connections to unmapped ports +will be dropped after processing the PROXY protocol requests. + +The service name can be found by analyzing the source of the module, as it is the +same name as specified within the _name_ attribute when calling +`module:provides("net", ...)` to initialize a network listener. The following table +shows the names for the most commonly used Prosody modules: + + ------------- -------------------------- + **Module** **Service Name** + c2s c2s (Plain/StartTLS) + s2s s2s (Plain/StartTLS) + proxy65 proxy65 (Plain) + http http (Plain) + net_multiplex multiplex (Plain/StartTLS) + ------------- -------------------------- + +This module should work with all services that are providing ports which either +offer plaintext or StartTLS-based encryption. Please note that instead of using +this module for HTTP-based services (BOSH/WebSocket) it might be worth resorting +to use proxy which is able to process HTTP and insert a _X-Forwarded-For_ header +instead. + + +Example +======= + +This example provides you with a Prosody server that accepts regular connections on +tcp/5222 (C2S) and tcp/5269 (S2S) while also offering dedicated PROXY protocol ports +for both modules, configured as tcp/15222 (C2S) and tcp/15269 (S2S): + +```lua +c2s_ports = {5222} +s2s_ports = {5269} +proxy_ports = {15222, 15269} +proxy_port_mappings = { + [15222] = "c2s", + [15269] = "s2s" +} +``` + +After adjusting the global configuration of your Prosody server accordingly, you can +configure your desired sender accordingly. Below is an example for a working HAProxy +configuration which will listen on the default XMPP ports (5222+5269) and connect to +your XMPP backend running on 192.168.10.10 using the PROXYv2 protocol: + +``` +defaults d-xmpp + mode tcp + option redispatch + option tcplog + option tcpka + option clitcpka + option srvtcpka + + timeout connect 5s + timeout client 24h + timeout server 60m + +frontend f-xmpp + bind :5222,:5269 + use_backend b-xmpp-c2s if { dst_port eq 5222 } + use_backend b-xmpp-s2s if { dst_port eq 5269 } + +backend b-xmpp-c2s + balance roundrobin + option independant-streams + server mycoolprosodybox 192.168.10.10:15222 send-proxy-v2 + +backend b-xmpp-s2s + balance roundrobin + option independant-streams + server mycoolprosodybox 192.168.10.10:15269 send-proxy-v2 +``` + + +Limitations +=========== + +It is currently not possible to use this module for offering PROXY protocol support +on SSL/TLS ports, which will automatically initiate a SSL handshake. This might be +possible in the future, but it currently does not look like this could easily be +implemented due to the current handling of such connections. + + +Important Notes +=============== + +Please do not expose any ports offering PROXY protocol to the internet - while regular +clients will be unable to use them anyways, it is outright dangerous and allows anyone +to spoof the actual IP address. It is highly recommended to only allow PROXY +connections from trusted sources, e.g. your loadbalancer. + + +Compatibility +============= + + ----- ----- + trunk Works + 0.10 Works + ----- ----- diff -r 3a104a900af1 -r 9a62780e7ee2 mod_net_proxy/mod_net_proxy.lua --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mod_net_proxy/mod_net_proxy.lua Thu Mar 15 15:26:30 2018 +0100 @@ -0,0 +1,378 @@ +-- mod_net_proxy.lua +-- Copyright (C) 2018 Pascal Mathis +-- +-- Implementation of PROXY protocol versions 1 and 2 +-- Specifications: https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt + +module:set_global(); + +-- Imports +local softreq = require "util.dependencies".softreq; +local bit = assert(softreq "bit" or softreq "bit32", "No bit module found. See https://prosody.im/doc/depends#bitop"); +local hex = require "util.hex"; +local ip = require "util.ip"; +local net = require "util.net"; +local portmanager = require "core.portmanager"; + +-- Utility Functions +local function _table_invert(input) + local output = {}; + for key, value in pairs(input) do + output[value] = key; + end + return output; +end + +-- Constants +local ADDR_FAMILY = { UNSPEC = 0x0, INET = 0x1, INET6 = 0x2, UNIX = 0x3 }; +local ADDR_FAMILY_STR = _table_invert(ADDR_FAMILY); +local TRANSPORT = { UNSPEC = 0x0, STREAM = 0x1, DGRAM = 0x2 }; +local TRANSPORT_STR = _table_invert(TRANSPORT); + +local PROTO_MAX_HEADER_LENGTH = 256; +local PROTO_HANDLERS = { + PROXYv1 = { signature = hex.from("50524F5859"), callback = nil }, + PROXYv2 = { signature = hex.from("0D0A0D0A000D0A515549540A"), callback = nil } +}; +local PROTO_HANDLER_STATUS = { SUCCESS = 0, POSTPONE = 1, FAILURE = 2 }; + +-- Persistent In-Memory Storage +local sessions = {}; +local mappings = {}; + +-- Proxy Data Methods +local proxy_data_mt = {}; proxy_data_mt.__index = proxy_data_mt; + +function proxy_data_mt:describe() + return string.format("proto=%s/%s src=%s:%d dst=%s:%d", + self:addr_family_str(), self:transport_str(), self:src_addr(), self:src_port(), self:dst_addr(), self:dst_port()); +end + +function proxy_data_mt:addr_family_str() + return ADDR_FAMILY_STR[self._addr_family] or ADDR_FAMILY_STR[ADDR_FAMILY.UNSPEC]; +end + +function proxy_data_mt:transport_str() + return TRANSPORT_STR[self._transport] or TRANSPORT_STR[TRANSPORT.UNSPEC]; +end + +function proxy_data_mt:version() + return self._version; +end + +function proxy_data_mt:addr_family() + return self._addr_family; +end + +function proxy_data_mt:transport() + return self._transport; +end + +function proxy_data_mt:src_addr() + return self._src_addr; +end + +function proxy_data_mt:src_port() + return self._src_port; +end + +function proxy_data_mt:dst_addr() + return self._dst_addr; +end + +function proxy_data_mt:dst_port() + return self._dst_port; +end + +-- Protocol Handler Functions +PROTO_HANDLERS["PROXYv1"].callback = function(conn, session) + local addr_family_mappings = { TCP4 = ADDR_FAMILY.INET, TCP6 = ADDR_FAMILY.INET6 }; + + -- Postpone processing if CRLF (PROXYv1 header terminator) does not exist within buffer + if session.buffer:find("\r\n") == nil then + return PROTO_HANDLER_STATUS.POSTPONE, nil; + end + + -- Declare header pattern and match current buffer against pattern + local header_pattern = "^PROXY (%S+) (%S+) (%S+) (%d+) (%d+)\r\n"; + local addr_family, src_addr, dst_addr, src_port, dst_port = session.buffer:match(header_pattern); + src_port, dst_port = tonumber(src_port), tonumber(dst_port); + + -- Ensure that header was successfully parsed and contains a valid address family + if addr_family == nil or src_addr == nil or dst_addr == nil or src_port == nil or dst_port == nil then + module:log("warn", "Received unparseable PROXYv1 header from %s", conn:ip()); + return PROTO_HANDLER_STATUS.FAILURE, nil; + end + if addr_family_mappings[addr_family] == nil then + module:log("warn", "Received invalid PROXYv1 address family from %s: %s", conn:ip(), addr_family); + return PROTO_HANDLER_STATUS.FAILURE, nil; + end + + -- Ensure that received source and destination ports are within 1 and 65535 (0xFFFF) + if src_port <= 0 or src_port >= 0xFFFF then + module:log("warn", "Received invalid PROXYv1 source port from %s: %d", conn:ip(), src_port); + return PROTO_HANDLER_STATUS.FAILURE, nil; + end + if dst_port <= 0 or dst_port >= 0xFFFF then + module:log("warn", "Received invalid PROXYv1 destination port from %s: %d", conn:ip(), dst_port); + return PROTO_HANDLER_STATUS.FAILURE, nil; + end + + -- Ensure that received source and destination address can be parsed + local _, err = ip.new_ip(src_addr); + if err ~= nil then + module:log("warn", "Received unparseable PROXYv1 source address from %s: %s", conn:ip(), src_addr); + end + _, err = ip.new_ip(dst_addr); + if err ~= nil then + module:log("warn", "Received unparseable PROXYv1 destination address from %s: %s", conn:ip(), dst_addr); + return PROTO_HANDLER_STATUS.FAILURE, nil; + end + + -- Strip parsed header from session buffer and build proxy data + session.buffer = session.buffer:gsub(header_pattern, ""); + + local proxy_data = { + _version = 1, + _addr_family = addr_family, _transport = TRANSPORT.STREAM, + _src_addr = src_addr, _src_port = src_port, + _dst_addr = dst_addr, _dst_port = dst_port + }; + setmetatable(proxy_data, proxy_data_mt); + + -- Return successful response with gathered proxy data + return PROTO_HANDLER_STATUS.SUCCESS, proxy_data; +end + +PROTO_HANDLERS["PROXYv2"].callback = function(conn, session) + -- Postpone processing if less than 16 bytes are available + if #session.buffer < 16 then + return PROTO_HANDLER_STATUS.POSTPONE, nil; + end + + -- Parse first 16 bytes of protocol header + local version = bit.rshift(bit.band(session.buffer:byte(13), 0xF0), 4); + local command = bit.band(session.buffer:byte(13), 0x0F); + local addr_family = bit.rshift(bit.band(session.buffer:byte(14), 0xF0), 4); + local transport = bit.band(session.buffer:byte(14), 0x0F); + local length = bit.bor(session.buffer:byte(16), bit.lshift(session.buffer:byte(15), 8)); + + -- Postpone processing if less than 16+ bytes are available + if #session.buffer < 16 + length then + return PROTO_HANDLER_STATUS.POSTPONE, nil; + end + + -- Ensure that version number is correct + if version ~= 0x2 then + module:log("error", "Received unsupported PROXYv2 version from %s: %d", conn:ip(), version); + return PROTO_HANDLER_STATUS.FAILURE, nil; + end + + local payload = session.buffer:sub(17); + if command == 0x0 then + -- Gather source/destination addresses and ports from local socket + local src_addr, src_port = conn:socket():getpeername(); + local dst_addr, dst_port = conn:socket():getsockname(); + + -- Build proxy data based on real connection information + local proxy_data = { + _version = version, + _addr_family = addr_family, _transport = transport, + _src_addr = src_addr, _src_port = src_port, + _dst_addr = dst_addr, _dst_port = dst_port + }; + setmetatable(proxy_data, proxy_data_mt); + + -- Return successful response with gathered proxy data + return PROTO_HANDLER_STATUS.SUCCESS, proxy_data; + elseif command == 0x1 then + local offset = 1; + local src_addr, src_port, dst_addr, dst_port; + + -- Verify transport protocol is either STREAM or DGRAM + if transport ~= TRANSPORT.STREAM and transport ~= TRANSPORT.DGRAM then + module:log("warn", "Received unsupported PROXYv2 transport from %s: 0x%02X", conn:ip(), transport); + return PROTO_HANDLER_STATUS.FAILURE, nil; + end + + -- Parse source and destination addresses + if addr_family == ADDR_FAMILY.INET then + src_addr = net.ntop(payload:sub(offset, offset + 3)); offset = offset + 4; + dst_addr = net.ntop(payload:sub(offset, offset + 3)); offset = offset + 4; + elseif addr_family == ADDR_FAMILY.INET6 then + src_addr = net.ntop(payload:sub(offset, offset + 15)); offset = offset + 16; + dst_addr = net.ntop(payload:sub(offset, offset + 15)); offset = offset + 16; + elseif addr_family == ADDR_FAMILY.UNIX then + src_addr = payload:sub(offset, offset + 107); offset = offset + 108; + dst_addr = payload:sub(offset, offset + 107); offset = offset + 108; + end + + -- Parse source and destination ports + if addr_family == ADDR_FAMILY.INET or addr_family == ADDR_FAMILY.INET6 then + src_port = bit.bor(payload:byte(offset + 1), bit.lshift(payload:byte(offset), 8)); offset = offset + 2; + -- luacheck: ignore 311 + dst_port = bit.bor(payload:byte(offset + 1), bit.lshift(payload:byte(offset), 8)); offset = offset + 2; + end + + -- Strip parsed header from session buffer and build proxy data + session.buffer = session.buffer:sub(17 + length); + + local proxy_data = { + _version = version, + _addr_family = addr_family, _transport = transport, + _src_addr = src_addr, _src_port = src_port, + _dst_addr = dst_addr, _dst_port = dst_port + }; + setmetatable(proxy_data, proxy_data_mt); + + -- Return successful response with gathered proxy data + return PROTO_HANDLER_STATUS.SUCCESS, proxy_data; + else + module:log("error", "Received unsupported PROXYv2 command from %s: 0x%02X", conn:ip(), command); + return PROTO_HANDLER_STATUS.FAILURE, nil; + end +end + +-- Wrap an existing connection with the provided proxy data. This will override several methods of the 'conn' object to +-- return the proxied source instead of the source which initiated the TCP connection. Afterwards, the listener of the +-- connection gets set according to the globally defined port<>service mappings and the methods 'onconnect' and +-- 'onincoming' are being called manually with the current session buffer. +local function wrap_proxy_connection(conn, session, proxy_data) + -- Override and add functions of 'conn' object when source information has been collected + conn.proxyip, conn.proxyport = conn.ip, conn.port; + if proxy_data:src_addr() ~= nil and proxy_data:src_port() ~= nil then + conn.ip = function() + return proxy_data:src_addr(); + end + conn.port = function() + return proxy_data:src_port(); + end + conn.clientport = conn.port; + end + + -- Attempt to find service by processing port<>service mappings + local mapping = mappings[conn:serverport()]; + if mapping == nil then + conn:close(); + module:log("error", "Connection %s@%s terminated: Could not find mapping for port %d", + conn:ip(), conn:proxyip(), conn:serverport()); + return; + end + + if mapping.service == nil then + local service = portmanager.get_service(mapping.service_name); + + if service ~= nil then + mapping.service = service; + else + conn:close(); + module:log("error", "Connection %s@%s terminated: Could not process mapping for unknown service %s", + conn:ip(), conn:proxyip(), mapping.service_name); + return; + end + end + + -- Pass connection to actual service listener and simulate onconnect/onincoming callbacks + local service_listener = mapping.service.listener; + + module:log("info", "Passing proxied connection %s:%d to service %s", conn:ip(), conn:port(), mapping.service_name); + conn:setlistener(service_listener); + if service_listener.onconnect then + service_listener.onconnect(conn); + end + return service_listener.onincoming(conn, session.buffer); +end + +-- Network Listener Methods +local listener = {}; + +function listener.onconnect(conn) + sessions[conn] = { + handler = nil; + buffer = nil; + }; +end + +function listener.onincoming(conn, data) + -- Abort processing if no data has been received + if not data then + return; + end + + -- Lookup session for connection and append received data to buffer + local session = sessions[conn]; + session.buffer = session.buffer and session.buffer .. data or data; + + -- Attempt to determine protocol handler if not done previously + if session.handler == nil then + -- Match current session buffer against all known protocol signatures to determine protocol handler + for handler_name, handler in pairs(PROTO_HANDLERS) do + if session.buffer:find("^" .. handler.signature) ~= nil then + session.handler = handler.callback; + module:log("debug", "Detected %s connection from %s:%d", handler_name, conn:ip(), conn:port()); + break; + end + end + + -- Decide between waiting for a complete header signature or terminating the connection when no handler has been found + if session.handler == nil then + -- Terminate connection if buffer size has exceeded tolerable maximum size + if #session.buffer > PROTO_MAX_HEADER_LENGTH then + conn:close(); + module:log("warn", "Connection %s:%d terminated: No valid PROXY header within %d bytes", + conn:ip(), conn:port(), PROTO_MAX_HEADER_LENGTH); + end + + -- Skip further processing without a valid protocol handler + module:log("debug", "No valid header signature detected from %s:%d, waiting for more data...", + conn:ip(), conn:port()); + return; + end + end + + -- Execute proxy protocol handler and process response + local response, proxy_data = session.handler(conn, session); + if response == PROTO_HANDLER_STATUS.SUCCESS then + module:log("info", "Received PROXY header from %s: %s", conn:ip(), proxy_data:describe()); + return wrap_proxy_connection(conn, session, proxy_data); + elseif response == PROTO_HANDLER_STATUS.POSTPONE then + module:log("debug", "Postponed parsing of incomplete PROXY header received from %s", conn:ip()); + return; + elseif response == PROTO_HANDLER_STATUS.FAILURE then + conn:close(); + module:log("warn", "Connection %s terminated: Could not process PROXY header from client, " + + "see previous log messages.", conn:ip()); + return; + else + -- This code should be never reached, but is included for completeness + conn:close(); + module:log("error", "Connection terminated: Received invalid protocol handler response with code %d", response); + return; + end +end + +function listener.ondisconnect(conn) + sessions[conn] = nil; +end + +listener.ondetach = listener.ondisconnect; + +-- Initialize the module by processing all configured port mappings +local config_ports = module:get_option_set("proxy_ports", {}); +local config_mappings = module:get_option("proxy_port_mappings", {}); +for port in config_ports do + if config_mappings[port] ~= nil then + mappings[port] = { + service_name = config_mappings[port], + service = nil + }; + else + module:log("warn", "No port<>service mapping found for port: %d", port); + end +end + +-- Register the previously declared network listener +module:provides("net", { + name = "proxy"; + listener = listener; +});