{% extends "global/layout.html" %}
{% block title %}I2PTunnel{% endblock %}
{% block lastupdated %}2022-09{% endblock %}
{% block accuratefor %}1.9.0{% endblock %}
{% block content %}

<h2 id="overview">{% trans %}Overview{% endtrans %}</h2>
<p>{% trans naming=site_url('docs/naming') -%}
I2PTunnel is a tool for interfacing with and providing services on I2P.
Destination of an I2PTunnel can be defined using a <a href="{{ naming }}">hostname</a>,
<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.
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
for the service and it will become avaliable throughout I2P.
A web interface for I2PTunnel management is avaliable on
<a href="http://localhost:7657/i2ptunnel/">localhost:7657/i2ptunnel/</a>.
{%- endtrans %}</p>

<h2 id="default-services">{% trans %}Default Services{% endtrans %}</h2>
<h3 id="default-server-tunnels">{% trans %}Server tunnels{% endtrans %}</h3>
<ul>
<li>{% trans -%}
<b>I2P Webserver</b> - A tunnel pointed to a Jetty webserver run
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> - $HOME/.i2p/eepsite/docroot
<br><b>Windows</b> - %LOCALAPPDATA%\I2P\I2P Site\docroot, which expands to: C:\Users\**username**\AppData\Local\I2P\I2P Site\docroot
</li>
</ul>
<h3 id="default-client-tunnels">{% trans %}Client tunnels{% endtrans %}</h3>
<ul>
<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.
{%- endtrans %}</li>
<li><b>Irc2P</b> - <i>localhost:6668</i> - {% trans %}An IRC tunnel to the default anonymous IRC network, Irc2P.{% endtrans %}</li>
<li><b>gitssh.idk.i2p</b> - <i>localhost:7670</i> -
SSH access to the project Git repository
</li>
<li><b>smtp.postman.i2p</b> - <i>localhost:7659</i> - {% trans postman=i2pconv('hq.postman.i2p') -%}
A SMTP service provided by postman at <a href="http://{{ postman }}/?page_id=16">{{ postman }}</a>
{%- endtrans %}</li>
<li><b>pop3.postman.i2p</b> - <i>localhost:7660</i> - {% trans postman=i2pconv('hq.postman.i2p') -%}
The accompanying POP sevice of postman at <a href="http://{{ postman }}/?page_id=16">{{ postman }}</a>
{%- endtrans %}</li>
</ul>

<h2 id="client-modes">{% trans %}Configuration{% endtrans %}</h2>
<a href="{{ site_url('docs/spec/configuration') }}">{{ _('I2PTunnel Configuration') }}</a>


<h2 id="client-modes">{% trans %}Client Modes{% endtrans %}</h2>
<h3 id="client-modes-standard">{% trans %}Standard{% endtrans %}</h3>
<p>{% trans -%}
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.
{%- endtrans %}</p>

<h3 id="client-mode-http">HTTP</h3>
<p>{% trans -%}
A HTTP-client tunnel. The tunnel connects to the destination specified by the URL
in a HTTP request. Supports proxying onto internet if an outproxy is provided. Strips HTTP connections of the following headers:
{%- endtrans %}</p>
<ul>
<li>{% trans -%}
<b>Accept, Accept-Charset, Accept-Language
 and Accept-Ranges</b> as they vary greatly between browsers and can be used as an identifier.
{%- endtrans %}</li>
<li><b>Referer:</b></li>
<li><b>Via:</b></li>
<li><b>From:</b></li>
</ul>

<p>
The HTTP client proxy provides a number of services to protect the user
and to provide a better user experience.
</p>

<ul><li>Request header processing:
<ul><li>Strip privacy-problematic headers
<li>Routing to local or remote outproxy
<li>Outproxy selection, caching, and reachability tracking
<li>Hostname to destination lookups
<li>Host header replacement to b32
<li>Add header to indicate support for transparent decompression
<li>Force connection: close
<li>RFC-compliant proxy support
<li>RFC-compliant hop-by-hop header processing and stripping
<li>Optional digest and basic username/password authentication
<li>Optional outproxy digest and basic username/password authentication
<li>Buffering of all headers before passing through for efficiency
<li>Jump server links
<li>Jump response processing and forms (address helper)
<li>Blinded b32 processing and credential forms
<li>Supports standard HTTP and HTTPS (CONNECT) requests
</ul>

<li>Response header processing:
<ul><li>Check for whether to decompress response
<li>Force connection: close
<li>RFC-compliant hop-by-hop header processing and stripping
<li>Buffering of all headers before passing through for efficiency
</ul>

<li>HTTP error responses:
<ul><li>For many common and not-so-common errors, so the user knows what happened
<li>Over 20 unique translated, styled, and formatted error pages for various errors
<li>Internal web server to serve forms, CSS, images, and errors
</ul>

<li>Transparent response decompression:
<ul><li>If the server-side HTTP proxy compressed the response,
the HTTP client proxy transparently decompresses it.
</ul>
</ul>


<p>
The i2ptunnel compression is requested with the HTTP header:
</p>
<ul>
<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>

