I2P Node Administration: Complete Guide to I2Pd Router Setup and Management

By Jasper MonroeLinux Commands

Introduction to I2P and Node Administration

I2P (Invisible Internet Project) is an open-source, peer-to-peer network designed with anonymity as its core principle. The network consists of two main entities: routers and endpoints. A router is a software client that must be installed to use I2P. By default, the router publishes real IP addresses and actively interacts with other routers, acting as a transit node and expanding its network map by accumulating information about other available routers for use in its tunnels. An endpoint is a meaningful network entity that performs hidden activities, such as a hidden website or a user’s outbound proxy. The anonymity of I2P is based on the secrecy of endpoint locations: identifying the router that is the parent of an endpoint is extremely difficult, and with proper administration, impossible.

This guide focuses on administering the router, i.e., understanding the configuration of a typical node that ensures the hidden network’s operation.

Installing I2Pd

I2Pd (Invisible Internet Protocol Daemon) is a router developed mainly by the Russian-speaking PurpleI2P community since 2013. Written in C++, it uses OpenSSL and Boost libraries. I2Pd is cross-platform, with binaries available for Windows, Linux, MacOS, and Android. Manual compilation is possible for other operating systems as well. While I2Pd is available in some Linux distributions’ standard repositories, it’s recommended to use the community repository for the latest version.

Administration is nearly identical across platforms: the main source of information about router activity is the web console at http://127.0.0.1:7070.

Web Console: Main Page Overview

  • Uptime – Time since the router started.
  • Network status – Shows the router’s network status. Since version 2.37.0, Network status 6 displays IPv6 interface status. Possible values:
    • Testing: Testing network capabilities.
    • OK: Router is operating normally and accessible via TCP and UDP. Usually appears when the I2Pd port is open and the IP is globally accessible (dedicated or port-forwarded via NAT).
    • Firewalled: Indicates the UDP port is inaccessible from outside, often due to firewall or NAT. Common for users behind mobile carriers or without a dedicated IP.
    • Proxy: Router is working through a proxy (NTCP2 only; SSU does not work via proxy). Configured manually.
    • Mesh: Router operates exclusively via a mesh network (e.g., Yggdrasil Network), bypassing the regular internet.
    • Unknown: No SSU traffic, and configuration doesn’t match Proxy or Mesh indicators.
  • Tunnel creation success rate – Percentage of successfully built tunnels (typically 20–50%).
  • Received/Sent – Amount of data received/sent since startup (current speed in parentheses).
  • Transit – Volume and current speed of transit traffic.
  • Data path – Working directory where keys and the local network database are stored.

I2Pd supports portable mode, storing all necessary files in one directory next to the executable. If “i2pd.conf” is present, I2Pd runs in portable mode.

Hidden content. Press on text to see – Spoiler with sensitive router info (hidden by default). Shows IP addresses by protocol (SSU, SSUv6, NTCP2, NTCP2v6), and the cryptographic router name (Router Ident) derived from the public “router.keys” key.

The Our external address section displays the router’s external IPs and working port. The port is randomly generated at first launch and saved in “router.info”. You can set a random port manually. If you see a local address or zeros, the port is closed by a firewall or your IP is not externally accessible. For SSU behind NAT (e.g., USB modem), the router’s external address will show the provider’s NAT server and the port currently assigned to you (Hole punch).

Router Caps (Flags)

Router Caps are special markers published by the router to inform others about its capabilities. Common flags:

  • f: Floodfill – router is a floodfill node.
  • H: Hidden – router does not publish its IPs.
  • K/L/M/N/O/P/X: Transit bandwidth limits (from 12KB/s up to 2000KB/s+).
  • R: Reachable – router is externally accessible.
  • U: Unreachable – router is not externally accessible.

Flags R and U are for compatibility with the legacy Java router; I2Pd uses similar flags in Router Info (RI) for each IP address.

Router Info is the information the router publishes about itself, including keys, flags, and IPs. The “router.info” file is generated after each state change and stored in the Data path.

  • 4: Hidden IPv4 address.
  • 6: Hidden IPv6 address.
  • B: SSU address handles peer tests.
  • C: Address can be an introducer (for connecting to hidden nodes).

Other Key Metrics

  • Routers: Number of known routers in the local database.
  • Floodfills: Number of floodfill routers in the local database.
  • LeaseSets: Number of local LeaseSets (info packets for connecting to hidden resources).
  • Client Tunnels: Number of tunnels built and used by the local router.
  • Transit Tunnels: Number of transit tunnels the router is currently part of.

Services Section

  • HTTP Proxy: User HTTP proxy for accessing the hidden network (default: 127.0.0.1:4444).
  • SOCKS Proxy: User SOCKS proxy (default: 127.0.0.1:4447).
  • BOB (Basic Open Bridge): Interface for applications to create dynamic tunnels. Supported and updated in I2Pd.
  • SAM (Simple Anonymous Messaging): Another interface for dynamic tunnels, equivalent to BOB in I2Pd.
  • I2CP (I2P Control Protocol): Protocol for external programs to interact with the router. In I2Pd, client data is handled internally for better control and performance.
  • I2PControl: Protocol for querying router status in JSON (rarely used).

Web Console: Router Commands

  • Run peer test: Check router accessibility (useful if the port was closed at startup and status is “Firewalled”).
  • Decline transit tunnels: Reject new transit tunnels (existing ones remain). Useful for analyzing server activity while keeping hidden services operational.
  • Start graceful shutdown: Begin a 10-minute shutdown period, allowing existing tunnels to close cleanly.
  • Force shutdown: Immediate router shutdown.
  • Logging level: Change log verbosity (none, error, warn, info, debug).
  • Transit tunnels limit: Set the maximum number of transit tunnels (default: 2500).

