sam/i2pforge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
Page: troubleshooting
Pages
Home backing up your key encrypt at rest faq how it works operator runbook opsec mistakes running multiple tunnels the installer troubleshooting verifying your setup
1 troubleshooting
Sam Bent edited this page 2026-07-17 15:15:52 -04:00
Table of Contents

Troubleshooting

Most problems fall into a few buckets. Work down this page in order.

No address appears

You started the container but docker logs never prints an address, and ./i2p-keys/eepsite.b32.i2p never shows up.

First, confirm the container is actually running and not restarting in a loop:

docker ps
docker logs <container> 2>&1 | tail -30

Common causes:

  • The backend name does not resolve. i2pforge resolves your backend to an IP at startup. If you pointed it at web:80 but there is no container called web on the same Docker network, it logs a resolution error and skips the tunnel. Put both containers on the same network, or use an IP address.
  • A bad service variable. If a *_I2P_SERVICE_HOSTS value is malformed, i2pforge logs Skipping ... and moves on. Check the log for that word.
  • First boot just needs time. Building tunnels on a fresh, constrained network can take a minute or two. Give it 60 to 90 seconds before worrying.

The address exists but the service is unreachable

You have an address, but visitors cannot load it over I2P.

  • The leaseset is still publishing. After the address appears, i2pd still has to announce it to the network. Wait a couple of minutes and try again.

  • The visitor's I2P client is slow to find it. New destinations take a little time to become widely reachable. This is normal for I2P.

  • The backend is down. Confirm the tunnel target actually answers from inside the container:

    docker exec <container> sh -c 'wget -qO- http://web:80/ | head'

    If that fails, the problem is your backend, not i2pforge.

The container refuses to start

i2pforge fails fast on purpose when something is wrong with the key folder, rather than run in a broken state.

  • A truncated or corrupt key. If a .dat file is too small or damaged, it refuses to boot and tells you which file. Delete that file to force a fresh key, or restore a good copy from backup.
  • An encrypted key with no passphrase. If the folder has an eepsite.dat.i2pfk1 but you did not mount a passphrase, it stops and says so. Mount the passphrase file.
  • A symlink where a key should be. If a key file is a symlink, it refuses to touch it and stops. A real key is never a symlink, so this means something tampered with the folder.

Checking the hardening is intact

If you want to confirm the running container still has every security flag on:

./scripts/i2pforge doctor --container <name>

It checks the capability set, the read-only filesystem, no-new-privileges, and that no ports are exposed. Anything red is a misconfiguration to fix.

Permissions on the key files

After the container runs, the key folder is owned by the in-container user, so you may need sudo to read the files from the host. This is expected. The public eepsite.b32.i2p is world-readable; the secret eepsite.dat is not.