src/components/artemis/documentation/latest/proxy-protocol.html - artemis-website - Git at Google

 <!DOCTYPE html>
 <html lang="en">
 <head>
 <meta charset="UTF-8">
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <meta name="generator" content="Asciidoctor 2.0.23">
 <link rel="icon" type="image/png" href="images/favicon.png">
 <title>PROXY Protocol</title>
 <link rel="stylesheet" href="css/asciidoctor.css">
 <link rel="stylesheet" href="css/font-awesome.css">
 <link rel="stylesheet" href="css/rouge-github.css">
 <script>
     document.addEventListener("DOMContentLoaded", function() {
         const pathSegments = window.location.pathname.split('/');
         if (window.location.hostname == "artemis.apache.org" && pathSegments[pathSegments.length - 2] != "latest") {
             var message = document.createElement("div");
             message.style.margin = "20px";
             message.style.textAlign = "center";
             message.style.backgroundColor = "#FFFFE0";
             message.textContent = "Please be aware that this documentation is out of date. ";

             var link = document.createElement("a");
             link.href = "../../latest";
             link.textContent = "Here is the latest documentation.";
             message.appendChild(link);

             document.body.insertBefore(message, document.body.firstChild);
         }
     });
 </script>
 </head>
 <body class="book toc2 toc-left">
 <div id="header">
 <h1>PROXY Protocol</h1>
 <div id="toc" class="toc2">
 <div id="toctitle"><a href="index.html">User Manual for 2.52.0</a></div>
 <ul class="sectlevel1">
 <li><a href="#configuration">1. Configuration</a>
 <ul class="sectlevel2">
 <li><a href="#security">1.1. Security</a></li>
 </ul>
 </li>
 <li><a href="#management">2. Management</a></li>
 </ul>
 </div>
 </div>
 <div id="content">
 <div id="preamble">
 <div class="sectionbody">
 <div class="paragraph">
 <p>As noted in the official <a href="https://github.com/haproxy/haproxy/blob/e6a9192af68c5e385aa73c3e1cc51eb9f0cc09d6/doc/proxy-protocol.txt">PROXY Protocol documentation</a>:</p>
 </div>
 <div class="quoteblock">
 <blockquote>
 <div class="paragraph">
 <p>The PROXY protocol provides a convenient way to safely transport connection information such as a client&#8217;s address across multiple layers of NAT or TCP proxies.</p>
 </div>
 </blockquote>
 </div>
 <div class="paragraph">
 <p>This essentially allows the broker to know a client&#8217;s IP address even when the connection is established through reverse proxy that supports the PROXY protocol (e.g. HAProxy, nginx, etc.).
 Without PROXY protocol support the broker would see such client connections as coming from the proxy itself which can be misleading for administrators and complicate trouble-shooting.</p>
 </div>
 <div class="paragraph">
 <p>Both versions 1 &amp; 2 of the PROXY Protocol are supported.</p>
 </div>
 <div class="paragraph">
 <p>Any of our supported messaging protocols can be used in combination with the PROXY protocol with or without TLS.</p>
 </div>
 </div>
 </div>
 <div class="sect1">
 <h2 id="configuration"><a class="anchor" href="#configuration"></a><a class="link" href="#configuration">1. Configuration</a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>Support for the PROXY Protocol is configured on a per-acceptor basis using the <code>proxyProtocolEnabled</code> parameter, e.g.:</p>
 </div>
 <div class="listingblock">
 <div class="content">
 <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt">&lt;acceptor</span> <span class="na">name=</span><span class="s">"proxy-artemis"</span><span class="nt">&gt;</span>tcp://0.0.0.0:61616?proxyProtocolEnabled=true<span class="nt">&lt;/acceptor&gt;</span></code></pre>
 </div>
 </div>
 <div class="sect2">
 <h3 id="security"><a class="anchor" href="#security"></a><a class="link" href="#security">1.1. Security</a></h3>
 <div class="paragraph">
 <p>Support for the PROXY Protocol must be explicitly configured due to security reasons.
 As noted in the official <a href="https://github.com/haproxy/haproxy/blob/master/doc/proxy-protocol.txt">PROXY Protocol documentation</a>:</p>
 </div>
 <div class="quoteblock">
 <blockquote>
 <div class="paragraph">
 <p>The receiver MUST be configured to only receive the protocol described in this specification and MUST not try to guess whether the protocol header is present or not.
 This means that the protocol explicitly prevents port sharing between public and private access.
 Otherwise it would open a major security breach by allowing untrusted parties to spoof their connection addresses.
 <strong>The receiver SHOULD ensure proper access filtering so that only trusted proxies are allowed to use this protocol.</strong> [emphasis added]</p>
 </div>
 </blockquote>
 </div>
 <div class="paragraph">
 <p>Because of this, an acceptor using <code>proxyProtocolEnabled=true</code> can <em>only</em> accept connections using the PROXY protocol and vice versa.</p>
 </div>
 <div class="paragraph">
 <p>If a client attempts to use (or not use) the PROXY Protocol in violation of the configured value for <code>proxyProtocolEnabled</code> the broker will log a warning with the code <code>AMQ224151</code> containing details about the violation.</p>
 </div>
 </div>
 </div>
 </div>
 <div class="sect1">
 <h2 id="management"><a class="anchor" href="#management"></a><a class="link" href="#management">2. Management</a></h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>Client connections established through a reverse proxy configured with PROXY Protocol support will have 2 additional pieces of information compared to non-proxied connections:</p>
 </div>
 <div class="dlist">
 <dl>
 <dt class="hdlist1">proxyAddress</dt>
 <dd>
 <p>The IP address and port of the proxy through which the client&#8217;s connection is established.</p>
 </dd>
 <dt class="hdlist1">proxyProtocolVersion</dt>
 <dd>
 <p>The version of the PROXY Protocol used when establishing the connection from the proxy to the broker.</p>
 <div class="paragraph">
 <p>Valid values are <code>V1</code> and <code>V2</code>.</p>
 </div>
 </dd>
 </dl>
 </div>
 <div class="paragraph">
 <p>This information is available via the <code>listConnections</code> method of the <code>ActiveMQServerControl</code>.
 On the web console corresponding details will be available in the "Connections" tab.</p>
 </div>
 </div>
 </div>
 </div>
 </body>
 </html>
	<!DOCTYPE html>
	<html lang="en">
	<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<meta name="generator" content="Asciidoctor 2.0.23">
	<link rel="icon" type="image/png" href="images/favicon.png">
	<title>PROXY Protocol</title>
	<link rel="stylesheet" href="css/asciidoctor.css">
	<link rel="stylesheet" href="css/font-awesome.css">
	<link rel="stylesheet" href="css/rouge-github.css">
	<script>
	document.addEventListener("DOMContentLoaded", function() {
	const pathSegments = window.location.pathname.split('/');
	if (window.location.hostname == "artemis.apache.org" && pathSegments[pathSegments.length - 2] != "latest") {
	var message = document.createElement("div");
	message.style.margin = "20px";
	message.style.textAlign = "center";
	message.style.backgroundColor = "#FFFFE0";
	message.textContent = "Please be aware that this documentation is out of date. ";

	var link = document.createElement("a");
	link.href = "../../latest";
	link.textContent = "Here is the latest documentation.";
	message.appendChild(link);

	document.body.insertBefore(message, document.body.firstChild);
	}
	});
	</script>
	</head>
	<body class="book toc2 toc-left">
	<div id="header">
	<h1>PROXY Protocol</h1>
	<div id="toc" class="toc2">
	<div id="toctitle"><a href="index.html">User Manual for 2.52.0</a></div>
	<ul class="sectlevel1">
	<li><a href="#configuration">1. Configuration</a>
	<ul class="sectlevel2">
	<li><a href="#security">1.1. Security</a></li>
	</ul>
	</li>
	<li><a href="#management">2. Management</a></li>
	</ul>
	</div>
	</div>
	<div id="content">
	<div id="preamble">
	<div class="sectionbody">
	<div class="paragraph">
	<p>As noted in the official <a href="https://github.com/haproxy/haproxy/blob/e6a9192af68c5e385aa73c3e1cc51eb9f0cc09d6/doc/proxy-protocol.txt">PROXY Protocol documentation</a>:</p>
	</div>
	<div class="quoteblock">
	<blockquote>
	<div class="paragraph">
	<p>The PROXY protocol provides a convenient way to safely transport connection information such as a client’s address across multiple layers of NAT or TCP proxies.</p>
	</div>
	</blockquote>
	</div>
	<div class="paragraph">
	<p>This essentially allows the broker to know a client’s IP address even when the connection is established through reverse proxy that supports the PROXY protocol (e.g. HAProxy, nginx, etc.).
	Without PROXY protocol support the broker would see such client connections as coming from the proxy itself which can be misleading for administrators and complicate trouble-shooting.</p>
	</div>
	<div class="paragraph">
	<p>Both versions 1 & 2 of the PROXY Protocol are supported.</p>
	</div>
	<div class="paragraph">
	<p>Any of our supported messaging protocols can be used in combination with the PROXY protocol with or without TLS.</p>
	</div>
	</div>
	</div>
	<div class="sect1">
	<h2 id="configuration"><a class="anchor" href="#configuration"></a><a class="link" href="#configuration">1. Configuration</a></h2>
	<div class="sectionbody">
	<div class="paragraph">
	<p>Support for the PROXY Protocol is configured on a per-acceptor basis using the <code>proxyProtocolEnabled</code> parameter, e.g.:</p>
	</div>
	<div class="listingblock">
	<div class="content">
	<pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><acceptor</span> <span class="na">name=</span><span class="s">"proxy-artemis"</span><span class="nt">></span>tcp://0.0.0.0:61616?proxyProtocolEnabled=true<span class="nt"></acceptor></span></code></pre>
	</div>
	</div>
	<div class="sect2">
	<h3 id="security"><a class="anchor" href="#security"></a><a class="link" href="#security">1.1. Security</a></h3>
	<div class="paragraph">
	<p>Support for the PROXY Protocol must be explicitly configured due to security reasons.
	As noted in the official <a href="https://github.com/haproxy/haproxy/blob/master/doc/proxy-protocol.txt">PROXY Protocol documentation</a>:</p>
	</div>
	<div class="quoteblock">
	<blockquote>
	<div class="paragraph">
	<p>The receiver MUST be configured to only receive the protocol described in this specification and MUST not try to guess whether the protocol header is present or not.
	This means that the protocol explicitly prevents port sharing between public and private access.
	Otherwise it would open a major security breach by allowing untrusted parties to spoof their connection addresses.
	<strong>The receiver SHOULD ensure proper access filtering so that only trusted proxies are allowed to use this protocol.</strong> [emphasis added]</p>
	</div>
	</blockquote>
	</div>
	<div class="paragraph">
	<p>Because of this, an acceptor using <code>proxyProtocolEnabled=true</code> can <em>only</em> accept connections using the PROXY protocol and vice versa.</p>
	</div>
	<div class="paragraph">
	<p>If a client attempts to use (or not use) the PROXY Protocol in violation of the configured value for <code>proxyProtocolEnabled</code> the broker will log a warning with the code <code>AMQ224151</code> containing details about the violation.</p>
	</div>
	</div>
	</div>
	</div>
	<div class="sect1">
	<h2 id="management"><a class="anchor" href="#management"></a><a class="link" href="#management">2. Management</a></h2>
	<div class="sectionbody">
	<div class="paragraph">
	<p>Client connections established through a reverse proxy configured with PROXY Protocol support will have 2 additional pieces of information compared to non-proxied connections:</p>
	</div>
	<div class="dlist">
	<dl>
	<dt class="hdlist1">proxyAddress</dt>
	<dd>
	<p>The IP address and port of the proxy through which the client’s connection is established.</p>
	</dd>
	<dt class="hdlist1">proxyProtocolVersion</dt>
	<dd>
	<p>The version of the PROXY Protocol used when establishing the connection from the proxy to the broker.</p>
	<div class="paragraph">
	<p>Valid values are <code>V1</code> and <code>V2</code>.</p>
	</div>
	</dd>
	</dl>
	</div>
	<div class="paragraph">
	<p>This information is available via the <code>listConnections</code> method of the <code>ActiveMQServerControl</code>.
	On the web console corresponding details will be available in the "Connections" tab.</p>
	</div>
	</div>
	</div>
	</div>
	</body>
	</html>