Web Console: Local Destinations

Lists endpoints hosted on the router. Each address is formed by a unique key, but multiple tunnels can use the same key. For detailed analysis, use the “I2P tunnels” section. Click an endpoint name for more info.

  • Base64: Full endpoint address in base64 (includes public encryption and signing keys).
  • Address registration line: String for registering a domain on reg.i2p or stats.i2p, linking it to the current key.
  • LeaseSets: Number of known LeaseSets for the endpoint (usually users the hidden service is communicating with).
  • Inbound/Outbound tunnels: Number of incoming/outgoing tunnels (max 16 each; default is 5 for server endpoints, 3 for clients). Multiple tunnels increase availability and complicate traffic analysis.
  • Tags: List of addresses with which the endpoint used one-time cryptographic keys (“tags”).

ElGamal is a resource-intensive, outdated encryption algorithm, being replaced by the faster ECIES-X25519-AEAD-Ratchet protocol. In the new protocol, keys are derived locally and not transmitted over the network.

  • Incoming Tags: Number of precomputed tags for future use.
  • Tags sessions: Number of sessions and addresses with established tags.
  • Status: Session state (4 = “Established”).

Streams are active TCP sessions between external applications and I2P via the local router. Each stream has an ID, destination, sent/received data, RTT, window size, buffer, and status (1 = open).

Packet sizes: 1730 bytes for ElGamal, 1812 bytes for ECIES-X25519-AEAD-Ratchet.

For a better understanding of I2P’s network architecture (protocol stack, crypto transports, tunnels), refer to the OSI-like model illustration in the original article.

Transit tunnels operate at the second layer, using minimal router resources. Standard 2500 transit tunnels do not overload even single-board computers. Floodfill operation is more resource-intensive due to end-to-end encryption.

Web Console: LeaseSets

Relevant for routers acting as floodfills. Shows LeaseSets published by hidden resources (anonymous endpoints). Each LeaseSet includes the entry tunnel info and expiration (about 10 minutes). Encrypted LeaseSets also exist and are not easily analyzed.

Web Console: Tunnels / Transit Tunnels

The Tunnels tab shows all incoming and outgoing tunnels initiated by the router. Exploratory tunnels are built automatically for network exploration and have low traffic. Transit tunnels shows only transit tunnels; information is minimal, as all I2P tunnels are unidirectional and the transit router only knows where to receive and forward packets.

Web Console: Transports

Displays direct connections with other routers, showing the number of connections per protocol (NTCP2, NTCP2v6, SSU, SSUv6) and the amount of data sent/received.

Web Console: I2P Tunnels

Similar to “Local destinations” but more practical, allowing analysis of each tunnel individually, even if multiple tunnels use the same key. Tunnel names are taken from their config files. Three types are shown: client, server, and Server Forwards (UDP tunnels).

Web Console: SAM Sessions

Lists external application sessions with the router via the SAM protocol. Click a session to see its external I2P address and local connections. BOB protocol could have a similar interface, but it’s less popular and not present in the web console.

For app development, it’s best to use the SAM protocol API for compatibility with Java router users.

Connecting to a Remote Router’s Web Console

I2Pd’s web console supports configuration for external access and user authentication. However, exposing the web console over the regular internet without extra encryption (HTTPS) is risky. The safest method is to connect via SSH with port forwarding. SSH provides built-in encryption and is widely used.

To forward a local port to a remote machine, use:
ssh -D 8888 user@<server ip> -p <ssh port>

This allows you to connect your browser to the SOCKS proxy at 127.0.0.1:8888, access the global internet from the server’s IP, and reach local resources on the remote machine, including the I2P router’s web console at 127.0.0.1:7070.

Configuration File

While the router can accept command-line parameters, it’s common to use a configuration file. On Debian, after package installation, i2pd.conf is in /etc/i2pd/. For manual binary launches, it’s read from ~/.i2pd/. On Android, all files are in /sdcard/i2pd/. On Windows, the default directory is %AppData%\i2pd.

Config files are mostly the same across OSes, with minor differences (see official documentation). A standard config with comments is in the contrib folder in the source or installed package.

Two syntax styles are supported:

  • Section in square brackets, with parameters listed below.
  • Parameter specified as section.parameter.

Default parameters (mainly when running without a config file):

  • Web console enabled at http://127.0.0.1:7070
  • HTTP proxy enabled at 127.0.0.1:4444
  • SOCKS proxy enabled at 127.0.0.1:4447
  • SAM enabled at 127.0.0.1:7656
  • Daemon mode active
  • Logging at “warn” level
  • IPv4 enabled, IPv6 disabled
  • Other parameters are inactive by default

Notable config options:

  • family: An identifier to prevent routers from the same admin from appearing in the same tunnel. Rarely used.
  • [reseed]: Parameters for obtaining the initial router set (reseeds) to join the I2P network.
    • verify: Signature verification for reseeds (default: off, but “true” in standard config). Requires certificates; otherwise, the router won’t start.
    • urls: URLs to download reseeds from (e.g., https://example.ru/).
    • yggurls: IPv6 Yggdrasil addresses for reseeds (http, not https).
    • file: Path to a local .su3 file or direct https link.
    • zipfile: Path to a local zip archive or direct https link.
    • proxy: Proxy used for reseed requests.
    • threshold: Minimum known routers before reseeding (default: 25).
  • [persist]: Controls saving dynamic info to disk.
    • profiles: Saves router profiles for next launch (quality of interaction with routers).
    • addressbook: Saves full addresses; disabling reduces disk load.

Conclusion

This article omits some OS-level technical details, focusing on I2P router management rather than basic system administration. Don’t forget about the --help function built into the router and the official documentation—these tools will assist you in practical configuration.

Leave a Reply