# User's Guide:i2p.tunnel

From Python-I2P.

Module `i2p.tunnel` allows data to be exchanged between traditional TCP sockets and I2P sockets.

## Tunnels

Tunnels allow stream sockets to be joined, so that connections to a listening socket are relayed to one or more sending sockets. This allows an ordinary web server to be exposed as an I2P Destination, or an I2P Destination to be bound as a local port, and so on.

class Tunnel(self, receive, make_send, nconnect=-1, timeout=60.0)

     A Tunnel relays connections from a 'receive' socket to one
     or more 'send' sockets.  The receive socket must be bound
     and listening.  For each incoming connection, a new send
     socket is created by calling make_send().  Data is then
     exchanged between the created streams until one socket is
     closed.  nconnect is the maximum number of simultaneous
     connections (-1 for infinite), and timeout is the time that
     a single connection can last for (None allows a connection
     to last forever).

     Sockets must accept stream traffic and support the Python
     socket interface.  A separate daemonic thread is created to
     manage the tunnel.  For high performance, make_send() should
     make a socket and connect in non-blocking mode (you should
     catch and discard the i2p.socket.BlockError or socket.error
     due to executing connect on a non-blocking socket).

     Security Note:
     A firewall is needed to maintain the end user's anonymity.
     An attacker could keep a tunnel socket open by pinging it
     regularly.  The accepted sockets from 'receive' must prevent
     this by closing down eventually.

     Socket errors do not cause the Tunnel to shut down.

close()

     Close all connections made for this tunnel.

### Tunnel Server

class TunnelServer(session, port, samaddr='127.0.0.1:7656', nconnect=-1, timeout=None, **kwargs)

     Tunnels incoming SAM streams --> localhost:port.

     nconnect and timeout are the maximum number of connections
     and maximum time per connection.  All other arguments are
     passed to i2p.socket.socket().  This call blocks until the
     tunnel is ready.

TunnelServer properties:

     dest       - I2P Destination of server.
     session    - Session name for server.

### Tunnel Client

class TunnelClient(session, port, dest, samaddr='127.0.0.1:7656', nconnect=-1, timeout=None, **kwargs)

     Derived from Tunnel.
     Tunnels localhost:port --> I2P Destination dest.

     A session named 'session' is created locally, for purposes
     of routing to 'dest'.  nconnect and timeout are the maximum
     number of connections and maximum time per connection.  All
     other arguments are passed to i2p.socket.socket().  This call
     blocks until the tunnel is ready.

TunnelClient properties:

     dest       - Local Destination used for routing.
     remotedest - Remote Destination.
     session    - Session name for local Destination.