I2P For Beginners: Java Software Guide

The Invisible Internet Project
9 min readOct 31, 2022


The I2P Router

The I2P router handles your connection to the I2P network.

The first time an I2P router makes connections to the network, it may take a few minutes to integrate your router into the network. As it begins to make this connection by finding peers, you will see the number of Active Peers begin to grow in the sidebar Peers status section.

When the router is integrated, a Local Tunnel named Shared Clients will display a green indicator to communicate its readiness. These Local Tunnels provide connections to the I2P network. They enable bittorrent, email, web proxy and other services.

When the I2P router starts up, and during normal operation, the tunnel build readiness indicator in the sidebar may indicate that I2P is “Rejecting Tunnels.” This is normal behaviour.

The I2P Router Console

The Router Console handles communication and monitoring from the router and clients, offers shortcuts to applications, and serves as an admin resource for people who want to customize or configure their I2P network connections and workflow.

The console itself is customizable and includes a default light theme with a dark theme option.


This is the landing page of the I2P router console

The sidebar will communicate the following:

  • Your version of the I2P software and when an update is available.
  • How long the router has been running.
  • Router connection status.
  • Bandwidth In and Out.
  • Tunnel build status.

News : The news section will display highlights from a new release, and alerts. This section can be displayed or hidden based on your preference.

Applications The I2P router includes : I2P Address book , Email, Hidden Services Manager, BitTorrent client, and a static site generator. This section provides links to each.

I2P Community Sites This is a collection of I2P network sites and services that the I2P team hosts. They include links to zzz’ dev forum, the community forum, the project Gitlab, and more. If you want to check if your browser is configured properly and if you are connected to the I2P network, click on one of these options to find out!

Configuration and Help In this section you can access your bandwidth sharing options, help and FAQ , and add plugins to your router, or customize the look of your router console.

Network and Developer Information Links in this section include access to I2P technical docs, Gitlab issues, Trac Wiki, and metrics options for people who are interested in I2P network statistics. Logs for your router can be accessed here as well.


/console is a welcome page that provides information about error messages, warmings and troubleshooting information.

The sidebar will communicate the following:

  • Your version of the I2P software and when an update is available.
  • How long the router has been running
  • Router connection status
  • Tunnel build status
  • Reseed if required
  • Options to stop, restart your router
  • Local Tunnels and Shared Clients
  • Shortcuts to applications, services, configuration, troubleshooting and logs.
A new router install encountering connection issues and prompting Reseed action.

Sidebar Peer and Tunnel Summary Information

Exploratory tunnels: These are tunnels built by the router and used for communication with the floodfill peers, building new tunnels, and testing existing tunnels.

Client tunnels: Tunnels built by the router for each client’s use.

Participating tunnels: Tunnels built by other routers through your router. The quantity will vary depending on network demand, your shared bandwidth, and amount of traffic your own usage creates.

***The recommended method for limiting participating tunnels is to change your share percentage on the Bandwidth Configuration page.

Share ratio: The number of participating tunnels you route for others, divided by the total number of hops in all your exploratory and client tunnels. A number greater than 1.00 means you are contributing more tunnels to the network than you are using.

How connections look when just starting up the router

Sidebar Error Messages And What They Mean

Reseed: In some cases there are issues with finding Peers and connecting with the I2P network. If the router is encountering this issue, it will provide the option to “Reseed” in the sidebar. Clicking the Reseed button will fetch a bundle of Peers router infos in an attempt to correct the issue.

OK: Your UDP port does not appear to be firewalled.

Firewalled: The I2P router will work fine when firewalled, there is no reason for concern. When firewalled, the router uses “introducers” to relay inbound connections. However, you will get more participating traffic and help the network if you open your firewall. If you think you have already done so, remember that you may have both a hardware and a software firewall, or be behind an additional, institutional firewall you cannot control. Also, some routers cannot correctly forward both TCP and UDP on a single port, or may have other limitations or bugs that prevent them from passing traffic through to I2P.

Testing: The I2P router is currently testing whether your UDP port is firewalled.

Hidden: The I2P router is not configured to publish its address, therefore it does not expect incoming connections. Hidden mode is automatically enabled for added protection in certain countries. Too see the countries that are on this list refer to the Strict Countries List.

WARN — Firewalled and Fast: You have configured your I2P router to share more than 128KBps of bandwidth, but you are firewalled. While the router will work in this configuration, if you really have over 128KBps of bandwidth to share, it will be much more helpful to the network if you open your firewall.

WARN — Firewalled and Floodfill: You have configured the I2P router to be a floodfill router, but you are firewalled. For best participation as a floodfill router, you should open your firewall.

WARN — Firewalled with Inbound TCP Enabled: You have configured inbound TCP, however your UDP port is firewalled, and therefore it is likely that your TCP port is firewalled as well. If your TCP port is firewalled with inbound TCP enabled, routers will not be able to contact you via TCP, which will hurt the network. Please open your firewall or disable inbound TCP above.

