kytv/I2P_Website
1
0
Fork 0
forked from I2P_Developers/i2p.www
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Moved i2pcontrol and *streaming pages into docs/api

Browse Source
This commit is contained in:
str4d
2012-11-10 21:53:08 +00:00
parent 51648c7d38
commit 46d0d5c7d9
3 changed files with 11 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

206
i2p2www/pages/site/docs/api/i2pcontrol.html Normal file
View File

@@ -0,0 +1,206 @@
{% extends "global/layout.html" %}
{% block title %}I2PControl API{% endblock %}
{% block content %}
<h1>I2PControl - Remote Control Service</h1>
<p>I2P enables a <a href="http://en.wikipedia.org/wiki/JSON-RPC">JSONRPC2</a> interface via the plugin I2PControl.
The aim of the interface is to provide simple way to interface with a running I2P node. A client, itoopie, has been developed in parallel.
The JSONRPC2 implementation for the client as well as the plugin is provided by the java libraries <a href="http://software.dzhuvinov.com/json-rpc-2.0.html">JSON-RPC 2.0</a>.
A list of implementations of JSON-RPC for various languages can be found at <a href="http://json-rpc.org/wiki/implementations">the JSON-RPC wiki</a>.
</p>
<p>I2PControl is by default listening on localhost:7650</p>
<h2>API, version 1.</h2>
<p>
Parameters are only provided in a named way (maps).
<h4>JSON-RPC 2 format</h4>
<div class="box" style="clear: none;"><pre>
Request:
{"id":"id", "method":"Method-name","params":{"Param-key-1":"param-value-1", "Param-key-2":"param-value-2", "Token":"**actual token**"}, "jsonrpc":"2.0"}
Response:
{"id":"id","result":{"Result-key-1":"result-value-1","Result-key-2":"result-value-2"},"jsonrpc":"2.0"}
</pre></div>
</p>
<ul>method-name &ndash; Description
<ul>Request
<li>Param-key-1 &ndash; Description</li>
<li>Param-key-2 &ndash; Description</li>
<li>Token &ndash; Token used for authenticating every request (excluding the 'Authenticate' RPC method)</li>
</ul>
<ul>Response
<li>Result-key-1 &ndash; Description</li>
<li>Result-key-2 &ndash; Description</li>
</ul>
</ul>
<h4>Implemented methods</h4>
<ul>Authenticate &ndash; Creates and returns an authentication token used for further communication.
<ul>Request
<li>API &ndash; [long] The version of the I2PControl API used by the client.</li>
<li>Password &ndash; [String] The password used for authenticating against the remote server.</li>
</ul>
<ul>Response
<li>API &ndash; [long] The primare I2PControl API version implemented by the server.</li>
<li>Token &ndash; [String] The token used for further communication.</li>
</ul>
</ul>
<ul>Echo &ndash; Echoes the value of the echo key, used for debugging and testing.
<ul>Request
<li>Echo &ndash; [String] Value will be returned in response.</li>
<li>Token &ndash; [String]Token used for authenticating the client. Is provided by the server via the 'Authenticate' RPC method.</li>
</ul>
<ul>Response
<li>Result &ndash; [String] Value of the key 'echo' in the request.</li>
</ul>
</ul>
<ul>GetRate &ndash; Fetches rateStat from router statManager. Creates stat if not already created.
<ul>Request
<li>Stat &ndash; [String] Determines which rateStat to fetch, see <a href="ratestats.html">ratestats</a>.</li>
<li>Period &ndash; [long] Determines which period a stat is fetched for. Measured in ms.</li>
<li>Token &ndash; [String] Token used for authenticating the client. Is provided by the server via the 'Authenticate' RPC method.</li>
</ul>
<ul>Response
<li>Result &ndash; [double] Returns the average value for the reuested rateStat and period.</li>
</ul>
</ul>
<ul>I2PControl &ndash; Manages I2PControl. Ports, passwords and the like.
<ul>Request
<li>*i2pcontrol.address &ndash; [String] Sets a new listen address for I2PControl (only 127.0.0.1 and 0.0.0.0 are implemented in I2PControl currently).</li>
<li>*i2pcontrol.password &ndash; [String] Sets a new password for I2PControl, all Authentication tokens will be revoked.</li>
<li>*i2pcontrol.port &ndash; [String] Switches which port I2PControl will listen for connections on.</li>
<li>Token &ndash; [String] Token used for authenticating the client. Is provided by the server via the 'Authenticate' RPC method.</li>
</ul>
<ul>Response
<li>**i2pcontrol.address &ndash; [null] Returned if address was changed</li>
<li>**i2pcontrol.password &ndash; [null] Returned if setting was changed</li>
<li>**i2pcontrol.port &ndash; [null] Returned if setting was changed</li>
<li>SettingsSaved &ndash; [Boolean] Returns true if any changes were made.</li>
<li>RestartNeeded &ndash; [Boolean] Returns true if any changes requiring a restart to take effect were made.</li>
</ul>
</ul>
<ul>RouterInfo &ndash; Fetches basic information about hte I2P router. Uptime, version etc.
<ul>Request
<li>*i2p.router.status &ndash; [n/a]</li>
<li>*i2p.router.uptime &ndash; [n/a]</li>
<li>*i2p.router.version &ndash; [n/a]</li>
<li>*i2p.router.net.bw.inbound.1s &ndash; [n/a] </li>
<li>*i2p.router.net.bw.inbound.15s &ndash; [n/a] </li>
<li>*i2p.router.net.bw.outbound.1s &ndash; [n/a] </li>
<li>*i2p.router.net.bw.outbound.15s &ndash; [n/a] </li>
<li>*i2p.router.net.status &ndash; [n/a]</li>
<li>*i2p.router.net.tunnels.participating &ndash; [n/a] </li>
<li>*i2p.router.netdb.activepeers &ndash; [n/a] </li>
<li>*i2p.router.netdb.fastpeers &ndash; [n/a] </li>
<li>*i2p.router.netdb.highcapacitypeers &ndash; [n/a] </li>
<li>*i2p.router.netdb.isreseeding &ndash; [n/a] </li>
<li>*i2p.router.netdb.knownpeers &ndash; [n/a] </li>
<li>Token &ndash; [String] Token used for authenticating the client. Is provided by the server via the 'Authenticate' RPC method.</li>
</ul>
<ul>Response
<li>**i2p.router.status &ndash; [String] What the status of the router is.</li>
<li>**i2p.router.uptime &ndash; [long] What the uptime of the router is in ms.</li>
<li>**i2p.router.version &ndash; [String] What version of I2P the router is running.</li>
<li>**i2p.router.net.bw.inbound.1s &ndash; [double] The 1 second average inbound bandwidth in Bps.</li>
<li>**i2p.router.net.bw.inbound.15s &ndash; [double] The 15 second average inbound bandwidth in Bps.</li>
<li>**i2p.router.net.bw.outbound.1s &ndash; [double] The 1 second average outbound bandwidth in Bps.</li>
<li>**i2p.router.net.bw.outbound.15s &ndash; [double] The 15 second average outbound bandwidth in Bps.</li>
<li>**i2p.router.net.status &ndash; [long] What the current network status is. According to the below enum:
<ul>
<li>0 &ndash; OK</li>
<li>1 &ndash; TESTING</li>
<li>2 &ndash; FIREWALLED</li>
<li>3 &ndash; HIDDEN</li>
<li>4 &ndash; WARN_FIREWALLED_AND_FAST</li>
<li>5 &ndash; WARN_FIREWALLED_AND_FLOODFILL</li>
<li>6 &ndash; WARN_FIREWALLED_WITH_INBOUND_TCP</li>
<li>7 &ndash; WARN_FIREWALLED_WITH_UDP_DISABLED</li>
<li>8 &ndash; ERROR_I2CP</li>
<li>9 &ndash; ERROR_CLOCK_SKEW</li>
<li>10 &ndash; ERROR_PRIVATE_TCP_ADDRESS</li>
<li>11 &ndash; ERROR_SYMMETRIC_NAT</li>
<li>12 &ndash; ERROR_UDP_PORT_IN_USE</li>
<li>13 &ndash; ERROR_NO_ACTIVE_PEERS_CHECK_CONNECTION_AND_FIREWALL</li>
<li>14 &ndash; ERROR_UDP_DISABLED_AND_TCP_UNSET</li>
</ul>
</li>
<li>**i2p.router.net.tunnels.participating &ndash; [long] How many tunnels on the I2P net are we participating in.</li>
<li>**i2p.router.netdb.activepeers &ndash; [long] How many peers have we communicated with recently.</li>
<li>**i2p.router.netdb.fastpeers &ndasg; [long] How many peers are considered 'fast'.</li>
<li>**i2p.router.netdb.highcapacitypeers &ndash; [long] How many peers are considered 'high capacity'.</li>
<li>**i2p.router.netdb.isreseeding &ndash; [boolean] Is the router reseeding hosts to its NetDB?</li>
<li>**i2p.router.netdb.knownpeers &ndash; [long] How many peers are known to us (listed in our NetDB).</li>
</ul>
</ul>
<ul>RouterManager &ndash; Manages I2P router restart/shutdown.
<ul>Request
<li>*Reseed &ndash; [n/a] Initiates a router reseed, fetching peers into our NetDB from a remote host.</li>
<li>*Restart &ndash; [n/a] Restarts the router.</li>
<li>*RestartGraceful &ndash; [n/a] Restarts the router gracefully (waits for participating tunnels to expire).</li>
<li>*Shutdown &ndash; [n/a] Shuts down the router.</li>
<li>*ShutdownGraceful &ndash; [n/a] Shuts down the router gracefully (waits for participating tunnels to expire).</li>
<li>Token &ndash; [String] Token used for authenticating the client. Is provided by the server via the 'Authenticate' RPC method.</li>
</ul>
<ul>Response
<li>**Reseed &ndash; [null] If requested, verifies that a reseed has been initiated.</li>
<li>**Restart &ndash; [null] If requested, verifies that a restart has been initiated.</li>
<li>**RestartGraceful &ndash; [null] If requested, verifies that a graceful restart has been initiated.</li>
<li>**Shutdown &ndash; [null] If requested, verifies that a shutdown has been initiated</li>
<li>**ShutdownGraceful &ndash; [null] If requested, verifies that a graceful shutdown has been initiated</li>
</ul>
</ul>
<ul>NetworkSetting &ndash; Fetches or sets various network related settings. Ports, addresses etc.
<ul>Request
<li>*i2p.router.net.ntcp.port &ndash; [String] What port is used for the TCP transport. If null is submitted, current setting will be returned.</li>
<li>*i2p.router.net.ntcp.hostname &ndash; [String] What hostname is used for the TCP transport. If null is submitted, current setting will be returned.</li>
<li>*i2p.router.net.ntcp.autoip &ndash; [String] Use automatically detected ip for TCP transport. If null is submitted, current setting will be returned.</li>
<li>*i2p.router.net.ssu.port &ndash; [String] What port is used for the UDP transport. If null is submitted, current setting will be returned.</li>
<li>*i2p.router.net.ssu.hostname &ndash; [String] What hostname is used for the UDP transport. If null is submitted, current setting will be returned.</li>
<li>*i2p.router.net.ssu.autoip &ndash; [String] Which methods should be used for detecting the ip address of the UDP transport. If null is submitted, current setting will be returned.</li>
<li>*i2p.router.net.ssu.detectedip &ndash; [null] What ip has been detected by the UDP transport.</li>
<li>*i2p.router.net.upnp &ndash; [String] Is UPNP enabled. If null is submitted, current setting will be returned.</li>
<li>*i2p.router.net.bw.share &ndash; [String] How many percent of bandwidth is usable for participating tunnels. If null is submitted, current setting will be returned.</li>
<li>*i2p.router.net.bw.in &ndash; [String] How many KB/s of inbound bandwidth is allowed. If null is submitted, current setting will be returned.</li>
<li>*i2p.router.net.bw.out &ndash; [String] How many KB/s of outbound bandwidth is allowed. If null is submitted, current setting will be returned.</li>
<li>*i2p.router.net.laptopmode &ndash; [String] Is laptop mode enabled (change router identity and UDP port when IP changes ). If null is submitted, current setting will be returned.</li>
<li>Token &ndash; [String] Token used for authenticating the client. Is provided by the server via the 'Authenticate' RPC method. If null is submitted, current setting will be returned.</li>
</ul>
<ul>Response
<li>**i2p.router.net.ntcp.port &ndash; [String] If requested, returns the port used for the TCP transport.</li>
<li>**i2p.router.net.ntcp.hostname &ndash; [String] If requested, returns the hostname used for the TCP transport.</li>
<li>**i2p.router.net.ntcp.autoip &ndash; [String] If requested, returns the method used for automatically detecting ip for the TCP transport.</li>
<li>**i2p.router.net.ssu.port &ndash; [String] If requested, returns the port used for the UDP transport.</li>
<li>**i2p.router.net.ssu.hostname &ndash; [String] If requested, returns the hostname used for the UDP transport.</li>
<li>**i2p.router.net.ssu.autoip &ndash; [String] If requested, returns methods used for detecting the ip address of the UDP transport.</li>
<li>**i2p.router.net.ssu.detectedip &ndash; [String] If requested, returns what ip has been detected by the UDP transport.</li>
<li>**i2p.router.net.upnp &ndash; [String] If requested, returns the UPNP setting.</li>
<li>**i2p.router.net.bw.share &ndash; [String] If requested, returns how many percent of bandwidth is usable for participating tunnels.</li>
<li>**i2p.router.net.bw.in &ndash; [String] If requested, returns how many KB/s of inbound bandwidth is allowed.</li>
<li>**i2p.router.net.bw.out &ndash; [String] If requested, returns how many KB/s of outbound bandwidth is allowed.</li>
<li>**i2p.router.net.laptopmode &ndash; [String] If requested, returns the laptop mode.</li>
<li>SettingsSaved &ndash; [boolean] Have the provided settings been saved.</li>
<li>RestartNeeded &ndash; [boolean] Is a restart needed for the new settings to be used.</li>
</ul>
</ul>
<p>* denotes an optional value.</p>
<p>** denotes a possibly occuring return value</p>
<h3>Error codes</h3>
<ul>Standard JSON-RPC2 error codes.
<li>-32700 &ndash; JSON parse error.</li>
<li>-32600 &ndash; Invalid request.</li>
<li>-32601 &ndash; Method not found.</li>
<li>-32603 &ndash; Internal error.</li>
</ul>
<ul>I2PControl specific error codes.
<li>-32001 &ndash; Invalid password provided.</li>
<li>-32002 &ndash; No authentication token presented.</li>
<li>-32003 &ndash; Authentication token doesn't exist.</li>
<li>-32004 &ndash; The provided authentication token was expired and will be removed.</li>
<li>-32005 &ndash; The version of the I2PControl API used wasn't specified, but is required to be specified.</li>
<li>-32006 &ndash; The version of the I2PControl API specified is not supported by I2PControl.</li>
</ul>
{% endblock %}

