Nipe: routing all your traffic through Tor with iptables

What Nipe is for, and who ends up running it

Tor ships a SOCKS proxy, and most applications will not use it unless you configure each one. Nipe takes the other route: it makes Tor the default gateway of the whole machine. The README describes it as an engine, developed in Perl, that aims at making the Tor network your default network gateway, so traffic from the host reaches the Internet through Tor without per-application configuration. The audience that follows from that is narrow and specific. People who need a shell, a browser and a command line tool to all leave through the same circuit, without editing each tool's proxy settings. Analysts running a throwaway virtual machine. Anyone testing how a service behaves when it sees a Tor exit node. Nipe is not a browser add-on and it is not a Tor Browser replacement; it operates at the network layer, below everything that opens a socket.

How the redirection actually happens

The mechanism is rule rewriting, not a proxy client. According to the README, Nipe uses iptables and ip6tables to apply redirection rules for IPv4 and IPv6 traffic respectively. The Tor process itself listens locally, and the rules send outbound traffic to it. Only traffic destined for local and loopback addresses stays outside the tunnel. The README also states that all non-local UDP and ICMP traffic is blocked by the Tor project, which is a consequence of Tor carrying TCP streams: DNS over UDP and ping will not work through the tunnel, and applications that depend on them will fail rather than silently leak. The Dockerfile confirms the local endpoints. It writes a torrc fragment containing SocksPort 0.0.0.0:9050 and ControlPort 0.0.0.0:9061, and exposes those two ports. The control port matters because the restart command is described as restarting the Nipe circuit, which is the operation that asks Tor for a new set of relays.

Installing Nipe and starting the first circuit

The README gives a three-step install. Clone the repository, install the Perl dependencies with cpanm, then run the install command as root. The install step is a subcommand of the script itself, not a separate installer.

# Download
$ git clone https://github.com/htrgouvea/nipe && cd nipe

# Install libs and dependencies
$ cpanm --installdeps .

# Nipe must be run as root
$ perl nipe.pl install

After that, the routing lifecycle is five subcommands: install, start, stop, restart and status. The README lists them with the note that start begins routing and status reports the current state.

perl nipe.pl start
perl nipe.pl status

A reasonable first check is to run status, confirm routing is on, then query an external service that echoes your address and compare it against your normal one. The README does not document a built-in verification command, so that comparison is on you.

There is also a container path. The Dockerfile is based on debian:bookworm-slim and installs tor, iptables, cpanminus and the Perl SSL libraries. The README's build and run commands require privileged mode and the NET_ADMIN capability, because the container writes firewall rules.

docker build -t nipe .
docker run -d -it --name nipe-container --privileged --cap-add=NET_ADMIN nipe
docker exec -it nipe-container ./nipe.pl <your command>

The container's entrypoint is /bin/bash, so the exec form is how you reach the script inside a running container.

The stop command is the real risk

The README is unusually direct about this, and it deserves to be quoted rather than paraphrased: if you already have rules applied to iptables or ip6tables, conflicts may occur during the start process, and when you stop the Nipe services, all departure rules are removed, not differentiating between the already existing ones and the Nipe rules. Read that as a data-loss statement for firewall configuration. If the host has hand-written NAT rules, port forwards or container networking rules, a single stop can wipe them. Recovery means reapplying them from whatever source of truth you keep outside the machine. The start path carries its own conflict risk, since Nipe appends to a chain it does not own. The practical consequence is that Nipe belongs on a machine whose firewall state is disposable: a fresh VM, a container, or a host where you can rebuild the ruleset from a config management system. On a shared server, or on a laptop where you have accumulated rules over months, the stop command is the wrong tool. The README does not document a rollback or a backup of the previous ruleset, so treat the current state as unrecoverable unless you saved it yourself.

Nipe against running Tor as a SOCKS proxy

The obvious alternative is not another routing engine; it is Tor's own proxy mode. Tor already exposes a SOCKS listener, and the Dockerfile shows Nipe's own container using SocksPort 0.0.0.0:9050. With that approach you leave the firewall alone, point individual applications at the proxy, and stop worrying about what happens when the tool exits. The trade-off is coverage. A SOCKS proxy only captures applications that honor it, and anything that ignores proxy settings, or opens a raw socket, bypasses it. Nipe's iptables approach captures everything at the network layer, which is exactly why it needs root and exactly why its cleanup is destructive. The two are not equivalent in failure modes either. A misconfigured SOCKS client leaks traffic silently. A misconfigured Nipe ruleset can take the host off the network or erase rules you needed. Pick based on whether you value per-application control or whole-machine coverage, and whether the host's firewall state is something you can afford to lose.

Maintenance, licensing and what the repository shows

The last push to the repository was on 2026-09-13, so the code is recent. The README carries a version badge reading 0.9.8, and no release information was retrieved, which suggests you should expect to track the main branch rather than pin a tagged release. The CI badges in the README reference a linter workflow, a zarn workflow, a security gate and a test run on Ubuntu, so the project does check itself on at least one platform, but the README does not say which Perl versions or which distributions are covered beyond that. The upgrade cost is low in code terms, since the install path is cpanm --installdeps . against a cpanfile, but every upgrade can change the iptables rules that get written, and that is the part worth reviewing before you roll it out. On licensing there is a real discrepancy: the repository metadata reports NOASSERTION, while the README shows an MIT badge and links to a LICENSE.md file. The README's license section states the work is licensed under the MIT License. If you need a definite answer for redistribution, read LICENSE.md directly rather than trusting either the badge or the metadata. This is not legal advice.

Editorial conclusion

Nipe fits engineers who want a whole-machine Tor gateway on a disposable VM, a container or a lab host, and who accept that the stop command flushes every NAT rule on that machine. Do not run it on a workstation or server that already carries hand-written iptables rules, because the README states the removal step does not distinguish Nipe's rules from yours. Before adopting it, read the source that implements start and stop and confirm how it snapshots and restores the ruleset, then verify the license file, since the repository carries a NOASSERTION identifier while the README points at an MIT badge.

Frequently asked questions

Official sources

1. htrgouvea/nipe on GitHub
2. Issues
3. Project website
4. README