<p>
The response indicating i2ptunnel compression contains the following HTTP header:
</p>
<ul>
<li><b>Content-Encoding: </b> x-i2p-gzip</li>
</ul>

<p>{% trans -%}
Depending on if the tunnel is using an outproxy or not it will append the following User-Agent: 
{%- endtrans %}</p>
<ul>
<li><i>{% trans %}Outproxy:{% endtrans %} </i><b>User-Agent:</b> Uses the user agent from a recent Firefox release on Windows</li>
<li><i>{% trans %}Internal I2P use:{% endtrans %} </i><b>User-Agent:</b> MYOB/6.66 (AN/ON)</li>
</ul>
</p>

<h3 id="client-mode-irc">IRC Client</h3>
<p>{% trans -%}
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.
{%- endtrans %}
The following allow list is for commands inbound from the IRC server to the IRC client.
<br>Allow list:</p>
<ul>
<li>AUTHENTICATE</li>
<li>CAP</li>
<li>ERROR</li>
<li>H</li>
<li>JOIN</li>
<li>KICK</li>
<li>MODE</li>
<li>NICK</li>
<li>PART</li>
<li>PING</li>
<li>PROTOCTL</li>
<li>QUIT</li>
<li>TOPIC</li>
<li>WALLOPS</li>
</ul>

<p>
There is also a whitelist is for commands outbound from the IRC client to the IRC server.
It is quite large due to the number of IRC administrative commands.
See the IRCFilter.java source for details.
The outbound filter also modifies the following commands to strip identifying information:
</p>
<ul>
<li>NOTICE</li>
<li>PART</li>
<li>PING</li>
<li>PRIVMSG</li>
<li>QUIT</li>
<li>USER</li>
</ul>

<h3 id="client-mode-socks">SOCKS 4/4a/5</h3>
<p>{% trans -%}
Enables using the I2P router as a SOCKS proxy.
{%- endtrans %}</p>

<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
<a href="#client-mode-irc">IRC</a> client mode.
{%- endtrans %}</p>

<h3 id="client-mode-connect">CONNECT</h3>
<p>{% trans -%}
Creates a HTTP tunnel and uses the HTTP request method "CONNECT" 
to build a TCP tunnel that usually is used for SSL and HTTPS.
{%- endtrans %}</p>

<h3 id="client-mode-streamr">Streamr</h3>
<p>{% trans -%}
Creates a UDP-server attached to a Streamr client I2PTunnel. The streamr client tunnel will 
subscribe to a streamr server tunnel.
{%- endtrans %}</p>
<img src="{{ url_for('static', filename='images/I2PTunnel-streamr.png') }}">


<br>
<h2 id="server-modes">{% trans %}Server Modes{% endtrans %}</h2>
<h3 id="server-mode-standard">{% trans %}Standard{% endtrans %}</h3>
<p>{% trans -%}
Creates a destination to a local ip:port with an open TCP port.
{%- endtrans %}</p>

<h3 id="server-mode-http">HTTP</h3>
<p>{% trans -%}
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.
{%- endtrans %}</p>

<p>
The HTTP server proxy provides a number of services to make hosting a website easier and more secure,
and to provide a better user experience on the client side.
</p>

<ul><li>Request header processing:
<ul><li>Header validation
<li>Header spoof protection
<li>Header size checks
<li>Optional inproxy and user-agent rejection
<li>Add X-I2P headers so the webserver knows where the request came from
<li>Host header replacement to make webserver vhosts easier
<li>Force connection: close
<li>RFC-compliant hop-by-hop header processing and stripping
<li>Buffering of all headers before passing through for efficiency
</ul>

<li>DDoS protection:
<ul><li>POST throttling
<li>Timeouts and slowloris protection
<li>Additional throttling happens in streaming for all tunnel types
</ul>

<li>Response header processing:
<ul><li>Stripping of some privacy-problematic headers
<li>Mime type and other headers check for whether to compress response
<li>Force connection: close
<li>RFC-compliant hop-by-hop header processing and stripping
<li>Buffering of all headers before passing through for efficiency
</ul>

<li>HTTP error responses:
<ul><li>For many common and not-so-common errors and on throttling, so the client-side user knows what happened
</ul>

<li>Transparent response compression:
<ul><li>The web server and/or the I2CP layer may compress, but the web server often does not,
and it's most efficient to compress at a high layer, even if I2CP also compresses.
The HTTP server proxy works cooperatively with the client-side proxy to transparently compress responses.
</ul>
</ul>


<h3 id="server-mode-http-bidir">HTTP Bidirectional</h3>
<p><i>Deprecated</i></p>
<p>{% trans -%}
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
requests, or loopback-testing an I2P Site as a diagnostic tool.
{%- endtrans %}</p>

<h3 id="server-mode-irc">IRC Server</h3>
<p>{% trans -%}
Creates a destination that filters the reqistration sequence of a client and passes 
the clients destination key as a hostname to the IRC-server.
{%- endtrans %}</p>

<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.
{%- endtrans %}</p>
{% endblock %}