WARN — Firewalled with UDP Disabled: You have configured inbound TCP, however you have disabled UDP. You appear to be firewalled on TCP, therefore your router cannot accept inbound connections. Please open your firewall or enable UDP.

ERR — Clock Skew: Your system’s clock is skewed, which will make it difficult to participate in the network. Correct your clock setting if this error persists.

ERR — Private TCP Address: You must never advertise an unroutable IP address such as or as your external address. Correct the address or disable inbound TCP on the Network Configuration page.

ERR — SymmetricNAT: The I2P router detected that you are firewalled by a Symmetric NAT. The I2P router does not work well behind this type of firewall. The router will probably not be able to accept inbound connections, which will limit participation in the network.

ERR — UDP Port In Use — Set i2np.udp.internalPort=xxxx in advanced config and restart: The I2P router was unable to bind to the configured port noted on the advanced network configuration page . Check to see if another program is using the configured port. If so, stop that program or configure the I2P router to use a different port. This may be a transient error, if the other program is no longer using the port. However, a restart is always required after this error.

ERR — UDP Disabled and Inbound TCP host/port not set: You have not configured inbound TCP with an address and port on the Network Configuration page, however you have disabled UDP. Therefore your router cannot accept inbound connections. Please configure a TCP host and port on the Network Configuration page or enable UDP.

ERR — Client Manager I2CP Error — check logs: This is usually due to a port 7654 conflict. Check the logs to verify. Do you have another I2P instance running? Stop the conflicting program and restart the I2P router.

I2P Applications, Services and Configuration

Applications are made available through a webUI that listens at


Developed by: postman, susi23, mastiejaner.

SusiMail is a secure email client. It is primarily intended for use with Postman’s email servers inside of the I2P network. It is designed to avoid leaking information about email use to other networks. SusiMail is bridged so it can send and receive email from the internet as well. Occasionally you may see some services like Gmail classifying it as spam, which you can correct in your Internet email service providers settings.

Postman’s service offers both internal and external email with POP3 and SMTP service through I2PTunnel. This allows people to use their preferred mail clients to send and receive mail pseudonymously.

Most mail clients expose substantial identifying information, however, SusiMail has been built specifically with I2P’s anonymity abilities in mind. The I2Pmail/mail.i2p service offers transparent virus filtering as well as denial of service prevention with hashcash augmented quotas. In addition, each user has control of their batching strategy prior to delivery through the mail.i2p outproxies, which are separate from the mail.i2p SMTP and POP3 servers. Both the outproxies and inproxies communicate with the mail.i2p SMTP and POP3 servers through I2P itself, so compromising those non-anonymous locations does not give access to the mail accounts or activity patterns of the user. More information can be found on the I2P Site: hq.postman.i2p.xyz.


Developed by: jrandom, et al, ported from mjw’s Snark client.

Snark is an I2P network only BitTorrent client. It never makes a connection to a peer over any other network.

Static Site Template ( Web server)

A template that you can modify to set up your own self-hosted I2P site. The directions for accessing these files are included.

The Address Book

Developed by: mihi, Ragnarok.

This is a locally-defined list of human-readable addresses ( ie: i2p-projekt.i2p) and corresponding I2P addresses.(udhdrtrcetjm5sxzskjyr5ztpeszydbh4dpl3pl4utgqqw2v4jna.b32.i2p) It integrates with other applications to allow you to use those human-readable addresses in place of those I2P network addresses. It is more similar to a hosts file or a contact list than a network database or a DNS service. There is no recognized global namespace, you decide what any given .i2p domain maps too in the end.

The QR Code Generator

Besides the Address Book, I2P addresses can be shared by converting them into QR codes and scanning them with a camera. This is especially useful for Android devices.

The Hidden Services Manager

This is a general-purpose adapter for forwarding services ( ie SSH ) into the I2P network and proxying client requests to and from the I2P network. It provides a variety of “Tunnel Types” that are able to do advance filtering of traffic before it reaches I2P.

Some example use cases include:

Outproxy For Accessing Clearnet (Internet) Content and Services

To support compatibility with the clearnet ( Internet ) and also maintain a privacy workflow, the I2P Java software provides access to an outproxy. This service is provided by StormyCloud Inc. https://stormycloud.org/.

Configuration/ Diagnostics

Customize your I2P router here. This includes bandwidth settings, home page, and the overall look and feel of your router console UI. Privacy and security setting can be adjusted here as well, such as your tunnel hops. Add more plugins and reseed from a url in this section as well.

An example of what you can do:

Configure your router to be a Bitcoin Node https://geti2p.net/en/blog/post/2021/09/18/i2p-bitcoin

I2P Network Peers

NTCP, SSU and UPnP connection can be found here.

Want to make this guide better? Get in touch!



The Invisible Internet Project

The Invisible Internet is a privacy by design people-powered network. This blog has moved: https://theoverlay.ghost.io/