23 lines
26 KiB
HTML
23 lines
26 KiB
HTML
<html><head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
<title>norp User's Guide</title><link rel="stylesheet" type="text/css" href="html.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><meta name="description" content="The NRL Nack-Oriented Proxy (norp) project includes software for an RFC 1928 SOCKS5-compatible proxy server daemon that is able to use the RFC 5740 Nack-Oriented Reliable Multicast (NORM) transport protocol for efficient and robust data transfer between norp proxy instances. The norp proxy automatically supports conventional SOCKS TCP proxy operation when a remote norp peer is unavailable. This software was developed by the Naval Research Laboratory (NRL) PROTocol Engineering Advanced Networking Research Group. The NRL reference implementation of NORM used here is available from http://www.nrl.navy.mil/itd/ncs/products/norm."></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" title="norp User's Guide"><div class="titlepage"><div><div><h2 class="title"><a name="d0e2"></a><span class="inlinemediaobject"><img src="resources/ProteanLogo.png" align="middle" width="162"></span> <span class="emphasis"><em>norp</em></span> User's Guide</h2></div><div><div class="abstract" title="Abstract"><p class="title"><b>Abstract</b></p><p>The NRL Nack-Oriented Proxy (<span class="emphasis"><em>norp</em></span>) project includes software for an RFC 1928 SOCKS5-compatible proxy server daemon that is able to use the RFC 5740 Nack-Oriented Reliable Multicast (NORM) transport protocol for efficient and robust data transfer between <span class="emphasis"><em>norp</em></span> proxy instances. The <span class="emphasis"><em>norp</em></span> proxy automatically supports conventional SOCKS TCP proxy operation when a remote <span class="emphasis"><em>norp</em></span> peer is unavailable. This software was developed by the <a class="ulink" href="http://www.nrl.navy.mil/" target="_top">Naval Research Laboratory</a> (NRL) PROTocol Engineering Advanced Networking Research Group. The NRL reference implementation of NORM used here is available from <a class="ulink" href="http://www.nrl.navy.mil/itd/ncs/products/norm" target="_top">http://www.nrl.navy.mil/itd/ncs/products/norm</a>.</p></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#d0e37">1. Overview</a></span></dt><dt><span class="sect1"><a href="#TheoryOfOperation">2. Theory of Operation</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d0e99">2.1. SOCKS Loopback and Intermediate System</a></span></dt><dt><span class="sect2"><a href="#d0e121">2.2. NORM Protocol Usage</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Usage">3. Usage</a></span></dt><dd><dl><dt><span class="sect2"><a href="#d0e459">3.1. SOCKS Client Configuration</a></span></dt><dt><span class="sect2"><a href="#ExampleUsage">3.2. Usage Examples</a></span></dt></dl></dd><dt><span class="sect1"><a href="#Commands">4. The "NORP" UDP Signaling Message Format</a></span></dt><dt><span class="sect1"><a href="#d0e585">5. Future Plans</a></span></dt></dl></div><div class="sect1" title="1. Overview"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e37"></a>1. Overview</h2></div></div></div><p>The <span class="emphasis"><em>norp</em></span> application ....</p></div><div class="sect1" title="2. Theory of Operation"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="TheoryOfOperation"></a>2. Theory of Operation</h2></div></div></div><p>The <span class="emphasis"><em>norp</em></span> program acts as a SOCKS proxy server. It supports the SOCKS5 "CONNECT", "BIND" and "UDP-ASSOCIATE" proxy methods for conventional SOCKS proxy operation. The current <span class="emphasis"><em>norp</em></span> implementation does not require (or support) any client authentication. Future versions may provide authentication or other access control mechanisms. The current <span class="emphasis"><em>norp</em></span> implementation only provides NORM transport for the SOCKS TCP "CONNECT" requests. SOCKS "UDP-ASSOCIATE" over NORM will be supported in a future version.</p><p>Unlike a conventional SOCKS server, it is expected that the <span class="emphasis"><em>norp</em></span> daemon can be installed and run as a local "loopback" server that is co-resident on the host running applications that wish to take advantage of NORM transport benefits. The <span class="emphasis"><em>norp</em></span> daemon implements its own signaling protocol that will automatically determine, upon TCP (or UDP) connection establishment, if a remote destination is also similarly "<span class="emphasis"><em>norp</em></span>-enabled" and establish a NORM transport connection as the proxy connection. Otherwise a "business-as-usual" TCP (or UDP) connection is established on the application's behalf and thus compatibility with "non-<span class="emphasis"><em>norp</em></span>" hosts is also supported. <a class="xref" href="#norpConcept" title="Figure 1. NORP Concept of Operation">Figure 1, “NORP Concept of Operation”</a> illustrates this high level concept of operation.</p><div class="figure"><a name="norpConcept"></a><p class="title"><b>Figure 1. NORP Concept of Operation</b></p><div class="figure-contents"><div class="mediaobject"><img src="resources/norpConcept.png" width="270" alt="NORP Concept of Operation"></div></div></div><p><br class="figure-break"></p><p><span class="emphasis"><em>TBD - provide some more details on norp signaling for peer detection and NORM session establishment</em></span></p><p>Note that as an alternative to making proxied connections directly to connection destination addresses as illustrated above, a remote <span class="emphasis"><em>norp</em></span> peer "correspondent" can be specified as part of the <code class="literal">forward</code> command or, for SOCKS connections, with the <code class="literal">correspondent</code> command (see command descriptions below). Future versions of <span class="emphasis"><em>norp</em></span> will include more sophisticated "routing" options for different destinations and traffic types.</p><div class="sect2" title="2.1. SOCKS Loopback and Intermediate System"><div class="titlepage"><div><div><h3 class="title"><a name="d0e99"></a>2.1. SOCKS Loopback and Intermediate System</h3></div></div></div><p>As noted above the principal use case for <span class="emphasis"><em>norp</em></span> is to act as a local, "loopback" SOCKS server that can be used in conjunction with a properly configured SOCKS client. In this way, all of the configuration parameters are localized and implicit and no precoordinated configuration with <span class="emphasis"><em>norp</em></span> peers (or non-<span class="emphasis"><em>norp</em></span> hosts) is required other than using a common UDP port number for NORP signaling.</p><p>However, there may be use cases where it may be desirable to deploy <span class="emphasis"><em>norp</em></span> on intermediate systems at the connection originating site (or domain) and/or the destination site(s) (or domain(s)). This is easily supported by the <span class="emphasis"><em>norp</em></span> design and future norp versions will provide configuration options for this type of deployment.</p></div><div class="sect2" title="2.2. NORM Protocol Usage"><div class="titlepage"><div><div><h3 class="title"><a name="d0e121"></a>2.2. NORM Protocol Usage</h3></div></div></div><p><span class="emphasis"><em>TBD - describe how the NORM streaming capability is used in a flow-controlled, positively-acknowledged fashion to provide a reliable TCP proxy function. Also describe the NORM congestion control options here.</em></span></p></div></div><div class="sect1" title="3. Usage"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="Usage"></a>3. Usage</h2></div></div></div><p>Typically, <span class="emphasis"><em>norp</em></span> can be run in its default configuration with no command-line options required. However, a number of options are available via the command-line. This is a summary of <span class="emphasis"><em>norp</em></span> usage:</p><div class="informalexample"><pre class="programlisting">norp [interface <ifaceName>][address <publicAddr>][sport <socksPort>][port <norpPort>]
|
|
[norm {on|off}][id <normId>][nport <normPort>][cce | ccl | rate <bits/sec>]
|
|
[limit <bits/sec>][persist <seconds>][segment <segmentSize>]
|
|
[correspondent <remoteNorpAddr>][forward <tcpPort>,<destAddr>/<destPort>[,<remoteNorpAddr>]]
|
|
[version][debug <level>][trace][dlog <debugLog>][lport <localNorpPort>][rport <remoteNorpPort>]</pre><p>The <span class="emphasis"><em>norp</em></span> program command-line options include ...</p></div><div class="table"><a name="d0e148"></a><p class="title"><b>Table 1. <span class="emphasis"><em><span class="emphasis"><em>norp</em></span></em></span> Command-line Options</b></p><div class="table-contents"><table summary="norp Command-line Options" border="1"><colgroup><col width="28%" class="Command"><col width="72%" class="Description"></colgroup><tbody><tr><td align="left"><code class="literal">interface <interfaceName></code></td><td>The given <code class="literal"><interfaceName></code> specifies the name (or IP address) of the host network interface <span class="emphasis"><em>norp</em></span> uses as its "public" proxy address. Currently a single interface may be designated for an instance of <span class="emphasis"><em>norp</em></span>. Future version of <span class="emphasis"><em>norp</em></span> may allow for multiple interfaces to be designated depending upon the source and/or destination address of SOCKS proxy connections.</td></tr><tr><td><code class="literal">address <publicAddr></code></td><td>This is similar to the "<code class="literal">interface</code>" command, but allows a specific address to be set. For example, hosts with multiple addresses assigned may wish to use a specific address for proxy functions.</td></tr><tr><td><code class="literal">sport <socksPort></code></td><td>This command is used to specify the port number on which the <span class="emphasis"><em>norp</em></span> server listens for SOCKS client connections. The default port is currently port number 7000.</td></tr><tr><td><code class="literal">port <norpPort></code></td><td>This command is used to specify the UDP port number used for <span class="emphasis"><em>norp</em></span> session setup signaling. The default <span class="emphasis"><em>norp</em></span> UDP signaling port is 7001. The configured <span class="emphasis"><em>norp</em></span> port number (and NORM port number) MUST be unblocked by any network firewalls between <span class="emphasis"><em>norp</em></span> peers. The given port number is used by <span class="emphasis"><em>norp</em></span> to listen for remote connection request and is used as the destination port to signal remote <span class="emphasis"><em>norp</em></span> peers.</td></tr><tr><td><code class="literal">norm {on | off}</code></td><td>By default, <span class="emphasis"><em>norp</em></span> attempts to signal the SOCKS connection endpoint to setup a NORM transport connection to handle reliable data transfer for the TCP connection being instantiated. This command with the "<code class="literal">off</code>" argument will disable this function and <span class="emphasis"><em>norp</em></span> will act as a conventional SOCKS proxy server.</td></tr><tr><td><code class="literal">id <normId></code></td><td>By default, <span class="emphasis"><em>norp</em></span> will attempt to self-configure a NORM protocol node identifier using the IP address of the server host. This command allows a specific NORM node identifier value to be set. It is generally not necessary to explicitly set this value for <span class="emphasis"><em>norp</em></span> unicast proxy connections.</td></tr><tr><td><code class="constant">nport <normPort></code></td><td>This command can be used to specify a UDP port number that will be used for NORM protocol transport connections. The default NORM port number used by <span class="emphasis"><em>norp</em></span> is 7002. The configured NORM port number (and <span class="emphasis"><em>norp</em></span> UDP signaling <code class="literal">port</code> number) MUST be unblocked by any network firewalls between <span class="emphasis"><em>norp</em></span> peers.</td></tr><tr><td><code class="literal">cce</code></td><td>This option enables NORM-CCE congestion control operation that uses Explicit Congestion Notification (ECN) information for NORM protocol end-to-end transmission rate adaption. This is an alternative to the TCP-friendly congestion control mechanism used for NORM by default. Routers in the path of the <span class="emphasis"><em>norp</em></span> peers using the NORM-CCE option MUST be configured for ECN packet marking in response to congestion.</td></tr><tr><td><code class="literal">ccl</code></td><td>This option enables experimental NORM-CCL ("Loss Tolerant") congestion control operation that uses some simple heuristics to try to differentiate packet loss due to congestion versus duo to channel bit errors. This is another alternative to the TCP-friendly congestion control mechanism used for NORM by default. No special intermediate system configuration is required, and while more loss tolerant than the default TCP-friendly behavior, is not as effective as the NORM-CCE mode of operation.</td></tr><tr><td><code class="literal">rate <bits/sec></code></td><td>This option causes <span class="emphasis"><em>norp</em></span> to use a preset and fixed transmission rate for each proxied data flow (e.g. TCP connection). This should only be used when the network connectivity usage is carefully pre-planned and previsioned for the expected (i.e. <span class="emphasis"><em>a priori</em></span> known) flows. At this time, one common transmission rate is used for all flows.</td></tr><tr><td><code class="literal">limit <bits/sec></code></td><td>This option sets a limit for the <span class="emphasis"><em>cumulative</em></span> transmit rate for <span class="emphasis"><em>all</em></span> flows that <span class="emphasis"><em>norp</em></span> is proxying. For automated congestion operation, this can also work to "jump start" the usual "slow start" transport rate control by setting the lower bound of rate adjustment based on the limit <code class="literal"><bits/sec> / <numFlows></code>. For example, a single flow will immediately "jump" to close the full limit rate, while the second of two flows would "jump" to half of the "limit" rate. Also, by setting a limit based on <span class="emphasis"><em>a priori</em></span> connectivity information, this can avoid rate adjustment "overshoot" and help congestion control operate more effectively as compared to a "blind" situation. IMPORTANT: This options should only be applied when the connectivity path is well known and the impact of the lower bound enforcement here will not adversely impact other network traffic flows. A future option may be provided to further reduce or eliminate the lower bound enforcement that would eliminate this concern in less controlled network deployments. A limit value of "-1.0" (default) disables the limit enforcement.</td></tr><tr><td><code class="literal">segment <segmentSize></code></td><td>This option sets the NORM protocol maximum packet payload size where is <em class="parameter"><code><segmentSize></code></em> is in units of bytes. . For <span class="emphasis"><em>norp</em></span> that uses the NORM_OBJECT_STREAM, the maximum NORM UDP payload size is 40 bytes of NORM header plus the configured segment size. The resultant total maximum IPv4 UDP packet size (including IP and UDP headers) is then 28 + 40 + <em class="parameter"><code><segmentSize></code></em> bytes. For IPv6, the resultant maximum packet size is 48 + 40 + <em class="parameter"><code><segmentSize></code></em> bytes. The default NORM segment size, if this option is not invoked, is 1400 bytes, resulting in NORM UDP packets with 1440 byte payloads. Thus, for IPv4 that has 28 bytes of IP + UDP header, this results in a maximum <span class="emphasis"><em>norp</em></span> packet size of 1468 bytes while, for IPv6, the maximum <span class="emphasis"><em>norp</em></span> packet size would be 1488 bytes.</td></tr><tr><td><code class="literal">correspondent <remoteNorpAddr></code></td><td>This option causes <span class="emphasis"><em>norp</em></span> to "route" connections through a <span class="emphasis"><em>norp</em></span> peer at the specified <em class="parameter"><code><remoteNorpAddr></code></em>. This is an alternative to the default behavior where <span class="emphasis"><em>norp</em></span> attempts to connect directly to the connection destination addresses.</td></tr><tr><td><code class="literal">persist <seconds></code></td><td>This option controls how persistently norp attempts to deliver data to the remote endpoint when the remote endpoint fails to acknowledge reception. A persist value of -1 makes norp infinitely persistent and the corresponding norp session remains in place until all data is delivered. If not, an orphaned session will remain in place if the remote endpoint is permanently disconnected. The default persist value is 120 seconds (2 minutes).</td></tr><tr><td><code class="literal">forward <tcpPort>,<dstAddr>/<dstPort>[,<norpAddr>]</code></td><td>This command sets up a "preset" TCP proxy (non-SOCKS) port forwarding session by listening on the specified TCP <em class="parameter"><code><tcpPort></code></em> for connections and then connecting to the given remote <em class="parameter"><code><dstAddr>/<dstPort></code></em>. Optionally, a separate remote <em class="parameter"><code><norpAddr></code></em> may be given. Otherwise, a <span class="emphasis"><em>norp</em></span> proxy connection is attempted to the given <em class="parameter"><code><dstAddr></code></em> platform on the <span class="emphasis"><em>norp</em></span> <em class="parameter"><code><port></code></em> (or <em class="parameter"><code><rport></code></em> if specified). Note that multiple such "preset" proxy sessions may be specified on the command-line and each "preset" proxy session can handle multiple connections as needed.</td></tr><tr><td><code class="literal">debug <debugLevel></code></td><td><table width="100%" border="0"><colgroup><col width="100%"></colgroup><tbody><tr><td>This command can be used to control the verbosity of <span class="emphasis"><em>norp</em></span> debug logging output. Generally, the range of the value is 0-12. A higher value results in more verbose, detailed debug output.</td></tr></tbody></table></td></tr><tr><td><code class="literal">trace</code></td><td>This command enables NORM send and receive packet trace logging.</td></tr><tr><td><code class="literal">dlog <fileName></code></td><td><table width="100%" border="0"><colgroup><col width="100%"></colgroup><tbody><tr><td>This command can be used to direct <span class="emphasis"><em>norp</em></span> debug logging output to a given file. The default <span class="emphasis"><em>norp</em></span> debug logging is to STDERR.</td></tr></tbody></table></td></tr><tr><td><code class="literal">lport <localNorpPort></code></td><td>This command can enable single host, loopback testing by a having <span class="emphasis"><em>norp</em></span> listen on a different port number than which it uses as the destination port for remote <span class="emphasis"><em>norp</em></span> peer signaling. E.g., two <span class="emphasis"><em>norp</em></span> instances on a single machine can be set up with unique <code class="literal"><localNorpPort></code> values and then use the "<code class="literal">rport</code>" command to specify each other's destination <span class="emphasis"><em>norp</em></span> port numbers.</td></tr><tr><td><code class="literal">rport <remoteNorpPort></code></td><td>This command is intended to be used in conjunction with the "<code class="literal">lport</code>" command to allow separate specification of the destination port number used for remote <span class="emphasis"><em>norp</em></span> peer signaling.</td></tr></tbody></table></div></div><br class="table-break"><div class="sect2" title="3.1. SOCKS Client Configuration"><div class="titlepage"><div><div><h3 class="title"><a name="d0e459"></a>3.1. SOCKS Client Configuration</h3></div></div></div><p><span class="emphasis"><em>TBD - provide overview and examples (for specific SOCKS clients of note such as Dante, Proxifier, etc) of SOCKS client configuration</em></span></p></div><div class="sect2" title="3.2. Usage Examples"><div class="titlepage"><div><div><h3 class="title"><a name="ExampleUsage"></a>3.2. Usage Examples</h3></div></div></div><p>The SOCKS client(s) must be configured to use the <span class="emphasis"><em>norp</em></span> server unless a preset TCP port <code class="literal">forward</code> is specified. For example the Dante proxy distribution (available from <a class="ulink" href="http://www.inet.no/dante/" target="_top">http://www.inet.no/dante/</a>) has a <span class="emphasis"><em>socksify</em></span> command that is installed and can be used to launch existing network applications so their socket communications are directed through the configured server. With Dante, a SOCKS configuration file (typically <code class="filename">/etc/socks.conf</code>) or the <code class="constant">SOCKS5_SERVER</code> environment variable can be used to set the server address and port number.</p><p>The <span class="emphasis"><em>norp</em></span> "server" is a lightweight module and can be installed on the same end systems requiring the performance benefits of NORM transport. In this case the SOCKS client server configuration is the loopback address and <span class="emphasis"><em>norp</em></span> SOCKS port number (i.e. <code class="literal">127.0.0.1:7000</code>). The locally installed norp SOCKS server will signal remote network destinations (e.g., upon TCP connection initiation) to determine if the destination is <span class="emphasis"><em>norp</em></span>-capable. If possible, it will establish a NORM-connection to the remote <span class="emphasis"><em>norp</em></span> correspondent that connects to the final destination. Otherwise a direct TCP connection (or UDP relay) will be made to the remote destination.</p></div></div><div class="sect1" title="4. The "NORP" UDP Signaling Message Format"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="Commands"></a>4. The "NORP" UDP Signaling Message Format</h2></div></div></div><p>The <span class="emphasis"><em>norp</em></span> proxy uses UDP signaling to confirm presence of a remote <span class="emphasis"><em>norp</em></span> peer and to set up (and tear down) NORM transport protocol sessions to support the proxied TCP (and eventually UDP) transport connections. The norp instance originating a SOCKS session request is referred to here as the "originator" and the remote norp peer to which the request is directed is referred to as the "correspondent". The <span class="emphasis"><em>norp</em></span> "originator" is the server associated with the SOCKS client making a request while the "correspondent" establishes connections with the remote SOCKS destination.</p><p>The following UDP payload format is used for NORP signaling:</p><pre class="programlisting">0 1 2 3
|
|
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
|
| msgType | reserved | sessionId |
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
|
| normNodeId |
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
|
| normSrcPort | normDstPort |
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
|
| timestamp_sec |
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
|
| timestamp_usec |
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
|
| content ...
|
|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
|
|
|
</pre><p>The NORP message types include:</p><div class="variablelist"><dl><dt><span class="term">SOCKS_REQ</span></dt><dd><p>The message content contains a SOCKS5 Request message from the "originator" to the "correspondent" <span class="emphasis"><em>norp</em></span> server.</p></dd><dt><span class="term">ACK_REQ</span></dt><dd><p>The message is used to acknowledge receipt of a SOCKS_REQ message. There is no "content"</p></dd><dt><span class="term">SOCKS_REP</span></dt><dd><p>The message content contains a SOCKS5 Reply message from the "correspondent" <span class="emphasis"><em>norp</em></span> server.</p></dd><dt><span class="term">ACK_REP</span></dt><dd><p>The message is used to acknowledge receipt of a SOCKS_REP message. There is no "content".</p></dd><dt><span class="term">ORIG_END</span></dt><dd><p>This message indicates the "originator" <span class="emphasis"><em>norp</em></span> server is terminating the given session. There is no "content".</p></dd><dt><span class="term">CORR_END</span></dt><dd><p>This message indicates the "correspondent" <span class="emphasis"><em>norp</em></span> server is terminating the given session. There is no "content".</p></dd><dt><span class="term">ACK_END</span></dt><dd><p>This message is used to acknowledge receipt of either an ORIG_END or CORR_END message. There is no "content".</p></dd></dl></div><p><span class="emphasis"><em>TBD - describe NORP signaling and the message format given here.</em></span></p></div><div class="sect1" title="5. Future Plans"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e585"></a>5. Future Plans</h2></div></div></div><p>There are a number of additional features and refinements planned for the <span class="emphasis"><em>norp</em></span> implementation. Some of these include:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Source / destination configuration and "routing" options</p></li><li class="listitem"><p>Data compression options</p></li><li class="listitem"><p>Security features</p></li></ol></div></div></div></body></html> |