47
i2p2www/pages/site/docs/api/ministreaming.html Normal file
View File

@@ -0,0 +1,47 @@
{% extends "global/layout.html" %}
{% block title %}Ministreaming Library{% endblock %}
{% block content %}
<h2>Note</h2>
The ministreaming library has been enhanced and extended by the
"full" <a href="{{ site_url('docs/api/streaming') }}">streaming library</a>.
Ministreaming is deprecated and is incompatible with today's applications.
The following documentation is old.
Also note that streaming extends ministreaming in the same Java package (net.i2p.client.streaming),
so the current
<a href="http://docs.i2p-projekt.de/javadoc/net/i2p/client/streaming/package-summary.html">API documentation</a>
contains both.
Obsolete ministreaming classes and methods are clearly marked as deprecated in the Javadocs.
<h2>Ministreaming Library</h2>
<p>The ministreaming library is a layer on top of the core
<a href="i2cp">I2CP</a> that allows reliable, in order, and authenticated streams
of messages to operate across an unreliable, unordered, and unauthenticated
message layer. Just like the TCP to IP relationship, this streaming
functionality has a whole series of tradeoffs and optimizations available, but
rather than embed that functionality into the base I2P code, it has been factored
off into its own library both to keep the TCP-esque complexities separate and to
allow alternative optimized implementations.</p>
<p>The ministreaming library was written by mihi as a part of his
<a href="{{ site_url('docs/api/i2ptunnel') }}">I2PTunnel</a> application and then factored out and released
under the BSD license. It is called the "mini"streaming library because it makes
some simplifications in the implementation, while a more robust streaming library
could be further optimized for operation over I2P. The two main issues with
the ministreaming library are its use of the traditional TCP two phase
establishment protocol and the current fixed window size of 1. The establishment
issue is minor for long lived streams, but for short ones, such as quick HTTP
requests, the impact can be <a href="minwww">significant</a>. As for the window
size, the ministreaming library doesn't maintain any ID or ordering within the
messages sent (or include any application level ACK or SACK), so it must wait
on average twice the time it takes to send a message before sending another.</p>
<p>Even with those issues, the ministreaming library performs quite well in many
situations, and its <a href="http://docs.i2p-projekt.de/javadoc/net/i2p/client/streaming/package-summary.html">API</a>
is both quite simple and capable of remaining unchanged as different streaming
implementations are introduced. The library is deployed in its own
ministreaming.jar.
Developers in Java who would like to use it can
access the API directly, while developers in other languages can use it through
<a href="{{ site_url('docs/api/samv3') }}">SAM</a>'s streaming support.</p>{% endblock %}

