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

Added translation tags to docs/api/* except SAM pages

Browse Source
This commit is contained in:
str4d
2013-01-30 20:23:24 +00:00
parent 611a8f05dc
commit 32c8fc9268
6 changed files with 680 additions and 470 deletions
Download Patch File Download Diff File Expand all files Collapse all files

144
i2p2www/pages/site/docs/api/bob.html
View File

@@ -1,48 +1,77 @@
{% extends "global/layout.html" %} {% extends "global/layout.html" %}
{% block title %}BOB{% endblock %} {% block title %}BOB{% endblock %}
{% block lastupdated %}{% trans %}August 2010{% endtrans %}{% endblock %}
{% block content %} {% block content %}
<pre> <h1>{% trans %}BOB - Basic Open Bridge{% endtrans %}</h1>
Technical differences from SAM (for the better?)
<h2>{% trans %}Technical differences from SAM (for the better?){% endtrans %}</h2>
<p>{% trans -%}
BOB has separate command and data channels. BOB has separate command and data channels.
One, an application command channel socket to router to configure. One, an application command channel socket to router to configure.
Two, the application data sockets to/from router that carry only data. Two, the application data sockets to/from router that carry only data.
The command channel is only needed for making or setting the initial The command channel is only needed for making or setting the initial
destination key, and to set the destination key to port bindings. destination key, and to set the destination key to port bindings.
All connections run in parallel. All connections run in parallel.
{%- endtrans %}</p>
SAM One connection that does everything, and you need to parse every packet. <p>{% trans -%}
SAM has one connection that does everything, and you need to parse every packet.
{%- endtrans %}</p>
<p>{% trans -%}
BOB does not hold keypair values, nor does the router. BOB does not hold keypair values, nor does the router.
Your application holds the keypair values. Your application holds the keypair values.
This is to reduce any extra complexity in the router code, it also adds to This is to reduce any extra complexity in the router code, it also adds to
your privacy. your privacy.
{%- endtrans %}</p>
<p>{% trans -%}
SAM router stores every keypair you ever make. SAM router stores every keypair you ever make.
{%- endtrans %}</p>
<p>{% trans -%}
Those are the important differences. Those are the important differences.
{%- endtrans %}</p>
KEYS = keypair public+private, these are BASE64 <p>{% trans -%}
KEY = public key, also BASE64 <code>KEYS</code> = keypair public+private, these are BASE64
{%- endtrans %}</p>
<p>{% trans -%}
<code>KEY</code> = public key, also BASE64
{%- endtrans %}</p>
<p>{% trans -%}
<code>ERROR</code> as is implied returns the message <code>"ERROR "+DESCRIPTION+"\n"</code>, where the <code>DESCRIPTION</code> is what went wrong.
{%- endtrans %}</p>
<p>{% trans -%}
<code>OK</code> returns <code>"OK"</code>, and if data is to be returned, it is on the same line. <code>OK</code> means the command is finished.
{%- endtrans %}</p>
<p>{% trans -%}
<code>DATA</code> lines contain information that you requested. There may be multiple <code>DATA</code> lines per request.
{%- endtrans %}</p>
ERROR as is implied returns the message "ERROR "+DESCRIPTION+"\n", where the DESCRIPTION is what went wrong. <p>{% trans -%}
OK returns "OK", and if data is to be returned, it is on the same line. OK means the command is finished. <b>NOTE:</b> The help command is the ONLY command that has an exception to
DATA lines contain information that you requested. There may be multiple DATA lines per request.
NOTE: The help command is the ONLY command that has an exception to
the rules... it can actually return nothing! This is intentional, since the rules... it can actually return nothing! This is intentional, since
help is a HUMAN and not an APPLICATION command. help is a HUMAN and not an APPLICATION command.
{%- endtrans %}</p>
PLEASE NOTE: <p>{% trans -%}
<b>PLEASE NOTE:</b>
For CURRENT details on the commands PLEASE use the built-in help command. For CURRENT details on the commands PLEASE use the built-in help command.
Just telnet to localhost 2827 and type help and you can get full documentation on each command. Just telnet to localhost 2827 and type help and you can get full documentation on each command.
{%- endtrans %}</p>
<p>{% trans -%}
Commands never get obsoleted or changed, however new commands do get added from time to time. Commands never get obsoleted or changed, however new commands do get added from time to time.
{%- endtrans %}</p>
Here are the commands we have as of this writing (Aug 2010). <p>{% trans -%}
Here are the commands we have as of this writing:
{%- endtrans %}</p>
COMMAND OPERAND RETURNS <pre>
{{ _('COMMAND') }} {{ _('OPERAND') }} {{ _('RETURNS') }}
help (optional command to get help on) NOTHING or OK and description of the command help (optional command to get help on) NOTHING or OK and description of the command
clear ERROR or OK clear ERROR or OK
getdest ERROR or OK and KEY getdest ERROR or OK and KEY
@@ -67,12 +96,16 @@ stop ERROR or OK
verify KEY ERROR or OK verify KEY ERROR or OK
visit OK, and dumps BOB's threads to the wrapper.log visit OK, and dumps BOB's threads to the wrapper.log
zap nothing, quits BOB zap nothing, quits BOB
</pre>
<p>{% trans -%}
Once set up, all TCP sockets can and will block as needed, and there is no need for any Once set up, all TCP sockets can and will block as needed, and there is no need for any
additional messages to/from the command channel. This allows the router to pace the additional messages to/from the command channel. This allows the router to pace the
stream without exploding with OOM like SAM does as it chokes on attempting to shove stream without exploding with OOM like SAM does as it chokes on attempting to shove
many streams in or out one socket -- that can't scale when you have alot of connections! many streams in or out one socket -- that can't scale when you have alot of connections!
{%- endtrans %}</p>
<p>{% trans -%}
What is also nice about this particular interface is that writing anything to interface What is also nice about this particular interface is that writing anything to interface
to it, is much much easier than SAM. There is no other processing to do after the set up. to it, is much much easier than SAM. There is no other processing to do after the set up.
It's configuration is so simple, that very simple tools, such as nc (netcat) can be used It's configuration is so simple, that very simple tools, such as nc (netcat) can be used
@@ -82,39 +115,53 @@ to stop that application. Instead, you can literally "unplug" the destination, a
"plug it in" again. As long as the same IP/port addresses and destination keys are used "plug it in" again. As long as the same IP/port addresses and destination keys are used
when bringing the bridge up, the normal TCP application won't care, and won't notice. when bringing the bridge up, the normal TCP application won't care, and won't notice.
It will simply be fooled -- the destinations are not reachable, and that nothing is coming in. It will simply be fooled -- the destinations are not reachable, and that nothing is coming in.
{%- endtrans %}</p>
<p>{% trans -%}
For the following example, we'll setup a very simple local loopback connection, For the following example, we'll setup a very simple local loopback connection,
with two destinations. Destination "mouth" will be the CHARGEN service from with two destinations. Destination "mouth" will be the CHARGEN service from
the INET superserver daemon. Destination "ear" will be a local port that you the INET superserver daemon. Destination "ear" will be a local port that you
can telnet into, and watch the pretty ASCII test puke forth. can telnet into, and watch the pretty ASCII test puke forth.
{%- endtrans %}</p>
EXAMPLE SESSION DIALOGUE -- simple telnet 127.0.0.1 2827 works <pre>
A = Application {% trans %}EXAMPLE SESSION DIALOGUE -- simple telnet 127.0.0.1 2827 works{% endtrans %}
C = BOB's Command response. A = {{ _('Application') }}
C = {% trans %}BOB's Command response.{% endtrans %}
FROM TO DIALOGUE {{ _('FROM') }} {{ _('TO') }} {{ _('DIALOGUE') }}
A C setnick mouth A C setnick mouth
C A OK Nickname set to mouth C A OK Nickname set to mouth
A C newkeys A C newkeys
C A OK ZMPz1zinTdy3~zGD~f3g9aikZTipujEvvXOEyYfq4Su-mNKerqG710hFbkR6P-xkouVyNQsqWLI8c6ngnkSwGdUfM7hGccqBYDjIubTrlr~0g2-l0vM7Y8nSqtFrSdMw~pyufXZ0Ys3NqUSb8NuZXpiH2lCCkFG21QPRVfKBGwvvyDVU~hPVfBHuR8vkd5x0teMXGGmiTzdB96DuNRWayM0y8vkP-1KJiPFxKjOXULjuXhLmINIOYn39bQprq~dAtNALoBgd-waZedYgFLvwHDCc9Gui8Cpp41EihlYGNW0cu0vhNFUN79N4DEpO7AtJyrSu5ZjFTAGjLw~lOvhyO2NwQ4RiC4UCKSuM70Fz0BFKTJquIjUNkQ8pBPBYvJRRlRG9HjAcSqAMckC3pvKKlcTJJBAE8GqexV7rdCCIsnasJXle-6DoWrDkY1s1KNbEVH6i1iUEtmFr2IHTpPeFCyWfZ581CAFNRbbUs-MmnZu1tXAYF7I2-oXTH2hXoxCGAAAA C A OK ZMPz1zinTdy3~zGD~f3g9aikZTipujEvvXOEyYfq4Su-mNKerqG710hFbkR6P-xkouVyNQsqWLI8c6ngnkSwGdUfM7hGccqBYDjIubTrlr~0g2-l0vM7Y8nSqtFrSdMw~pyufXZ0Ys3NqUSb8NuZXpiH2lCCkFG21QPRVfKBGwvvyDVU~hPVfBHuR8vkd5x0teMXGGmiTzdB96DuNRWayM0y8vkP-1KJiPFxKjOXULjuXhLmINIOYn39bQprq~dAtNALoBgd-waZedYgFLvwHDCc9Gui8Cpp41EihlYGNW0cu0vhNFUN79N4DEpO7AtJyrSu5ZjFTAGjLw~lOvhyO2NwQ4RiC4UCKSuM70Fz0BFKTJquIjUNkQ8pBPBYvJRRlRG9HjAcSqAMckC3pvKKlcTJJBAE8GqexV7rdCCIsnasJXle-6DoWrDkY1s1KNbEVH6i1iUEtmFr2IHTpPeFCyWfZ581CAFNRbbUs-MmnZu1tXAYF7I2-oXTH2hXoxCGAAAA
</pre>
<p><b>{% trans -%}
MAKE NOTE OF THE ABOVE DESTINATION KEY, YOURS WILL BE DIFFERENT! MAKE NOTE OF THE ABOVE DESTINATION KEY, YOURS WILL BE DIFFERENT!
{%- endtrans %}</b></p>
FROM TO DIALOGUE <pre>
{{ _('FROM') }} {{ _('TO') }} {{ _('DIALOGUE') }}
A C outhost 127.0.0.1 A C outhost 127.0.0.1
C A OK outhost set C A OK outhost set
A C outport 19 A C outport 19
C A OK outbound port set C A OK outbound port set
A C start A C start
C A OK tunnel starting C A OK tunnel starting
</pre>
<p>{% trans -%}
At this point, there was no error, a destination with a nickname of "mouth" At this point, there was no error, a destination with a nickname of "mouth"
is set up. When you contact the destination provided, you actually connect is set up. When you contact the destination provided, you actually connect
to the CHARGEN service on 19/TCP. to the <code>CHARGEN</code> service on <code>19/TCP</code>.
{%- endtrans %}</p>
<p>{% trans -%}
Now for the other half, so that we can actually contact this destination. Now for the other half, so that we can actually contact this destination.
{%- endtrans %}</p>
FROM TO DIALOGUE <pre>
{{ _('FROM') }} {{ _('TO') }} {{ _('DIALOGUE') }}
A C setnick ear A C setnick ear
C A OK Nickname set to ear C A OK Nickname set to ear
A C newkeys A C newkeys
@@ -127,14 +174,20 @@ A C start
C A OK tunnel starting C A OK tunnel starting
A C quit A C quit
C A OK Bye! C A OK Bye!
</pre>
<p>{% trans -%}
Now all we need to do is telnet into 127.0.0.1, port 37337, Now all we need to do is telnet into 127.0.0.1, port 37337,
send the destination key or host address from addressbook we want to contact. send the destination key or host address from addressbook we want to contact.
In this case, we want to contact "mouth", all we do is paste in the In this case, we want to contact "mouth", all we do is paste in the
key and it goes. key and it goes.
{%- endtrans %}</p>
NOTE: The "quit" command in the command channel does NOT disconnect the tunnels like SAM. <p>{% trans -%}
<b>NOTE:</b> The "quit" command in the command channel does NOT disconnect the tunnels like SAM.
{%- endtrans %}</p>
<pre>
# telnet 127.0.0.1 37337 # telnet 127.0.0.1 37337
Trying 127.0.0.1... Trying 127.0.0.1...
Connected to 127.0.0.1. Connected to 127.0.0.1.
@@ -146,20 +199,32 @@ ZMPz1zinTdy3~zGD~f3g9aikZTipujEvvXOEyYfq4Su-mNKerqG710hFbkR6P-xkouVyNQsqWLI8c6ng
#$%&amp;'()*+,-./0123456789:;&lt;=&gt;?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghij #$%&amp;'()*+,-./0123456789:;&lt;=&gt;?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghij
$%&amp;'()*+,-./0123456789:;&lt;=&gt;?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijk $%&amp;'()*+,-./0123456789:;&lt;=&gt;?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijk
... ...
After a few virtual miles of this spew, press Control-] </pre>
<p>{% trans -%}
After a few virtual miles of this spew, press <code>Control-]</code>
{%- endtrans %}</p>
<pre>
... ...
cdefghijklmnopqrstuvwxyz{|}~ !"#$%&amp;'()*+,-./0123456789:;&lt;=&gt;?@ABCDEFGHIJK cdefghijklmnopqrstuvwxyz{|}~ !"#$%&amp;'()*+,-./0123456789:;&lt;=&gt;?@ABCDEFGHIJK
defghijklmnopqrstuvwxyz{|}~ !"#$%&amp;'()*+,-./0123456789:;&lt;=&gt;?@ABCDEFGHIJKL defghijklmnopqrstuvwxyz{|}~ !"#$%&amp;'()*+,-./0123456789:;&lt;=&gt;?@ABCDEFGHIJKL
efghijklmnopqrstuvwxyz{|}~ !"#$%&amp;'()*+,-./0123456789:;&lt;= efghijklmnopqrstuvwxyz{|}~ !"#$%&amp;'()*+,-./0123456789:;&lt;=
telnet&gt; c telnet&gt; c
Connection closed. Connection closed.
</pre>
<p>{% trans -%}
Here is what happened... Here is what happened...
{%- endtrans %}</p>
<pre>
telnet -&gt; ear -&gt; i2p -&gt; mouth -&gt; chargen -. telnet -&gt; ear -&gt; i2p -&gt; mouth -&gt; chargen -.
telnet &lt;- ear &lt;- i2p &lt;- mouth &lt;-----------' telnet &lt;- ear &lt;- i2p &lt;- mouth &lt;-----------'
</pre>
<p>{% trans -%}
You can connect to EEPSITES too! You can connect to EEPSITES too!
{%- endtrans %}</p>
<pre>
# telnet 127.0.0.1 37337 # telnet 127.0.0.1 37337
Trying 127.0.0.1... Trying 127.0.0.1...
Connected to 127.0.0.1. Connected to 127.0.0.1.
@@ -186,36 +251,52 @@ Accept-Ranges: bytes
&lt;/html&gt; &lt;/html&gt;
Connection closed by foreign host. Connection closed by foreign host.
# #
</pre>
<p>{% trans -%}
Pretty cool isn't it? Try some other well known EEPSITES if you like, nonexistent ones, Pretty cool isn't it? Try some other well known EEPSITES if you like, nonexistent ones,
etc, to get a feel for what kind of output to expect in different situations. etc, to get a feel for what kind of output to expect in different situations.
For the most part, it is suggested that you ignore any of the error messages. For the most part, it is suggested that you ignore any of the error messages.
They would be meaningless to the application, and are only presented for human debugging. They would be meaningless to the application, and are only presented for human debugging.
{%- endtrans %}</p>
<p>{% trans -%}
Let's put down our destinations now that we are all done with them. Let's put down our destinations now that we are all done with them.
{%- endtrans %}</p>
<p>{% trans -%}
First, lets see what destination nicknames we have. First, lets see what destination nicknames we have.
{%- endtrans %}</p>
FROM TO DIALOGUE <pre>
{{ _('FROM') }} {{ _('TO') }} {{ _('DIALOGUE') }}
A C list A C list
C A DATA NICKNAME: mouth STARTING: false RUNNING: true STOPPING: false KEYS: true QUIET: false INPORT: not_set INHOST: localhost OUTPORT: 19 OUTHOST: 127.0.0.1 C A DATA NICKNAME: mouth STARTING: false RUNNING: true STOPPING: false KEYS: true QUIET: false INPORT: not_set INHOST: localhost OUTPORT: 19 OUTHOST: 127.0.0.1
C A DATA NICKNAME: ear STARTING: false RUNNING: true STOPPING: false KEYS: true QUIET: false INPORT: 37337 INHOST: 127.0.0.1 OUTPORT: not_set OUTHOST: localhost C A DATA NICKNAME: ear STARTING: false RUNNING: true STOPPING: false KEYS: true QUIET: false INPORT: 37337 INHOST: 127.0.0.1 OUTPORT: not_set OUTHOST: localhost
C A OK Listing done C A OK Listing done
</pre>
<p>{% trans -%}
Alright, there they are. First, let's remove "mouth". Alright, there they are. First, let's remove "mouth".
{%- endtrans %}</p>
FROM TO DIALOGUE <pre>
{{ _('FROM') }} {{ _('TO') }} {{ _('DIALOGUE') }}
A C getnick mouth A C getnick mouth
C A OK Nickname set to mouth C A OK Nickname set to mouth
A C stop A C stop
C A OK tunnel stopping C A OK tunnel stopping
A C clear A C clear
C A OK cleared C A OK cleared
</pre>
<p>{% trans -%}
Now to remove "ear", note that this is what happens when you type too fast, Now to remove "ear", note that this is what happens when you type too fast,
and shows you what typical ERROR messages looks like. and shows you what typical ERROR messages looks like.
{%- endtrans %}</p>
FROM TO DIALOGUE <pre>
{{ _('FROM') }} {{ _('TO') }} {{ _('DIALOGUE') }}
A C getnick ear A C getnick ear
C A OK Nickname set to ear C A OK Nickname set to ear
A C stop A C stop
@@ -226,20 +307,31 @@ A C clear
C A OK cleared C A OK cleared
A C quit A C quit
C A OK Bye! C A OK Bye!
</pre>
<p>{% trans -%}
I won't bother to show an example of the receiver end of a bridge I won't bother to show an example of the receiver end of a bridge
because it is very simple. There are two possible settings for it, and because it is very simple. There are two possible settings for it, and
it is toggled with the "quiet" command. it is toggled with the "quiet" command.
{%- endtrans %}</p>
<p>{% trans -%}
The default is NOT quiet, and the first data to come into your The default is NOT quiet, and the first data to come into your
listening socket is the destination that is making the contact. It is a listening socket is the destination that is making the contact. It is a
single line consisting of the BASE64 address followed by a newline. single line consisting of the BASE64 address followed by a newline.
Everything after that is for the application to actually consume. Everything after that is for the application to actually consume.
{%- endtrans %}</p>
<p>{% trans -%}
In quiet mode, think of it as a regular Internet connection. No In quiet mode, think of it as a regular Internet connection. No
extra data comes in at all. It's just as if you are plain connected to extra data comes in at all. It's just as if you are plain connected to
the regular Internet. This mode allows a form of transparency much like the regular Internet. This mode allows a form of transparency much like
is available on the router console tunnel settings pages, so that you is available on the router console tunnel settings pages, so that you
can use BOB to point a destination at a web server, for example, and can use BOB to point a destination at a web server, for example, and
you would not have to modify the web server at all. you would not have to modify the web server at all.
{%- endtrans %}</p>
<p>{% trans -%}
The advantage with using BOB for this is as discussed The advantage with using BOB for this is as discussed
previously. You could schedule random uptimes for the application, previously. You could schedule random uptimes for the application,
redirect to a different machine, etc. One use of this may be something redirect to a different machine, etc. One use of this may be something
@@ -251,5 +343,5 @@ have to bother shutting it down and restarting it. You could redirect
and point to a different machine on your LAN while you do updates, or and point to a different machine on your LAN while you do updates, or
point to a set of backup machines depending on what is running, etc, point to a set of backup machines depending on what is running, etc,
etc. Only your imagination limits what you could do with BOB. etc. Only your imagination limits what you could do with BOB.
</pre> {%- endtrans %}</p>
{% endblock %} {% endblock %}

261
i2p2www/pages/site/docs/api/i2pcontrol.html
View File

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

123
i2p2www/pages/site/docs/api/i2ptunnel.html
View File

@@ -1,92 +1,100 @@
{% extends "global/layout.html" %} {% extends "global/layout.html" %}
{% block title %}i2ptunnel{% endblock %} {% block title %}i2ptunnel{% endblock %}
{% block content %}Description of i2ptunnel and tunneling modes {% block content %}
<!--Description of i2ptunnel and tunneling modes
default services default services
client modes client modes
serrver modes server modes
-->
<h1>I2PTunnel</h1> <h1>I2PTunnel</h1>
<h2 id="overview">Overview</h2> <h2 id="overview">{% trans %}Overview{% endtrans %}</h2>
<p> <p>{% trans naming=site_url('docs/naming') -%}
I2PTunnel is a tool for interfacing with and providing services on I2P. I2PTunnel is a tool for interfacing with and providing services on I2P.
Destination of an I2PTunnel can be defined using a <a href="naming.html">hostname</a>, Destination of an I2PTunnel can be defined using a <a href="{{ naming }}">hostname</a>,
<a href="naming.html#base32">Base32</a>, or a full 516-byte destination key. <a href="{{ naming }}#base32">Base32</a>, or a full 516-byte destination key.
An established I2PTunnel will be available on your client machine as localhost:port. An established I2PTunnel will be available on your client machine as localhost:port.
If you wish to provide a service on I2P network, you simply create I2PTunnel to the If you wish to provide a service on I2P network, you simply create I2PTunnel to the
appropriate ip_address:port. A corresponding 516-byte destination key will be generated appropriate ip_address:port. A corresponding 516-byte destination key will be generated
for the service and it will become avaliable throughout I2P. for the service and it will become avaliable throughout I2P.
A web interface for I2PTunnel management is avaliable on A web interface for I2PTunnel management is avaliable on
<a href="http://localhost:7657/i2ptunnel/">localhost:7657/i2ptunnel/</a>. <a href="http://localhost:7657/i2ptunnel/">localhost:7657/i2ptunnel/</a>.
</p> {%- endtrans %}</p>
<br> <h2 id="default-services">{% trans %}Default Services{% endtrans %}</h2>
<h2 id="default-services">Default Services</h2> <h3 id="default-server-tunnels">{% trans %}Server tunnels{% endtrans %}</h3>
<h3 id="default-server-tunnels">Server tunnels</h3>
<ul> <ul>
<li><b>I2P Webserver</b> - A tunnel pointed to a Jetty webserver run <li>{% trans -%}
on <a href="http://localhost:7658">localhost:7658</a> for convenient and quick hosting on I2P. <b>I2P Webserver</b> - A tunnel pointed to a Jetty webserver run
<br>The document root is: on <a href="http://localhost:7658">localhost:7658</a> for convenient and quick hosting on I2P.
<br>The document root is:{% endtrans %}
<br><b>Unix</b> - %APPDATA%\I2P\eepsite\docroot <br><b>Unix</b> - %APPDATA%\I2P\eepsite\docroot
<br><b>Windows</b> - C:\Users\**username**\AppData\Roaming\I2P\eepsite\docroot <br><b>Windows</b> - C:\Users\**username**\AppData\Roaming\I2P\eepsite\docroot
</li> </li>
</ul> </ul>
<h3 id="default-client-tunnels">Client tunnels</h3> <h3 id="default-client-tunnels">{% trans %}Client tunnels{% endtrans %}</h3>
<ul> <ul>
<li><b>I2P HTTP Proxy</b> - <i>localhost:4444</i></a> - A HTTP proxy used for browsing I2P and the regular internet anonymously through I2P. <li><b>I2P HTTP Proxy</b> - <i>localhost:4444</i></a> - {% trans -%}
A HTTP proxy used for browsing I2P and the regular internet anonymously through I2P.
Browsing internet through I2P uses a random proxy specified by the "Outproxies:" option. Browsing internet through I2P uses a random proxy specified by the "Outproxies:" option.
</li> {%- endtrans %}</li>
<li><b>IRC Proxy</b> - <i>localhost:6668</i> - A IRC proxy to the default anonymous IRC-servers.</li> <li><b>Irc2P</b> - <i>localhost:6668</i> - {% trans %}An IRC tunnel to the default anonymous IRC network, Irc2P.{% endtrans %}</li>
<li><b>mtn.i2p2.i2p</b> - <i>localhost:8998</i> - The anonymous <a href="http://en.wikipedia.org/wiki/Monotone_%28software%29">monotone</a> <li><b>mtn.i2p2.i2p</b> - <i>localhost:8998</i> - {% trans -%}
sourcecode repository for I2P The anonymous <a href="http://en.wikipedia.org/wiki/Monotone_%28software%29">monotone</a>
</li> sourcecode repository for I2P
<li><b>smtp.postman.i2p</b> - <i>localhost:7659</i> - A SMTP service provided by postman at {%- endtrans %}</li>
<a href="http://hq.postman.i2p/?page_id=16">hq.postman.i2p</a> <li><b>smtp.postman.i2p</b> - <i>localhost:7659</i> - {% trans postman=i2pconv('hq.postman.i2p') -%}
(<a href="http://hq.postman.i2p.to/?page_id=16">via inproxy</a>) A SMTP service provided by postman at <a href="http://{{ postman }}/?page_id=16">{{ postman }}</a>
</li> {%- endtrans %}</li>
<li><b>pop3.postman.i2p</b> - <i>localhost:7660</i> - The accompanying POP sevice of postman at <li><b>pop3.postman.i2p</b> - <i>localhost:7660</i> - {% trans postman=i2pconv('hq.postman.i2p') -%}
<a href="http://hq.postman.i2p/?page_id=16">hq.postman.i2p</a> The accompanying POP sevice of postman at <a href="http://{{ postman }}/?page_id=16">{{ postman }}</a>
(<a href="http://hq.postman.i2p.to/?page_id=16">via inproxy</a>) {%- endtrans %}</li>
</ul> </ul>
<br> <h2 id="client-modes">{% trans %}Client Modes{% endtrans %}</h2>
<h2 id="client-modes">Client Modes</h2> <h3 id="client-modes-standard">{% trans %}Standard{% endtrans %}</h3>
<h3 id="client-modes-standard">Standard</h3> <p>{% trans -%}
Opens a local TCP port that connects to a service (like HTTP, FTP or SMTP) on a destination inside of I2P. Opens a local TCP port that connects to a service (like HTTP, FTP or SMTP) on a destination inside of I2P.
The tunnel is directed to a random host from the comma seperated (", ") list of destinations. The tunnel is directed to a random host from the comma seperated (", ") list of destinations.
{%- endtrans %}</p>
<br>
<h3 id="client-mode-http">HTTP</h3> <h3 id="client-mode-http">HTTP</h3>
<p>A HTTP-client tunnel. The tunnel connects to the destination specified by the URL <p>{% trans -%}
in a HTTP request. Supports proxying onto internet if an outproxy is provided. Strips HTTP connections of the following headers: A HTTP-client tunnel. The tunnel connects to the destination specified by the URL
</p> in a HTTP request. Supports proxying onto internet if an outproxy is provided. Strips HTTP connections of the following headers:
{%- endtrans %}</p>
<ul> <ul>
<li><b>Accept, Accept-Charset, Accept-Encoding, Accept-Language <li>{% trans -%}
<b>Accept, Accept-Charset, Accept-Encoding, Accept-Language
and Accept-Ranges</b> as they vary greatly between browsers and can be used as an identifier. and Accept-Ranges</b> as they vary greatly between browsers and can be used as an identifier.
</li> {%- endtrans %}</li>
<li><b>Referer:</b></li> <li><b>Referer:</b></li>
<li><b>Via:</b></li> <li><b>Via:</b></li>
<li><b>From:</b></li> <li><b>From:</b></li>
</ul> </ul>
<p> <p>{% trans -%}
HTTP client/server tunnels are via I2Ptunnel force-enabling compression via the following http headers: HTTP client/server tunnels are via I2Ptunnel force-enabling compression via the following http headers:
{%- endtrans %}</p>
<ul> <ul>
<li><b>Accept-Encoding: </b></li> <li><b>Accept-Encoding: </b></li>
<li><b>X-Accept-Encoding: </b> x-i2p-gzip;q=1.0, identity;q=0.5, deflate;q=0, gzip;q=0, *;q=0</li> <li><b>X-Accept-Encoding: </b> x-i2p-gzip;q=1.0, identity;q=0.5, deflate;q=0, gzip;q=0, *;q=0</li>
</ul> </ul>
<p> <p>{% trans -%}
Depending on if the tunnel is using an outproxy or not it will append the following User-Agent: Depending on if the tunnel is using an outproxy or not it will append the following User-Agent:
</p> {%- endtrans %}</p>
<ul> <ul>
<li><i>Outproxy: </i><b>User-Agent:</b> Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.9.2.6) Gecko/20100625 Firefox/3.6.6</li> <li><i>{% trans %}Outproxy:{% endtrans %} </i><b>User-Agent:</b> Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.9.2.6) Gecko/20100625 Firefox/3.6.6</li>
<li><i>Internal I2P use: </i><b>User-Agent:</b> MYOB/6.66 (AN/ON)</li> <li><i>{% trans %}Internal I2P use:{% endtrans %} </i><b>User-Agent:</b> MYOB/6.66 (AN/ON)</li>
</ul> </ul>
</p> </p>
<h3 id="client-mode-irc">IRC</h3> <h3 id="client-mode-irc">IRC</h3>
<p>{% trans -%}
Creates a connection to a random IRC server specified by the comma seprated (", ") Creates a connection to a random IRC server specified by the comma seprated (", ")
list of destinations. Only a whitelisted subset of IRC commands are allowed due to anonymity concerns. list of destinations. Only a whitelisted subset of IRC commands are allowed due to anonymity concerns.
<br>Whitelist: {%- endtrans %}
<br>{% trans %}Whitelist:{% endtrans %}</p>
<ul> <ul>
<li>MODE</li> <li>MODE</li>
<li>JOIN</li> <li>JOIN</li>
@@ -101,41 +109,58 @@ list of destinations. Only a whitelisted subset of IRC commands are allowed due
</ul> </ul>
<h3 id="client-mode-socks">SOCKS 4/4a/5</h3> <h3 id="client-mode-socks">SOCKS 4/4a/5</h3>
<p>{% trans -%}
Enables using the I2P router as a SOCKS proxy. Enables using the I2P router as a SOCKS proxy.
{%- endtrans %}</p>
<h3 id="client-mode-socks-irc">SOCKS IRC</h3> <h3 id="client-mode-socks-irc">SOCKS IRC</h3>
<p>{% trans -%}
Enables using the I2P router as a SOCKS proxy with the command whitelist specified by Enables using the I2P router as a SOCKS proxy with the command whitelist specified by
<a href="#client-mode-irc">IRC</a> client mode. <a href="#client-mode-irc">IRC</a> client mode.
{%- endtrans %}</p>
<h3 id="client-mode-connect">CONNECT</h3> <h3 id="client-mode-connect">CONNECT</h3>
<p>{% trans -%}
Creates a HTTP tunnel and uses the HTTP request method "CONNECT" Creates a HTTP tunnel and uses the HTTP request method "CONNECT"
to build a TCP tunnel that usually is used for SSL and HTTPS. to build a TCP tunnel that usually is used for SSL and HTTPS.
{%- endtrans %}</p>
<h3 id="client-mode-streamr">Streamr</h3> <h3 id="client-mode-streamr">Streamr</h3>
<p>{% trans -%}
Creates a UDP-server attached to a Streamr client I2PTunnel. The streamr client tunnel will Creates a UDP-server attached to a Streamr client I2PTunnel. The streamr client tunnel will
subscribe to a streamr server tunnel. subscribe to a streamr server tunnel.
<br> {%- endtrans %}</p>
<img src="_static/images/I2PTunnel-streamr.png"> <img src="{{ url_for('static', filename='images/I2PTunnel-streamr.png') }}">
<br> <br>
<h2 id="server-modes">Server Modes</h2> <h2 id="server-modes">{% trans %}Server Modes{% endtrans %}</h2>
<h3 id="server-mode-standard">Standard</h3> <h3 id="server-mode-standard">{% trans %}Standard{% endtrans %}</h3>
<p>{% trans -%}
Creates a destination to a local ip:port with an open TCP port. Creates a destination to a local ip:port with an open TCP port.
{%- endtrans %}</p>
<h3 id="server-mode-http">HTTP</h3> <h3 id="server-mode-http">HTTP</h3>
<p>{% trans -%}
Creates a destination to a local HTTP server ip:port. Supports gzip for requests with Creates a destination to a local HTTP server ip:port. Supports gzip for requests with
Accept-encoding: x-i2p-gzip, replies with Content-encoding: x-i2p-gzip in such a request. Accept-encoding: x-i2p-gzip, replies with Content-encoding: x-i2p-gzip in such a request.
{%- endtrans %}</p>
<h3 id="server-mode-http-bidir">HTTP Bidirectional</h3> <h3 id="server-mode-http-bidir">HTTP Bidirectional</h3>
<p>{% trans -%}
Functions as both a I2PTunnel HTTP Server, and a I2PTunnel HTTP client with no outproxying Functions as both a I2PTunnel HTTP Server, and a I2PTunnel HTTP client with no outproxying
capabilities. An example application would be a web application that does client-type capabilities. An example application would be a web application that does client-type
requests, or loopback-testing an eepsite as a diagnostic tool. requests, or loopback-testing an eepsite as a diagnostic tool.
{%- endtrans %}</p>
<h3 id="server-mode-irc">IRC</h3> <h3 id="server-mode-irc">IRC</h3>
<p>{% trans -%}
Creates a destination that filters the reqistration sequence of a client and passes Creates a destination that filters the reqistration sequence of a client and passes
the clients destination key as a hostname to the IRC-server. the clients destination key as a hostname to the IRC-server.
{%- endtrans %}</p>
<h3 id="server-mode-streamr">Streamr</h3> <h3 id="server-mode-streamr">Streamr</h3>
<p>{% trans -%}
A UDP-client that connects to a media server is created. The UDP-Client is coupled with a Streamr server I2PTunnel. A UDP-client that connects to a media server is created. The UDP-Client is coupled with a Streamr server I2PTunnel.
{%- endtrans %}</p>
{% endblock %} {% endblock %}

43
i2p2www/pages/site/docs/api/ministreaming.html
View File

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

71
i2p2www/pages/site/docs/api/socks.html
View File

@@ -1,34 +1,39 @@
{% extends "global/layout.html" %} {% extends "global/layout.html" %}
{% block title %}SOCKS{% endblock %} {% block title %}SOCKS{% endblock %}
{% block content %} {% block content %}
<h2>SOCKS and SOCKS proxies</h2> <h2>{% trans %}SOCKS and SOCKS proxies{% endtrans %}</h2>
<p> <p>{% trans %}
The SOCKS proxy is working as of release 0.7.1. SOCKS 4/4a/5 are supported. The SOCKS proxy is working as of release 0.7.1. SOCKS 4/4a/5 are supported.
Enable SOCKS by creating a SOCKS client tunnel in i2ptunnel. Enable SOCKS by creating a SOCKS client tunnel in i2ptunnel.
Both shared-clients and non-shared are supported. Both shared-clients and non-shared are supported.
There is no SOCKS outproxy so it is of limited use. There is no SOCKS outproxy so it is of limited use.
</p> {%- endtrans %}</p>
<p>
As it says on the <p>{% trans faq=site_url('faq') %}
<a href="{{ site_url('support/faq') }}#socks">FAQ</a>: As it says on the <a href="{{ faq }}#socks">FAQ</a>:
<p> {%- endtrans %}</p>
Many applications leak sensitive <pre>{% trans -%}
information that could identify you on the Internet. I2P only filters Many applications leak sensitive
connection data, but if the program you intend to run sends this information that could identify you on the Internet. I2P only filters
information as content, I2P has no way to protect your anonymity. For connection data, but if the program you intend to run sends this
example, some mail applications will send the IP address of the machine information as content, I2P has no way to protect your anonymity. For
they are running on to a mail server. There is no way for I2P to filter example, some mail applications will send the IP address of the machine
this, thus using I2P to 'socksify' existing applications is possible, but they are running on to a mail server. There is no way for I2P to filter
extremely dangerous. this, thus using I2P to 'socksify' existing applications is possible, but
</p><p> extremely dangerous.
{%- endtrans %}</pre>
<p>{% trans -%}
And quoting from a 2005 email: And quoting from a 2005 email:
</p><p> {%- endtrans %}</p>
<pre>{% trans -%}
... there is a reason why human and ... there is a reason why human and
others have both built and abandoned the SOCKS proxies. Forwarding others have both built and abandoned the SOCKS proxies. Forwarding
arbitrary traffic is just plain unsafe, and it behooves us as arbitrary traffic is just plain unsafe, and it behooves us as
developers of anonymity and security software to have the safety of developers of anonymity and security software to have the safety of
our end users foremost in our minds. our end users foremost in our minds.
{%- endtrans %}</pre>
<p>{% trans -%}
Hoping that we can simply strap an arbitrary client on top of I2P Hoping that we can simply strap an arbitrary client on top of I2P
without auditing both its behavior and its exposed protocols for without auditing both its behavior and its exposed protocols for
security and anonymity is naive. Pretty much *every* application security and anonymity is naive. Pretty much *every* application
@@ -38,33 +43,33 @@ reality. End users are better served with systems designed for
anonymity and security. Modifying existing systems to work in anonymity and security. Modifying existing systems to work in
anonymous environments is no small feat, orders of magnitude more anonymous environments is no small feat, orders of magnitude more
work that simply using the existing I2P APIs. work that simply using the existing I2P APIs.
</p> {%- endtrans %}</p>
<p> <p>{% trans -%}
The SOCKS proxy The SOCKS proxy
supports standard addressbook names, but not Base64 destinations. supports standard addressbook names, but not Base64 destinations.
Base32 hashes should work as of release 0.7. Base32 hashes should work as of release 0.7.
It supports outgoing connections only, i.e. an I2PTunnel Client. It supports outgoing connections only, i.e. an I2PTunnel Client.
UDP support is stubbed out but not working yet. UDP support is stubbed out but not working yet.
Outproxy selection by port number is stubbed out. Outproxy selection by port number is stubbed out.
</p> {%- endtrans %}</p>
<h3>See Also</h3> <h3>{% trans %}See Also{% endtrans %}</h3>
<ul> <ul>
<li> <li>{% trans meeting81=get_url('meetings_show', id=81), meeting82=get_url('meetings_show', id=82) -%}
The notes for The notes for <a href="{{ meeting81 }}">Meeting 81</a> and
<a href="{{ url_for('meetings_show', id=81) }}">Meeting 81</a> <a href="{{ meeting82 }}">Meeting 82</a> in March 2004.
and {%- endtrans %}</li>
<a href="{{ url_for('meetings_show', id=82) }}">Meeting 82</a>
in March 2004.
<li> <li>
<a href="http://www.abenteuerland.at/onioncat/">Onioncat</a> <a href="http://www.abenteuerland.at/onioncat/">Onioncat</a>
<li> <li>
<a href="http://zzz.i2p/">zzz.i2p</a> <a href="http://{{ i2pconv('zzz.i2p') }}/">{{ i2pconv('zzz.i2p') }}</a>
</ul> </ul>
<h3>If You Do Get Something Working</h3> <h3>{% trans %}If You Do Get Something Working{% endtrans %}</h3>
<p>{% trans -%}
Please let us know. And please provide substantial warnings about the Please let us know. And please provide substantial warnings about the
risks of socks proxies. risks of socks proxies.
{%- endtrans %}
{% endblock %} {% endblock %}

506
i2p2www/pages/site/docs/api/streaming.html
View File

@@ -1,30 +1,32 @@
{% extends "global/layout.html" %} {% extends "global/layout.html" %}
{% block title %}Streaming Library{% endblock %} {% block title %}{% trans %}Streaming Library{% endtrans %}{% endblock %}
{% block lastupdated %}November 2012{% endblock %} {% block lastupdated %}{% trans %}November 2012{% endtrans %}{% endblock %}
{% block accuratefor %}0.9.3{% endblock %} {% block accuratefor %}0.9.3{% endblock %}
{% block content %} {% block content %}
<h2>Overview</h2> <h2>{% trans %}Overview{% endtrans %}</h2>
<p> <p>{% trans datagrams=site_url('docs/spec/datagrams') -%}
The streaming library is technically part of the "application" layer, The streaming library is technically part of the "application" layer,
as it is not a core router function. as it is not a core router function.
In practice, however, it provides a vital function for almost all In practice, however, it provides a vital function for almost all
existing I2P applications, by providing a TCP-like existing I2P applications, by providing a TCP-like
streams over I2P, and allowing existing apps to be easily ported to I2P. 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 The other end-to-end transport library for client communication is the
<a href="datagrams.html">datagram library</a>. <a href="{{ datagrams }}">datagram library</a>.
</p> {%- endtrans %}</p>
<p>The streaming library is a layer on top of the core <p>{% trans i2cp=site_url('docs/protocol/i2cp') -%}
<a href="i2cp.html">I2CP API</a> that allows reliable, in-order, and authenticated streams The streaming library is a layer on top of the core
<a href="{{ i2cp }}">I2CP API</a> that allows reliable, in-order, and authenticated streams
of messages to operate across an unreliable, unordered, and unauthenticated of messages to operate across an unreliable, unordered, and unauthenticated
message layer. Just like the TCP to IP relationship, this streaming message layer. Just like the TCP to IP relationship, this streaming
functionality has a whole series of tradeoffs and optimizations available, but 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 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 off into its own library both to keep the TCP-esque complexities separate and to
allow alternative optimized implementations.</p> allow alternative optimized implementations.
{%- endtrans %}</p>
<p> <p>{% trans -%}
In consideration of the relatively high cost of messages, In consideration of the relatively high cost of messages,
the streaming library's protocol for scheduling and delivering those messages has been optimized to 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. allow individual messages passed to contain as much information as is available.
@@ -35,183 +37,255 @@ 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 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 received, the local HTTP proxy can often deliver the full response to the browser
immediately. immediately.
</p> {%- endtrans %}</p>
<p> <p>{% trans -%}
The streaming library bears much resemblance to an The streaming library bears much resemblance to an
abstraction of TCP, with its sliding windows, congestion control algorithms abstraction of TCP, with its sliding windows, congestion control algorithms
(both slow start and congestion avoidance), and general packet behavior (ACK, (both slow start and congestion avoidance), and general packet behavior (ACK,
SYN, FIN, RST, rto calculation, etc). SYN, FIN, RST, rto calculation, etc).
</p> {%- endtrans %}</p>
<p> <p>{% trans -%}
The streaming library is The streaming library is
a robust library a robust library
which is optimized for operation over I2P. which is optimized for operation over I2P.
It has a one-phase setup, and It has a one-phase setup, and
it contains a full windowing implementation. it contains a full windowing implementation.
</p> {%- endtrans %}</p>
<h2 id="api">{% trans %}API{% endtrans %}</h2>
<p>{% trans i2cp=site_url('docs/protocol/i2cp') -%}
<h2 id="api">API</h2>
<p>
The streaming library API provides a standard socket paradigm to Java applications. The streaming library API provides a standard socket paradigm to Java applications.
The lower-level The lower-level <a href="{{ i2cp }}">I2CP</a> API is completely hidden, except that
<a href="i2cp.html">I2CP</a> applications may pass <a href="{{ i2cp }}#options">I2CP parameters</a> through the
API is completely hidden, except that applications may pass streaming library, to be interpreted by I2CP.
<a href="i2cp.html#options">I2CP parameters</a> through the streaming library, {%- endtrans %}</p>
to be interpreted by I2CP.
</p>
<p> <p>{% trans i2cp=site_url('docs/protocol/i2cp'),
i2psktmf='http://docs.i2p-projekt.de/javadoc/net/i2p/client/streaming/I2PSocketManagerFactory.html',
i2psktm='http://docs.i2p-projekt.de/javadoc/net/i2p/client/streaming/I2PSocketManager.html',
i2psess='http://docs.i2p-projekt.de/javadoc/net/i2p/client/streaming/I2PSession.html',
i2pskt='http://docs.i2p-projekt.de/javadoc/net/i2p/client/streaming/I2PSocket.html',
i2psskt='http://docs.i2p-projekt.de/javadoc/net/i2p/client/streaming/I2PServerSocket.html' -%}
The standard interface to the streaming lib is for the application to use the 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> <a href="{{ i2psktmf }}">I2PSocketManagerFactory</a> to create an
to create an <a href="{{ i2psktm }}">I2PSocketManager</a>. The application then asks the
<a href="http://docs.i2p-projekt.de/javadoc/net/i2p/client/streaming/I2PSocketManager.html">I2PSocketManager</a>. socket manager for an <a href="{{ i2psess }}">I2PSession</a>, which will cause
The application then asks the socket manager for an a connection to the router via <a href="{{ i2cp }}">I2CP</a>. The application
<a href="http://docs.i2p-projekt.de/javadoc/net/i2p/client/streaming/I2PSession.html">I2PSession</a>, can then setup connections with an <a href="{{ i2pskt }}">I2PSocket</a> or
which will cause a connection to the router via receive connections with an <a href="{{ i2psskt }}">I2PServerSocket</a>.
<a href="i2cp.html">I2CP</a>. {%- endtrans %}</p>
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> <p>{% trans url='http://docs.i2p-projekt.de/javadoc/net/i2p/client/streaming/package-summary.html' -%}
Here are the <a href="{{ url }}">full streaming library Javadocs</a>.
{%- endtrans %}</p>
<p>{% trans -%}
For a good example of usage, see the i2psnark code. For a good example of usage, see the i2psnark code.
</p> {%- endtrans %}</p>
<h3 id="options">Options and Defaults</h3> <h3 id="options">{% trans %}Options and Defaults{% endtrans %}</h3>
<p> <p>{% trans i2psktmf='http://docs.i2p-projekt.de/javadoc/net/i2p/client/streaming/I2PSocketManagerFactory.html' -%}
The options and current default values are listed below. 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 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. per-connection basis.
Many values are tuned for HTTP performance over typical I2P conditions. Other applications such Many values are tuned for HTTP performance over typical I2P conditions. Other applications such
as peer-to-peer services are strongly encouraged to as peer-to-peer services are strongly encouraged to
modify as necessary, by setting the options and passing them via the call 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). <a href="{{ i2psktmf }}">I2PSocketManagerFactory</a>.createManager(_i2cpHost, _i2cpPort, opts).
Time values are in ms. Time values are in ms.
</p> {%- endtrans %}</p>
<p>
Note that higher-layer APIs, such as <p>{% trans samv3=site_url('docs/api/samv3'), bob=site_url('docs/api/bob'), i2ptunnel=site_url('docs/api/i2ptunnel') -%}
<a href="{{ site_url('docs/api/samv3') }}">SAM</a>, Note that higher-layer APIs, such as <a href="{{ samv3 }}">SAM</a>,
<a href="{{ site_url('docs/api/bob') }}">BOB</a>, and <a href="{{ bob }}">BOB</a>, and <a href="{{ i2ptunnel }}">I2PTunnel</a>,
<a href="{{ site_url('docs/api/i2ptunnel') }}">I2PTunnel</a>,
may override these defaults with their own defaults. may override these defaults with their own defaults.
Also note that many options only apply to servers listening for incoming connections. Also note that many options only apply to servers listening for incoming connections.
</p><p> {%- endtrans %}</p>
<p>{% trans -%}
As of release 0.9.1, most, but not all, options may be changed on an active socket manager or session. 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. See the javadocs for details.
</p> {%- endtrans %}</p>
<table> <table>
<tr><th>Option</th><th>Default</th><th>Notes</th> <tr><th>{{ _('Option') }}</th><th>{{ _('Default') }}</th><th>{{ _('Notes') }}</th>
</tr> </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 <tr><td>i2cp.accessList</td><td>null</td><td>{% trans -%}
As of release 0.7.13. Comma- or space-separated list of Base64 peer Hashes used for either access list or blacklist.
</td></tr><tr><td>i2cp.enableAccessList</td><td>false {%- endtrans %} {% trans release='0.7.13' -%}
</td><td>Use the access list as a whitelist for incoming connections As of release {{ release }}.
As of release 0.7.13. {%- endtrans %}</td></tr>
</td></tr><tr><td>i2cp.enableBlackList</td><td>false
</td><td>Use the access list as a blacklist for incoming connections <tr><td>i2cp.enableAccessList</td><td>false</td><td>{% trans -%}
As of release 0.7.13. Use the access list as a whitelist for incoming connections.
</td></tr><tr><td>i2p.streaming.answerPings</td><td>true</td><td>Whether to respond to incoming pings {%- endtrans %} {% trans release='0.7.13' -%}
</td></tr><tr><td>i2p.streaming.blacklist</td><td>null</td><td>Comma- or space-separated list of Base64 peer Hashes to be As of release {{ release }}.
blacklisted for incoming connections to ALL destinations in the context. {%- endtrans %}</td></tr>
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 <tr><td>i2cp.enableBlackList</td><td>false</td><td>{% trans -%}
router in a separate JVM and context. Use the access list as a blacklist for incoming connections.
As of release 0.9.3. {%- endtrans %} {% trans release='0.7.13' -%}
</td></tr><tr><td>i2p.streaming.bufferSize</td><td>64K</td><td> As of release {{ release }}.
How much transmit data (in bytes) will be accepted that hasn't been written out yet. {%- endtrans %}</td></tr>
</td></tr><tr><td>i2p.streaming.congestionAvoidanceGrowthRateFactor</td><td>1
</td><td> <tr><td>i2p.streaming.answerPings</td><td>true</td><td>{% trans -%}
When we're in congestion avoidance, we grow the window size at the rate Whether to respond to incoming pings
of 1/(windowSize*factor). In standard TCP, window sizes are in bytes, {%- endtrans %}</td></tr>
while in I2P, window sizes are in messages.
A higher number means slower growth. <tr><td>i2p.streaming.blacklist</td><td>null</td><td>{% trans -%}
</td></tr><tr><td>i2p.streaming.connectDelay</td><td>-1 Comma- or space-separated list of Base64 peer Hashes to be
</td><td> blacklisted for incoming connections to ALL destinations in the context.
How long to wait after instantiating a new con This option must be set in the context properties, NOT in the createManager() options argument.
before actually attempting to connect. If this is Note that setting this in the router context will not affect clients outside the
&lt;= 0, connect immediately with no initial data. If greater than 0, wait router in a separate JVM and context.
until the output stream is flushed, the buffer fills, {%- endtrans %} {% trans release='0.9.3' -%}
or that many milliseconds pass, and include any initial data with the SYN. As of release {{ release }}.
</td></tr><tr><td>i2p.streaming.connectTimeout</td><td>5*60*1000</td><td> {%- endtrans %}</td></tr>
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> <tr><td>i2p.streaming.bufferSize</td><td>64K</td><td>{% trans -%}
Whether to disable warnings in the logs when an incoming connection is rejected due to connection limits. How much transmit data (in bytes) will be accepted that hasn't been written out yet.
As of release 0.9.4. {%- endtrans %}</td></tr>
</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 <tr><td>i2p.streaming.congestionAvoidanceGrowthRateFactor</td><td>1</td><td>{% trans -%}
(released March 2009). Set to true if running multiple protocols on this Destination. When we're in congestion avoidance, we grow the window size at the rate
As of release 0.9.1. of <code>1/(windowSize*factor)</code>. In standard TCP, window sizes are in bytes,
</td></tr><tr><td>i2p.streaming.inactivityAction</td><td>2 (send) </td><td>(0=noop, 1=disconnect) while in I2P, window sizes are in messages.
What to do on an inactivity timeout - do nothing, disconnect, or send a duplicate ack. A higher number means slower growth.
</td></tr><tr><td>i2p.streaming.inactivityTimeout</td><td>90*1000 {%- endtrans %}</td></tr>
</td></tr><tr><td>i2p.streaming.initialAckDelay</td><td>2000
</td></tr><tr><td>i2p.streaming.initialResendDelay</td><td>1000 <tr><td>i2p.streaming.connectDelay</td><td>-1</td><td>{% trans -%}
</td><td> How long to wait after instantiating a new con
The initial value of the resend delay field in the packet header, times 1000. before actually attempting to connect. If this is
Not fully implemented; see below. &lt;= 0, connect immediately with no initial data. If greater than 0, wait
</td></tr><tr><td>i2p.streaming.initialRTT</td><td>8000 </td><td>(if no <a href="#sharing">sharing data</a> available) until the output stream is flushed, the buffer fills,
</td></tr><tr><td>i2p.streaming.initialWindowSize</td><td>6</td><td>(if no <a href="#sharing">sharing data</a> available) or that many milliseconds pass, and include any initial data with the SYN.
In standard TCP, window sizes are in bytes, while in I2P, window sizes are in messages. {%- endtrans %}</td></tr>
</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. <tr><td>i2p.streaming.connectTimeout</td><td>5*60*1000</td><td>{% trans -%}
</td></tr><tr><td>i2p.streaming.maxConnsPerMinute</td><td>0 </td><td>Incoming connection limit (per peer; 0 means disabled) How long to block on connect, in milliseconds. Negative means indefinitely. Default is 5 minutes.
As of release 0.7.14. {%- endtrans %}</td></tr>
</td></tr><tr><td>i2p.streaming.maxConnsPerHour</td><td>0 </td><td>(per peer; 0 means disabled)
As of release 0.7.14. <tr><td>i2p.streaming.disableRejectLogging</td><td>false</td><td>{% trans -%}
</td></tr><tr><td>i2p.streaming.maxConnsPerDay</td><td>0 </td><td>(per peer; 0 means disabled) Whether to disable warnings in the logs when an incoming connection is rejected due to connection limits.
As of release 0.7.14. {%- endtrans %} {% trans release='0.9.4' -%}
</td></tr><tr><td>i2p.streaming.maxMessageSize</td><td>1730</td><td>The MTU in bytes. As of release {{ release }}.
</td></tr><tr><td>i2p.streaming.maxResends</td><td>8 {%- endtrans %}</td></tr>
</td><td>
Maximum number of retransmissions before failure. <tr><td>i2p.streaming.enforceProtocol</td><td>false</td><td>{% trans -%}
</td></tr><tr><td>i2p.streaming.maxTotalConnsPerMinute</td><td>0 </td><td>Incoming connection limit (all peers; 0 means disabled) Whether to listen only for the streaming protocol.
As of release 0.7.14. Setting to true will prohibit communication with Destinations earlier than release 0.7.1
</td></tr><tr><td>i2p.streaming.maxTotalConnsPerHour</td><td>0 </td><td>(all peers; 0 means disabled) (released March 2009). Set to true if running multiple protocols on this Destination.
Use with caution as exceeding this will disable a server for a long time. {%- endtrans %} {% trans release='0.9.1' -%}
As of release 0.7.14. As of release {{ release }}.
</td></tr><tr><td>i2p.streaming.maxTotalConnsPerDay</td><td>0 </td><td>(all peers; 0 means disabled) {%- endtrans %}</td></tr>
Use with caution as exceeding this will disable a server for a long time.
As of release 0.7.14. <tr><td>i2p.streaming.inactivityAction</td><td>2 (send) </td><td>{% trans -%}
</td></tr><tr><td>i2p.streaming.maxWindowSize</td><td>128 (0=noop, 1=disconnect)
</td></tr><tr><td>i2p.streaming.profile</td><td>1 (bulk)</td><td>(2=interactive not supported) What to do on an inactivity timeout - do nothing, disconnect, or send a duplicate ack.
This doesn't currently do anything, but setting it to a value other than 1 will cause an error. {%- endtrans %}</td></tr>
</td></tr><tr><td>i2p.streaming.readTimeout</td><td>-1
</td><td> <tr><td>i2p.streaming.inactivityTimeout</td><td>90*1000</td></tr>
How long to block on read, in milliseconds. Negative means indefinitely. <tr><td>i2p.streaming.initialAckDelay</td><td>2000</td></tr>
</td></tr><tr><td>i2p.streaming.slowStartGrowthRateFactor</td><td>1
</td><td> <tr><td>i2p.streaming.initialResendDelay</td><td>1000</td><td>{% trans -%}
When we're in slow start, we grow the window size at the rate The initial value of the resend delay field in the packet header, times 1000.
of 1/(factor). In standard TCP, window sizes are in bytes, Not fully implemented; see below.
while in I2P, window sizes are in messages. {%- endtrans %}</td></tr>
A higher number means slower growth.
</td></tr><tr><td>i2p.streaming.writeTimeout</td><td>-1 <tr><td>i2p.streaming.initialRTT</td><td>8000 </td><td>({% trans %}if no <a href="#sharing">sharing data</a> available{% endtrans %})</td></tr>
</td><td>
How long to block on write/flush, in milliseconds. Negative means indefinitely. <tr><td>i2p.streaming.initialWindowSize</td><td>6</td><td>({% trans %}if no <a href="#sharing">sharing data</a> available{% endtrans %}) {% trans -%}
</td></tr> In standard TCP, window sizes are in bytes, while in I2P, window sizes are in messages.
{%- endtrans %}</td></tr>
<tr><td>i2p.streaming.maxConcurrentStreams</td><td>-1 </td><td>{% trans -%}
(0 or negative value means unlimited)
This is a total limit for incoming and outgoing combined.
{%- endtrans %}</td></tr>
<tr><td>i2p.streaming.maxConnsPerMinute</td><td>0 </td><td>{% trans -%}
Incoming connection limit (per peer; 0 means disabled)
{%- endtrans %} {% trans release='0.7.14' -%}
As of release {{ release }}.
{%- endtrans %}</td></tr>
<tr><td>i2p.streaming.maxConnsPerHour</td><td>0 </td><td>{% trans -%}
(per peer; 0 means disabled)
{%- endtrans %} {% trans release='0.7.14' -%}
As of release {{ release }}.
{%- endtrans %}</td></tr>
<tr><td>i2p.streaming.maxConnsPerDay</td><td>0 </td><td>{% trans -%}
(per peer; 0 means disabled)
{%- endtrans %} {% trans release='0.7.14' -%}
As of release {{ release }}.
{%- endtrans %}</td></tr>
<tr><td>i2p.streaming.maxMessageSize</td><td>1730</td><td>{% trans -%}
The MTU in bytes.
{%- endtrans %}</td></tr>
<tr><td>i2p.streaming.maxResends</td><td>8</td><td>{% trans -%}
Maximum number of retransmissions before failure.
{%- endtrans %}</td></tr>
<tr><td>i2p.streaming.maxTotalConnsPerMinute</td><td>0 </td><td>{% trans -%}
Incoming connection limit (all peers; 0 means disabled)
{%- endtrans %} {% trans release='0.7.14' -%}
As of release {{ release }}.
{%- endtrans %}</td></tr>
<tr><td>i2p.streaming.maxTotalConnsPerHour</td><td>0 </td><td>{% trans -%}
(all peers; 0 means disabled)
Use with caution as exceeding this will disable a server for a long time.
{%- endtrans %} {% trans release='0.7.14' -%}
As of release {{ release }}.
{%- endtrans %}</td></tr>
<tr><td>i2p.streaming.maxTotalConnsPerDay</td><td>0 </td><td>{% trans -%}
(all peers; 0 means disabled)
Use with caution as exceeding this will disable a server for a long time.
{%- endtrans %} {% trans release='0.7.14' -%}
As of release {{ release }}.
{%- endtrans %}</td></tr>
<tr><td>i2p.streaming.maxWindowSize</td><td>128</td></tr>
<tr><td>i2p.streaming.profile</td><td>1 (bulk)</td><td>{% trans -%}
(2=interactive not supported)
This doesn't currently do anything, but setting it to a value other than 1 will cause an error.
{%- endtrans %}</td></tr>
<tr><td>i2p.streaming.readTimeout</td><td>-1</td><td>{% trans -%}
How long to block on read, in milliseconds. Negative means indefinitely.
{%- endtrans %}</td></tr>
<tr><td>i2p.streaming.slowStartGrowthRateFactor</td><td>1</td><td>{% trans -%}
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.
{%- endtrans %}</td></tr>
<tr><td>i2p.streaming.writeTimeout</td><td>-1</td><td>{% trans -%}
How long to block on write/flush, in milliseconds. Negative means indefinitely.
{%- endtrans %}</td></tr>
</table> </table>
<h2>Protocol Specification</h2> <h2>{% trans %}Protocol Specification{% endtrans %}</h2>
<h3>Packet Format</h3> <h3>{% trans %}Packet Format{% endtrans %}</h3>
<p> <p>{% trans -%}
The format of a single packet in the streaming protocol is: The format of a single packet in the streaming protocol is:
{%- endtrans %}</p>
<pre> <pre>
+----+----+----+----+----+----+----+----+ +----+----+----+----+----+----+----+----+
@@ -232,7 +306,7 @@ The format of a single packet in the streaming protocol is:
</pre> </pre>
<table> <table>
<tr><th>Field<th>Length<th>Contents <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 <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. 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, 0 in the SYN message sent by the originator, and in subsequent messages, until a SYN reply is received,
@@ -280,11 +354,14 @@ As specified by the flags. See below.
<tr><td>payload <td>remaining packet size<td> <tr><td>payload <td>remaining packet size<td>
</table> </table>
<h3>Flags and Option Data Fields</h3> <h3>{% trans %}Flags and Option Data Fields{% endtrans %}</h3>
<p>The flags field above specifies some metadata about the packet, and in <p>{% trans -%}
The flags field above specifies some metadata about the packet, and in
turn may require certain additional data to be included. The flags are 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 as follows. Any data structures specified must be added to the options area
in the given order.</p> in the given order.
{%- endtrans %}</p>
<p> <p>
Bit order: 15....0 (15 is MSB) Bit order: 15....0 (15 is MSB)
</p> </p>
@@ -329,30 +406,32 @@ Currently unused, the ackThrough field is always valid.
<tr><td>11-15<td>unused<td><td> <tr><td>11-15<td>unused<td><td>
</table> </table>
<h2>Implementation Details</h2> <h2>{% trans %}Implementation Details{% endtrans %}</h2>
<h3>Setup</h3> <h3>{% trans %}Setup{% endtrans %}</h3>
<p> <p>{% trans -%}
The initiator sends a packet with the SYNCHRONIZE flag set. This packet may contain the initial data as well. 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. The peer replies with a packet with the SYNCHRONIZE flag set. This packet may contain the initial response data as well.
</p> {%- endtrans %}</p>
<p>
<p>{% trans -%}
The initiator may send additional data packets, up to the initial window size, before receiving the SYNCHRONIZE response. 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. 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 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. arrive out of order, in advance of the SYNCHRONIZE packet.
</p> {%- endtrans %}</p>
<h3>MTU Selection and Negotiation</h3> <h3>{% trans %}MTU Selection and Negotiation{% endtrans %}</h3>
<p> <p>{% trans -%}
The maximum message size (also called the MTU / MRU) is negotiated to the lower value supported by 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 the two peers. As tunnel messages are padded to 1KB, a poor MTU selection will lead to
a large amount of overhead. a large amount of overhead.
The MTU is specified by the option i2p.streaming.maxMessageSize. 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, The current default MTU of 1730 was chosen to fit precisely into two 1K I2NP tunnel messages,
including overhead for the typical case. including overhead for the typical case.
</p> {%- endtrans %}</p>
<p>
<p>{% trans -%}
The first message in a connection includes a 387 byte (typical) Destination added by the streaming layer, 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. 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). (The LeaseSet and Session Keys will not be bundled if an ElGamal Session was previously established).
@@ -360,42 +439,45 @@ Therefore, the goal of fitting a complete HTTP request in a single 1KB I2NP mess
However, the selection of the MTU, together with careful implementation of fragmentation 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, and batching strategies in the tunnel gateway processor, are important factors in network bandwidth,
latency, reliability, and efficiency, especially for long-lived connections. latency, reliability, and efficiency, especially for long-lived connections.
</p> {%- endtrans %}</p>
<h3>Data Integrity</h3> <h3>{% trans %}Data Integrity{% endtrans %}</h3>
<p>{% trans i2cp=site_url('docs/protocol/i2cp') -%}
Data integrity is assured by the gzip CRC-32 checksum implemented in Data integrity is assured by the gzip CRC-32 checksum implemented in
<a href="i2cp.html#format">the I2CP layer</a>. <a href="{{ i2cp }}#format">the I2CP layer</a>.
There is no checksum field in the streaming protocol. There is no checksum field in the streaming protocol.
{%- endtrans %}</p>
<h3>Packet Encapsulation</h3> <h3>{% trans %}Packet Encapsulation{% endtrans %}</h3>
<p>{% trans garlicrouting=site_url('docs/how/garlic-routing'), i2cp=site_url('docs/protocol/i2cp'),
i2np=site_url('docs/protocol/i2np'), tunnelmessage=site_url('docs/spec/tunnel-message') -%}
Each packet is sent through I2P as a single message (or as an individual clove in a 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>). <a href="{{ garlicrouting }}">Garlic Message</a>). Message encapsulation is implemented
Message encapsulation is implemented in the underlying in the underlying <a href="{{ i2cp }}">I2CP</a>, <a href="{{ i2np }}">I2NP</a>, and
<a href="i2cp.html">I2CP</a>, <a href="{{ tunnelmessage }}">tunnel message</a> layers. There is no packet delimiter
<a href="i2np.html">I2NP</a>, and mechanism or payload length field in the streaming protocol.
<a href="tunnel_message_spec.html">tunnel message</a> layers. {%- endtrans %}</p>
There is no packet delimiter mechanism or payload length field in the streaming protocol.
<h3>Windowing</h3> <h3>{% trans %}Windowing{% endtrans %}</h3>
<p> <p>{% trans -%}
The streaming lib uses standard slow-start (exponential window growth) and congestion avoidance (linear window growth) The streaming lib uses standard slow-start (exponential window growth) and congestion avoidance (linear window growth)
phases, with exponential backoff. phases, with exponential backoff.
Windowing and acknowledgments use packet count, not byte count. Windowing and acknowledgments use packet count, not byte count.
</p> {%- endtrans %}</p>
<h3>Close</h3> <h3>{% trans %}Close{% endtrans %}</h3>
<p> <p>{% trans -%}
Any packet, including one with the SYNCHRONIZE flag set, may have the CLOSE flag sent as well. 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. The connection is not closed until the peer responds with the CLOSE flag.
CLOSE packets may contain data as well. CLOSE packets may contain data as well.
</p> {%- endtrans %}</p>
<h3 id="sharing">Control Block Sharing</h3> <h3 id="sharing">{% trans %}Control Block Sharing{% endtrans %}</h3>
<p> <p>{% trans -%}
The streaming lib supports "TCP" Control Block sharing. The streaming lib supports "TCP" Control Block sharing.
This shares two important streaming lib parameters This shares two important streaming lib parameters
(window size and round trip time) (window size and round trip time)
@@ -407,10 +489,12 @@ There is a separate share per ConnectionManager (i.e. per local Destination)
so that there is no information leakage to other Destinations on the so that there is no information leakage to other Destinations on the
same router. same router.
The share data for a given peer expires after a few minutes. The share data for a given peer expires after a few minutes.
</p> {%- endtrans %}</p>
<h3 id="other">Other Parameters</h3> <h3 id="other">{% trans %}Other Parameters{% endtrans %}</h3>
<p>{% trans -%}
The following parameters are hardcoded, but may be of interest for analysis: The following parameters are hardcoded, but may be of interest for analysis:
{%- endtrans %}</p>
<ul> <ul>
<li>MIN_RESEND_DELAY = 2*1000 (minimum RTO) <li>MIN_RESEND_DELAY = 2*1000 (minimum RTO)
<li>MAX_RESEND_DELAY = 45*1000 (maximum RTO) <li>MAX_RESEND_DELAY = 45*1000 (maximum RTO)
@@ -425,8 +509,8 @@ The following parameters are hardcoded, but may be of interest for analysis:
</ul> </ul>
</p> </p>
<h3>History</h3> <h3>{% trans %}History{% endtrans %}</h3>
<p> <p>{% trans -%}
The streaming library has grown organically for I2P - first mihi implemented the 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 "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 size of 1 message (requiring an ACK before sending the next one), and then it was
@@ -437,26 +521,25 @@ 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, message size is selected to fit precisely in two 1K I2NP tunnel messages,
and is a reasonable tradeoff between the bandwidth costs of and is a reasonable tradeoff between the bandwidth costs of
retransmitting lost messages, and the latency and overhead of multiple messages. retransmitting lost messages, and the latency and overhead of multiple messages.
</p> {%- endtrans %}</p>
<h2 id="future">{% trans %}Future Work{% endtrans %}</h2>
<p>{% trans -%}
<h2 id="future">Future Work</h2>
The behavior of the streaming library has a profound impact on The behavior of the streaming library has a profound impact on
application-level performance, and as such, is an important application-level performance, and as such, is an important
area for further analysis. area for further analysis.
{%- endtrans %}</p>
<ul> <ul>
<li> <li>{% trans -%}
Additional tuning of the streaming lib parameters may be necessary. Additional tuning of the streaming lib parameters may be necessary.
</li> {%- endtrans %}</li>
<li> <li>{% trans ntcpdisc=site_url('docs/discussions/ntcp') -%}
Another area for research is the interaction of the streaming lib with the Another area for research is the interaction of the streaming lib with the
NTCP and SSU transport layers. NTCP and SSU transport layers.
See <a href="{{ site_url('docs/transport/ntcp/discussion') }}">the NTCP discussion page</a> for details. See <a href="{{ ntcpdisc }}">the NTCP discussion page</a> for details.
</li> {%- endtrans %}</li>
<li> <li>{% trans -%}
The interaction of the routing algorithms with the streaming lib strongly affects performance. 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 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 leads to a high degree of out-of-order delivery which results in smaller window
@@ -465,38 +548,35 @@ messages for a single from/to destination pair through a consistent set
of tunnels, until tunnel expiration or delivery failure. The router's of tunnels, until tunnel expiration or delivery failure. The router's
failure and tunnel selection algorithms should be reviewed for possible failure and tunnel selection algorithms should be reviewed for possible
improvements. improvements.
</li> {%- endtrans %}</li>
<li> <li>{% trans -%}
The data in the first SYN packet may exceed the receiver's MTU. The data in the first SYN packet may exceed the receiver's MTU.
</li> {%- endtrans %}</li>
<li> <li>{% trans -%}
The DELAY_REQUESTED field could be used more. The DELAY_REQUESTED field could be used more.
</li> {%- endtrans %}</li>
<li> <li>{% trans -%}
Duplicate initial SYNCHRONIZE packets on short-lived streams may not be recognized and removed. Duplicate initial SYNCHRONIZE packets on short-lived streams may not be recognized and removed.
</li> {%- endtrans %}</li>
<li> <li>{% trans -%}
Don't send the MTU in a retransmission. Don't send the MTU in a retransmission.
</li> {%- endtrans %}</li>
<li> <li>{% trans -%}
Data is sent along unless the outbound window is full. Data is sent along unless the outbound window is full.
(i.e. no-Nagle or TCP_NODELAY) (i.e. no-Nagle or TCP_NODELAY)
Probably should have a configuration option for this. Probably should have a configuration option for this.
</li> {%- endtrans %}</li>
<li> <li>{% trans -%}
zzz has added debug code to the streaming library to log packets in a wireshark-compatible zzz has added debug code to the streaming library to log packets in a wireshark-compatible
(pcap) format; Use this to further analyze performance. (pcap) format; Use this to further analyze performance.
The format may require enhancement to map more streaming lib parameters to TCP fields. The format may require enhancement to map more streaming lib parameters to TCP fields.
</li> {%- endtrans %}</li>
<li> <li>{% trans -%}
There are proposals to replace the streaming lib with standard TCP There are proposals to replace the streaming lib with standard TCP
(or perhaps a null layer together with raw sockets). (or perhaps a null layer together with raw sockets).
This would unfortunately be incompatible with the streaming lib This would unfortunately be incompatible with the streaming lib
but it would be good to compare the performance of the two. but it would be good to compare the performance of the two.
</li> {%- endtrans %}</li>
</ul> </ul>
{% endblock %} {% endblock %}