No description
  • Shell 83.1%
  • Python 14.9%
  • Dockerfile 1%
  • Makefile 1%
Find a file
LowEel 1abff552a5
Some checks reported errors
continuous-integration/drone/tag Build was killed
narnia 0.99-beta2: every node on the circuit's port, udp, for hole punching
Members take the port the master chose and their host files say it. With
ufw or firewalld active, the master opens it tcp and udp and lets the
circuit's interface in; members open it udp only; clean closes only what
narnia opened. The Docker test runs on port 7000 with ufw on the master and
alice, and checks that alice reaches bob directly.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 21:03:53 +01:00
changelog narnia 0.99-beta2: every node on the circuit's port, udp, for hole punching 2026-11-22 21:03:53 +01:00
packaging narnia 0.99-beta 2026-11-22 16:38:32 +01:00
sbin narnia 0.99-beta2: every node on the circuit's port, udp, for hole punching 2026-11-22 21:03:53 +01:00
test narnia 0.99-beta2: every node on the circuit's port, udp, for hole punching 2026-11-22 21:03:53 +01:00
tools narnia 0.99-beta 2026-11-22 16:38:32 +01:00
.drone.yml narnia 0.99-beta 2026-11-22 16:38:32 +01:00
.gitignore narnia 0.99-beta 2026-11-22 16:38:32 +01:00
LICENSE narnia 0.99-beta 2026-11-22 16:38:32 +01:00
Makefile narnia 0.99-beta2: every node on the circuit's port, udp, for hole punching 2026-11-22 21:03:53 +01:00
README.md narnia 0.99-beta2: every node on the circuit's port, udp, for hole punching 2026-11-22 21:03:53 +01:00
README_IT.md narnia 0.99-beta2: every node on the circuit's port, udp, for hole punching 2026-11-22 21:03:53 +01:00

Narnia

Leggi in italiano

The idea for Narnia comes from this post: https://keinpfusch.net/e-possibile-farsi-una-darknet-privata/

A small private network for a group of people: friends, an association, a hackerspace, a family spread over several homes. One computer is the central node (the master) and decides everything; the others, the members, join with a file the master hands them.

Inside the network everyone sees each other as on a home LAN: each machine has an address and a name (alice.narnia, square.narnia), and members can offer services to each other without going through the internet.

What it is

  • An encrypted overlay network built with tinc, in switch mode (layer 2): every machine gets a narnia0 interface that behaves like a network card plugged into the same switch.
  • The master hands out addresses and names with dnsmasq: each member always has the same address and the same name, chosen by the master.
  • Members sync every hour with the master (read-only rsync, inside the network): whoever is added or removed is added or removed for everyone within an hour.
  • The network's name is up to you: a circuit called eternia gets the interface eternia0 and names like foo.eternia.
  • Addresses live in the carrier-grade NAT space 100.64.0.0/10, which does not clash with home networks (192.168.x, 10.x).

What problems it solves

  • No one else's platform. To talk, share files or publish something among a few people you need no third-party servers: the network is yours, with your rules.
  • No third-party services at runtime. Once installed, Narnia needs no registry, update server or outside DNS: the nodes talk to each other over the internet, encrypted.
  • Reachability. Members behind NAT or with a dynamic IP can still be reached: the master only needs a static IP or a DDNS name.
  • Names. No addresses to remember: the master names every member, and can invent more names for services (git.narnia, square.narnia).
  • Simple control. Letting someone in is one command; throwing them out is another.
  • Your browsing stays yours. The network is not a gateway: members' internet traffic never passes through the master, and the master only ever receives DNS queries for the network's own names (*.narnia), never others.

What it is NOT

Narnia is not a full darknet, and must not be used as one.

  • It does not make you anonymous. Connected members see your real IP; your provider sees that you use tinc, and towards which address.
  • It does not protect you from other members. Inside the network you trust each other as on a home LAN: a member can forge a MAC address or try to disturb the others. Narnia blocks rogue DHCP servers, not everything else.
  • It does not protect you from the administrator. The master decides who gets in, and generates the members' keys itself: it therefore knows their private keys and can impersonate any of them. Joining Narnia means trusting whoever runs it.
  • It is not Tor or I2P. If you need anonymity, use those.
  • A removed member stays known to the other nodes until their next sync, that is for at most an hour.

Supported systems

Debian 13, Ubuntu 24.04 and their derivatives (.deb); Fedora, openSUSE Tumbleweed and Leap 16 (.rpm). Not openSUSE Leap 15, which lacks dhcpcd.

Ports

Where Port Direction Why
master 655 TCP and UDP open to the internet members connect here; TCP carries the control channel, UDP the traffic
member 655 UDP, never TCP open, without touching the router other members talk to it directly instead of through the master

655 is tinc's default; choose another with narnia circuit -P PORT, and members use their circuit's.

On the master the port must be open in every firewall in front of it: the router's port forwarding at home, the provider's firewall on a VPS. The machine's own is opened by narnia circuit when ufw or firewalld is active, which also lets narnia0 in, where Narnia's own rules still allow only DHCP, DNS, rsync and ping.

On members narnia join opens the port, UDP only, in the machine's firewall when ufw or firewalld is active. Nothing is needed on the home router: tinc sends from that very port, and almost every router, seeing UDP go out of a port, leaves it open inbound for whoever it was sent to (UDP hole punching). Almost every, not every: behind some carrier NATs the hole does not open, and traffic to that member then goes through the master. It still works, only slower.

narnia clean closes what Narnia opened and nothing else: a port you had opened yourself stays open.

Installing the central node (master)

You need an always-on machine with a static public IP or a DDNS name, and port 655 TCP and UDP open towards it (see Ports).

  1. Install the create-initial-node package (.deb or .rpm) from the repository's Releases page. It brings tinc, dnsmasq, rsync, nftables and the narnia command.

  2. Create the circuit:

    sudo narnia circuit
    

    It asks for the circuit's name (e.g. narnia), proposes a random network inside 100.64.0.0/10 (press Enter to accept it) and asks for the machine's public address. The master takes the network's first address and the name master.narnia.

  3. Let a member in:

    sudo narnia node alice
    

    This writes a file narnia-alice.narnia. It contains the member's private key: hand it over through a safe channel (in person, on a USB stick, encrypted) and then delete it.

  4. Other commands:

    sudo narnia list          # who is in
    sudo narnia drop alice    # throw alice out
    sudo narnia clean         # remove the circuit from this machine
    

On narnia0 the master accepts only DHCP, DNS, rsync and ping, and forwards nothing between the network and the rest of the world.

Installing a member node

  1. Install the join-narnia package (.deb or .rpm) from the repository's Releases page. It brings tinc, rsync, dhcpcd, nftables, cron and the narnia command.

  2. Join with the file you got from the master:

    sudo narnia join narnia-alice.narnia
    

    Narnia checks that the circuit's network does not clash with addresses the machine already has (this happens with some carrier-NAT providers and with Tailscale), starts tinc, gets its address and name from the master, and schedules the hourly sync.

  3. For *.narnia names you need systemd-resolved running: it already is on Ubuntu and Fedora. On Debian and openSUSE install and enable it; otherwise the network still works, but by address only.

  4. To leave: sudo narnia clean.

Tests

test/run.sh sets up a master and two members in Docker containers, on an internal network with no way out, and checks addresses, names, syncing and the removal of a member. It does not touch the network of the machine it runs on.

Licence

EUPL-1.2.