501
i2p2www/pages/site/docs/api/streaming.html Normal file
View File

@@ -0,0 +1,501 @@
{% extends "global/layout.html" %}
{% block title %}Streaming Library{% endblock %}
{% block content %}
Updated November 2012, current as of router version 0.9.3
<h2>Overview</h2>
<p>
The streaming library is technically part of the "application" layer,
as it is not a core router function.
In practice, however, it provides a vital function for almost all
existing I2P applications, by providing a TCP-like
streams over I2P, and allowing existing apps to be easily ported to I2P.
The other end-to-end transport library for client communication is the
<a href="datagrams.html">datagram library</a>.
</p>
<p>The streaming library is a layer on top of the core
<a href="i2cp.html">I2CP API</a> that allows reliable, in-order, and authenticated streams
of messages to operate across an unreliable, unordered, and unauthenticated
message layer. Just like the TCP to IP relationship, this streaming
functionality has a whole series of tradeoffs and optimizations available, but
rather than embed that functionality into the base I2P code, it has been factored
off into its own library both to keep the TCP-esque complexities separate and to
allow alternative optimized implementations.</p>
<p>
In consideration of the relatively high cost of messages,
the streaming library's protocol for scheduling and delivering those messages has been optimized to
allow individual messages passed to contain as much information as is available.
For instance, a small HTTP transaction proxied through the streaming library can
be completed in a single round trip - the first messages bundle a SYN, FIN, and
the small HTTP request payload, and the reply bundles the SYN,
FIN, ACK, and the HTTP response payload. While an additional
ACK must be transmitted to tell the HTTP server that the SYN/FIN/ACK has been
received, the local HTTP proxy can often deliver the full response to the browser
immediately.
</p>
<p>
The streaming library bears much resemblance to an
abstraction of TCP, with its sliding windows, congestion control algorithms
(both slow start and congestion avoidance), and general packet behavior (ACK,
SYN, FIN, RST, rto calculation, etc).
</p>
<p>
The streaming library is
a robust library
which is optimized for operation over I2P.
It has a one-phase setup, and
it contains a full windowing implementation.
</p>
<h2 id="api">API</h2>
<p>
The streaming library API provides a standard socket paradigm to Java applications.
The lower-level
<a href="i2cp.html">I2CP</a>
API is completely hidden, except that applications may pass
<a href="i2cp.html#options">I2CP parameters</a> through the streaming library,
to be interpreted by I2CP.
</p>
<p>
The standard interface to the streaming lib is for the application to use the
<a href="http://docs.i2p-projekt.de/javadoc/net/i2p/client/streaming/I2PSocketManagerFactory.html">I2PSocketManagerFactory</a>
to create an
<a href="http://docs.i2p-projekt.de/javadoc/net/i2p/client/streaming/I2PSocketManager.html">I2PSocketManager</a>.
The application then asks the socket manager for an
<a href="http://docs.i2p-projekt.de/javadoc/net/i2p/client/streaming/I2PSession.html">I2PSession</a>,
which will cause a connection to the router via
<a href="i2cp.html">I2CP</a>.
The application can then setup connections with an
<a href="http://docs.i2p-projekt.de/javadoc/net/i2p/client/streaming/I2PSocket.html">I2PSocket</a>
or receive connections with an
<a href="http://docs.i2p-projekt.de/javadoc/net/i2p/client/streaming/I2PServerSocket.html">I2PServerSocket</a>.
</p>
<p>
Here are the
<a href="http://docs.i2p-projekt.de/javadoc/net/i2p/client/streaming/package-summary.html">full streaming library Javadocs</a>.
</p>
<p>
For a good example of usage, see the i2psnark code.
</p>
<h3 id="options">Options and Defaults</h3>
<p>
The options and current default values are listed below.
Options are case-sensitive and may be set for the whole router, for a particular client, or for an individual socket on a
per-connection basis.
Many values are tuned for HTTP performance over typical I2P conditions. Other applications such
as peer-to-peer services are strongly encouraged to
modify as necessary, by setting the options and passing them via the call to
<a href="http://docs.i2p-projekt.de/javadoc/net/i2p/client/streaming/I2PSocketManagerFactory.html">I2PSocketManagerFactory</a>.createManager(_i2cpHost, _i2cpPort, opts).
Time values are in ms.
</p>
<p>
Note that higher-layer APIs, such as
<a href="{{ site_url('docs/api/samv3') }}">SAM</a>,
<a href="{{ site_url('docs/api/bob') }}">BOB</a>, and
<a href="{{ site_url('docs/api/i2ptunnel') }}">I2PTunnel</a>,
may override these defaults with their own defaults.
Also note that many options only apply to servers listening for incoming connections.
</p><p>
As of release 0.9.1, most, but not all, options may be changed on an active socket manager or session.
See the javadocs for details.
</p>
<table>
<tr><th>Option</th><th>Default</th><th>Notes</th>
</tr>
<tr><td>i2cp.accessList</td><td>null</td><td>Comma- or space-separated list of Base64 peer Hashes used for either access list or blacklist
As of release 0.7.13.
</td></tr><tr><td>i2cp.enableAccessList</td><td>false
</td><td>Use the access list as a whitelist for incoming connections
As of release 0.7.13.
</td></tr><tr><td>i2cp.enableBlackList</td><td>false
</td><td>Use the access list as a blacklist for incoming connections
As of release 0.7.13.
</td></tr><tr><td>i2p.streaming.answerPings</td><td>true</td><td>Whether to respond to incoming pings
</td></tr><tr><td>i2p.streaming.blacklist</td><td>null</td><td>Comma- or space-separated list of Base64 peer Hashes to be
blacklisted for incoming connections to ALL destinations in the context.
This option must be set in the context properties, NOT in the createManager() options argument.
Note that setting this in the router context will not affect clients outside the
router in a separate JVM and context.
As of release 0.9.3.
</td></tr><tr><td>i2p.streaming.bufferSize</td><td>64K</td><td>
How much transmit data (in bytes) will be accepted that hasn't been written out yet.
</td></tr><tr><td>i2p.streaming.congestionAvoidanceGrowthRateFactor</td><td>1
</td><td>
When we're in congestion avoidance, we grow the window size at the rate
of 1/(windowSize*factor). In standard TCP, window sizes are in bytes,
while in I2P, window sizes are in messages.
A higher number means slower growth.
</td></tr><tr><td>i2p.streaming.connectDelay</td><td>-1
</td><td>
How long to wait after instantiating a new con
before actually attempting to connect. If this is
&lt;= 0, connect immediately with no initial data. If greater than 0, wait
until the output stream is flushed, the buffer fills,
or that many milliseconds pass, and include any initial data with the SYN.
</td></tr><tr><td>i2p.streaming.connectTimeout</td><td>5*60*1000</td><td>
How long to block on connect, in milliseconds. Negative means indefinitely. Default is 5 minutes.
</td></tr><tr><td>i2p.streaming.disableRejectLogging</td><td>false</td><td>
Whether to disable warnings in the logs when an incoming connection is rejected due to connection limits.
As of release 0.9.4.
</td></tr><tr><td>i2p.streaming.enforceProtocol</td><td>false</td><td>Whether to listen only for the streaming protocol.
Setting to true will prohibit communication with Destinations earlier than release 0.7.1
(released March 2009). Set to true if running multiple protocols on this Destination.
As of release 0.9.1.
</td></tr><tr><td>i2p.streaming.inactivityAction</td><td>2 (send) </td><td>(0=noop, 1=disconnect)
What to do on an inactivity timeout - do nothing, disconnect, or send a duplicate ack.
</td></tr><tr><td>i2p.streaming.inactivityTimeout</td><td>90*1000
</td></tr><tr><td>i2p.streaming.initialAckDelay</td><td>2000
</td></tr><tr><td>i2p.streaming.initialResendDelay</td><td>1000
</td><td>
The initial value of the resend delay field in the packet header, times 1000.
Not fully implemented; see below.
</td></tr><tr><td>i2p.streaming.initialRTT</td><td>8000 </td><td>(if no <a href="#sharing">sharing data</a> available)
</td></tr><tr><td>i2p.streaming.initialWindowSize</td><td>6</td><td>(if no <a href="#sharing">sharing data</a> available)
In standard TCP, window sizes are in bytes, while in I2P, window sizes are in messages.
</td></tr><tr><td>i2p.streaming.maxConcurrentStreams</td><td>-1 </td><td>(0 or negative value means unlimited)
This is a total limit for incoming and outgoing combined.
</td></tr><tr><td>i2p.streaming.maxConnsPerMinute</td><td>0 </td><td>Incoming connection limit (per peer; 0 means disabled)
As of release 0.7.14.
</td></tr><tr><td>i2p.streaming.maxConnsPerHour</td><td>0 </td><td>(per peer; 0 means disabled)
As of release 0.7.14.
</td></tr><tr><td>i2p.streaming.maxConnsPerDay</td><td>0 </td><td>(per peer; 0 means disabled)
As of release 0.7.14.
</td></tr><tr><td>i2p.streaming.maxMessageSize</td><td>1730</td><td>The MTU in bytes.
</td></tr><tr><td>i2p.streaming.maxResends</td><td>8
</td><td>
Maximum number of retransmissions before failure.
</td></tr><tr><td>i2p.streaming.maxTotalConnsPerMinute</td><td>0 </td><td>Incoming connection limit (all peers; 0 means disabled)
As of release 0.7.14.
</td></tr><tr><td>i2p.streaming.maxTotalConnsPerHour</td><td>0 </td><td>(all peers; 0 means disabled)
Use with caution as exceeding this will disable a server for a long time.
As of release 0.7.14.
</td></tr><tr><td>i2p.streaming.maxTotalConnsPerDay</td><td>0 </td><td>(all peers; 0 means disabled)
Use with caution as exceeding this will disable a server for a long time.
As of release 0.7.14.
</td></tr><tr><td>i2p.streaming.maxWindowSize</td><td>128
</td></tr><tr><td>i2p.streaming.profile</td><td>1 (bulk)</td><td>(2=interactive not supported)
This doesn't currently do anything, but setting it to a value other than 1 will cause an error.
</td></tr><tr><td>i2p.streaming.readTimeout</td><td>-1
</td><td>
How long to block on read, in milliseconds. Negative means indefinitely.
</td></tr><tr><td>i2p.streaming.slowStartGrowthRateFactor</td><td>1
</td><td>
When we're in slow start, we grow the window size at the rate
of 1/(factor). In standard TCP, window sizes are in bytes,
while in I2P, window sizes are in messages.
A higher number means slower growth.
</td></tr><tr><td>i2p.streaming.writeTimeout</td><td>-1
</td><td>
How long to block on write/flush, in milliseconds. Negative means indefinitely.
</td></tr>
</table>
<h2>Protocol Specification</h2>
<h3>Packet Format</h3>
<p>
The format of a single packet in the streaming protocol is:
<pre>
+----+----+----+----+----+----+----+----+
| send Stream ID | rcv Stream ID |
+----+----+----+----+----+----+----+----+
| sequence Num | ack Through |
+----+----+----+----+----+----+----+----+
| nc | NACKs ...
+----+----+----+----+----+----+----+----+
| rd | flags | opt size| opt data
+----+----+----+----+----+----+----+----+
... |
+----+----+----+----+----+----+----+----+
| payload ...
+----+----+----+----//
</pre>
<table>
<tr><th>Field<th>Length<th>Contents
<tr><td>sendStreamId <td>4 byte <a href="common_structures_spec.html#type_Integer">Integer</a><td>Random number selected by the connection recipient
and constant for the life of the connection.
0 in the SYN message sent by the originator, and in subsequent messages, until a SYN reply is received,
containing the peer's stream ID.
<tr><td>receiveStreamId <td>4 byte <a href="common_structures_spec.html#type_Integer">Integer</a><td>Random number selected by the connection originator
and constant for the life of the connection. May be 0 if unknown, for example in a RESET packet.
<tr><td>sequenceNum <td>4 byte <a href="common_structures_spec.html#type_Integer">Integer</a><td>
The sequence for this message, starting at 0 in the SYN message,
and incremented by 1 in each message except for plain ACKs and retransmissions.
If the sequenceNum is 0 and the SYN flag is not set, this is a plain ACK
packet that should not be ACKed.
<tr><td>ackThrough <td>4 byte <a href="common_structures_spec.html#type_Integer">Integer</a><td>
The highest packet sequence number that was received
on the receiveStreamId. This field is ignored on the initial
connection packet (where receiveStreamId is the unknown id) or
if the NO_ACK flag set.
All packets up to and including this sequence number are ACKed,
EXCEPT for those listed in NACKs below.
<tr><td>NACK count<td>1 byte <a href="common_structures_spec.html#type_Integer">Integer</a><td>
The number of 4-byte NACKs in the next field
<tr><td>NACKs <td>n * 4 byte <a href="common_structures_spec.html#type_Integer">Integers</a><td>
Sequence numbers less than ackThrough that are not yet received.
Two NACKs of a packet is a request for a 'fast retransmit' of that packet.
<tr><td>resendDelay<td>1 byte <a href="common_structures_spec.html#type_Integer">Integer</a><td>
How long is the creator of this packet going to wait before
resending this packet (if it hasn't yet been ACKed). The
value is seconds since the packet was created.
Currently ignored on receive.
<tr><td>flags <td>2 byte value<td>
See below.
<tr><td>option size<td>2 byte <a href="common_structures_spec.html#type_Integer">Integer</a><td>
The number of bytes in the next field
<tr><td>option data<td>0 or more bytes<td>
As specified by the flags. See below.
<tr><td>payload <td>remaining packet size<td>
</table>
<h3>Flags and Option Data Fields</h3>
<p>The flags field above specifies some metadata about the packet, and in
turn may require certain additional data to be included. The flags are
as follows. Any data structures specified must be added to the options area
in the given order.</p>
<p>
Bit order: 15....0 (15 is MSB)
</p>
<table>
<tr><th>Bit<th>Flag<th>Option Data<th>Function
<tr><td>0<td>SYNCHRONIZE<td align="center">--<td>
Similar to TCP SYN. Set in the initial packet and in the first response.
FROM_INCLUDED and SIGNATURE_INCLUDED must be set also.
<tr><td>1<td>CLOSE<td align="center">--<td>
Similar to TCP FIN. If the response to a SYNCHRONIZE fits in a single message, the response
will contain both SYNCHRONIZE and CLOSE.
SIGNATURE_INCLUDED must be set also.
<tr><td>2<td>RESET<td align="center">--<td>
Abnormal close.
SIGNATURE_INCLUDED must be set also.
<tr><td>3<td>SIGNATURE_INCLUDED<td>40 byte <a href="common_structures_spec.html#type_Signature">DSA Signature</a>
<td>
Currently sent only with SYNCHRONIZE, CLOSE, and RESET, where it is required.
The signature uses the Destination's <a href="common_structures_spec.html#type_SigningPublicKey">DSA signing keys</a>
to sign the entire header and payload with the 40-byte space in the option data field
for the signature being set to all zeroes.
<tr><td>4<td>SIGNATURE_REQUESTED<td align="center">--<td>
Unused. Requests every packet in the other direction to have SIGNATURE_INCLUDED
<tr><td>5<td>FROM_INCLUDED<td>387+ byte <a href="common_structures_spec.html#struct_Destination">Destination</a>
<td>
Currently sent only with SYNCHRONIZE, where it is required.
<tr><td>6<td>DELAY_REQUESTED<td>2 byte <a href="common_structures_spec.html#type_Integer">Integer</a><td>
Optional delay.
How many milliseconds the sender of this packet wants the recipient
to wait before sending any more data.
A value greater than 60000 indicates choking.
<tr><td>7<td>MAX_PACKET_SIZE_INCLUDED<td>2 byte <a href="common_structures_spec.html#type_Integer">Integer</a><td>
Currently sent with SYNCHRONIZE only.
Was also sent in retransmitted packets until release 0.9.1.
<tr><td>8<td>PROFILE_INTERACTIVE<td align="center">--<td>
Unused or ignored; the interactive profile is unimplemented.
<tr><td>9<td>ECHO<td align="center">--<td>
Unused except by ping programs
<tr><td>10<td>NO_ACK<td align="center">--<td>
This flag simply tells the recipient to ignore the ackThrough field in the header.
Currently unused, the ackThrough field is always valid.
<tr><td>11-15<td>unused<td><td>
</table>
<h2>Implementation Details</h2>
<h3>Setup</h3>
<p>
The initiator sends a packet with the SYNCHRONIZE flag set. This packet may contain the initial data as well.
The peer replies with a packet with the SYNCHRONIZE flag set. This packet may contain the initial response data as well.
</p>
<p>
The initiator may send additional data packets, up to the initial window size, before receiving the SYNCHRONIZE response.
These packets will also have the send Stream ID field set to 0.
Recipients must buffer packets received on unknown streams for a short period of time, as they may
arrive out of order, in advance of the SYNCHRONIZE packet.
</p>
<h3>MTU Selection and Negotiation</h3>
<p>
The maximum message size (also called the MTU / MRU) is negotiated to the lower value supported by
the two peers. As tunnel messages are padded to 1KB, a poor MTU selection will lead to
a large amount of overhead.
The MTU is specified by the option i2p.streaming.maxMessageSize.
The current default MTU of 1730 was chosen to fit precisely into two 1K I2NP tunnel messages,
including overhead for the typical case.
</p>
<p>
The first message in a connection includes a 387 byte (typical) Destination added by the streaming layer,
and usually a 898 byte (typical) LeaseSet, and Session keys, bundled in the Garlic message by the router.
(The LeaseSet and Session Keys will not be bundled if an ElGamal Session was previously established).
Therefore, the goal of fitting a complete HTTP request in a single 1KB I2NP message is not always attainable.
However, the selection of the MTU, together with careful implementation of fragmentation
and batching strategies in the tunnel gateway processor, are important factors in network bandwidth,
latency, reliability, and efficiency, especially for long-lived connections.
</p>
<h3>Data Integrity</h3>
Data integrity is assured by the gzip CRC-32 checksum implemented in
<a href="i2cp.html#format">the I2CP layer</a>.
There is no checksum field in the streaming protocol.
<h3>Packet Encapsulation</h3>
Each packet is sent through I2P as a single message (or as an individual clove in a
<a href="{{ site_url('docs/how/garlicrouting') }}">Garlic Message</a>).
Message encapsulation is implemented in the underlying
<a href="i2cp.html">I2CP</a>,
<a href="i2np.html">I2NP</a>, and
<a href="tunnel_message_spec.html">tunnel message</a> layers.
There is no packet delimiter mechanism or payload length field in the streaming protocol.
<h3>Windowing</h3>
<p>
The streaming lib uses standard slow-start (exponential window growth) and congestion avoidance (linear window growth)
phases, with exponential backoff.
Windowing and acknowledgments use packet count, not byte count.
</p>
<h3>Close</h3>
<p>
Any packet, including one with the SYNCHRONIZE flag set, may have the CLOSE flag sent as well.
The connection is not closed until the peer responds with the CLOSE flag.
CLOSE packets may contain data as well.
</p>
<h3 id="sharing">Control Block Sharing</h3>
<p>
The streaming lib supports "TCP" Control Block sharing.
This shares two important streaming lib parameters
(window size and round trip time)
across connections to the same remote peer.
This is used for "temporal" sharing at connection open/close time,
not "ensemble" sharing during a connection (See
<a href="http://www.ietf.org/rfc/rfc2140.txt">RFC 2140</a>).
There is a separate share per ConnectionManager (i.e. per local Destination)
so that there is no information leakage to other Destinations on the
same router.
The share data for a given peer expires after a few minutes.
</p>
<h3 id="other">Other Parameters</h3>
The following parameters are hardcoded, but may be of interest for analysis:
<ul>
<li>MIN_RESEND_DELAY = 2*1000 (minimum RTO)
<li>MAX_RESEND_DELAY = 45*1000 (maximum RTO)
<li>MIN_WINDOW_SIZE = 1
<li>TREND_COUNT = 3
<li>RTT_DAMPENING = 0.875
<li>MIN_MESSAGE_SIZE = 512 (minimum MTU)
<li>INBOUND_BUFFER_SIZE = maxMessageSize * (maxWindowSize + 2)
<li>INITIAL_TIMEOUT = 1.5 * initialRTT
<li>PASSIVE_FLUSH_DELAY = 250
<li>Maximum RTT estimate: 60*1000
</ul>
</p>
<h3>History</h3>
<p>
The streaming library has grown organically for I2P - first mihi implemented the
"mini streaming library" as part of I2PTunnel, which was limited to a window
size of 1 message (requiring an ACK before sending the next one), and then it was
refactored out into a generic streaming interface (mirroring TCP sockets) and the
full streaming implementation was deployed with a sliding window protocol and
optimizations to take into account the high bandwidth x delay product. Individual
streams may adjust the maximum packet size and other options. The default
message size is selected to fit precisely in two 1K I2NP tunnel messages,
and is a reasonable tradeoff between the bandwidth costs of
retransmitting lost messages, and the latency and overhead of multiple messages.
</p>
<h2 id="future">Future Work</h2>
The behavior of the streaming library has a profound impact on
application-level performance, and as such, is an important
area for further analysis.
<ul>
<li>
Additional tuning of the streaming lib parameters may be necessary.
</li>
<li>
Another area for research is the interaction of the streaming lib with the
NTCP and SSU transport layers.
See <a href="{{ site_url('docs/transport/ntcp/discussion') }}">the NTCP discussion page</a> for details.
</li>
<li>
The interaction of the routing algorithms with the streaming lib strongly affects performance.
In particular, random distribution of messages to multiple tunnels in a pool
leads to a high degree of out-of-order delivery which results in smaller window
sizes than would otherwise be the case. The router currently routes
messages for a single from/to destination pair through a consistent set
of tunnels, until tunnel expiration or delivery failure. The router's
failure and tunnel selection algorithms should be reviewed for possible
improvements.
</li>
<li>
The data in the first SYN packet may exceed the receiver's MTU.
</li>
<li>
The DELAY_REQUESTED field could be used more.
</li>
<li>
Duplicate initial SYNCHRONIZE packets on short-lived streams may not be recognized and removed.
</li>
<li>
Don't send the MTU in a retransmission.
</li>
<li>
Data is sent along unless the outbound window is full.
(i.e. no-Nagle or TCP_NODELAY)
Probably should have a configuration option for this.
</li>
<li>
zzz has added debug code to the streaming library to log packets in a wireshark-compatible
(pcap) format; Use this to further analyze performance.
The format may require enhancement to map more streaming lib parameters to TCP fields.
</li>
<li>
There are proposals to replace the streaming lib with standard TCP
(or perhaps a null layer together with raw sockets).
This would unfortunately be incompatible with the streaming lib
but it would be good to compare the performance of the two.
</li>
</ul>
{% endblock %}