What's this guide about?

This guide is intended to help IRC network admins to make their network accessible inside I2P. For many IRC networks on the normal internet, enabling secure, anonymous access for their users is very difficult, when also weighing up the requirement that users can still be managed and protected. The usual method for anonymously accessing an IRC network is through a proxy or Tor. However, this results in many users connecting from the same IP address, which poses a problem for IRC opers trying to prevent abuse of the network. In nearly every case, IRC networks just ban connections from common proxies and known Tor exit nodes.

By connecting their network directly to I2P, network admins can provide their users with the ability to connect anonymously to their IRC network, while still being able to manage users individually and control or block abusers. This is because client connections are uniquely identifiable by their cryptographic key, but the anonymity of the user is still protected due to the inherent nature of the I2P network.

How does it work?

The magic happens via the webirc protocol, which is normally used for creating IRC clients in web browsers. An I2P router is set up with a single server tunnel pointing at the IRCd server, through which all I2P users will connect. This means that the IRCd server will see all the users appearing from the same IP address (e.g. if the I2P router and IRCd server are running on the same machine), but by using the webirc protocol, the I2P router can pass to the IRCd server the cryptographic hash of the client connection as the user's hostname.

On the IRCd server side, this is the exact same way that a network admin would set up a web client like Mibbit for connecting to their server. However, web clients like Mibbit cannot be used anonymously as they employ JavaScript in the browser, which opens up the possibility for determining the real IP of the user, and thus requires the user to "trust" the provider of the web client. With an I2P interface, there is no such trust requirement, as the presence of the I2P network by design prevents the server from learning the user's IP address, only their unique cryptographic hash.

Okay, so what do I do?

Setting up an I2P tunnel for an IRC network is very simple.

  1. Have an IRC server somewhere (obviously).
    • It can be a good idea to have a separate IRC server in your network just for I2P users, as this server can then be customized a bit to improve their security (for example, ignoring any and all DCC messages), but this is not required.
  2. Configure the IRC server to have a(nother) webirc listener.
    • This webirc listener should be listening on a local port (
    • There is a lot of information on how to set up webirc for different IRCd programs on the Mibbit wiki, but in essence you add a webirc or CGI:IRC block to your server configuration file, with the hostname as and some password APASSWORD.
  3. Install I2P somewhere.
    • You can run this on the same server as the IRCd process, or a different server. All that is required is that a connection can be made from the computer that I2P is installed on to the webirc listener set up above (whether locally, via an SSH tunnel, or through a VPN).
    • If you want to also make a website or other services available on I2P, that can be done with the one router (or multiple routers if you have multiple servers available with bandwidth to spare ^_^ ). However, if the I2P router is solely for the IRC server, then several features can be disabled and several options tweaked in order to reduce the footprint of the router:
      • (list of options and tweaks to go here, e.g. disabling Jetty, SAM/BOB, SusiMail)
  4. Set up an I2P server tunnel. This is done via the I2PTunnel configuration page in the router console. Under "I2P Server Tunnels" create a new server tunnel of type IRC, and configure it as follows:
    • Name: whatever you want.
    • Description: whatever you want.
    • Auto start: probably yes.
    • Target: host and port should be whatever your IRCd's webirc or CGI:IRC block is listening on.
    • Private key file: This is where the identifier for your tunnel is kept. If you want to give your tunnel a domain name (e.g. irc.example.i2p) then this file is VERY IMPORTANT to back up (if lost, you lose access to the domain name pointing at it). Any path here is relative to your I2P data dir (e.g. usually ~/.i2p on GNU/Linux), and at this point you can change the filename or path to make it easier to identify the file when you go to back it up.
    • Custom options:
      ircserver.method=webirc ircserver.webircPassword=APASSWORD ircserver.fakeHostname=%f.b32.i2p
      • APASSWORD is the same as the password set up in the IRCd's webirc block.
      • %f gets replaced by the full B32 destination hash of the connecting user's IRC client tunnel. If you wish to cloak this so the IRC server does not see it, replace this with %c which is a cloaked hash of the B32.
    • Other "Advanced networking options": any ideas here? Defaults fine?
  5. Publicise the tunnel.
    • On the main I2PTunnel page, under "I2P Server Tunnels" you will find the tunnel you just set up, and there will be a B32 address given there. By giving people this address (with ".b32.i2p" added on the end) they can already connect to your tunnel by creating a new IRC client tunnel on their router (and copying the general configuration settings of the default IRC client tunnel that comes with the router).
    • If you wish to give people a domain name to use in their IRC client tunnel configuration instead, then register the tunnel at e.g. stats.i2p or inr.i2p and wait a few days before giving people the domain name to use.

And that's it! You should now have a working I2P tunnel to your IRC server, and users connecting over it should have individual hostnames rather than all appearing from the same IP.