Torsen

A minimal system-wide Tor routing helper for Linux.

Torsen backs up your current network state, rewrites Tor configuration from a template, takes control of DNS, applies firewall rules, waits for Tor bootstrap, and restores everything cleanly when you disconnect.

✨ Features

System-wide traffic routing through Tor
Automatic iptables/ip6tables backup and restore
Automatic DNS takeover and recovery
Automatic torrc backup, templating, and restore
Waits for Tor bootstrap using the control port
Built-in status, verify, and recover commands
Editable Tor template with safe runtime placeholders
Persistent local state for clean rollback
Simple single-binary CLI

⚠️ Important Warning

Torsen modifies:

firewall rules
DNS configuration
Tor service configuration
system networking behavior

You should:

run it only on systems you understand
review the source before production use
test inside a VM or disposable machine first
always use verify before first connection

Root privileges are required.

🧠 How It Works

When you run torsen connect, the tool roughly does this:

Backs up current firewall rules
Stops local DNS-related services if needed
Backs up and replaces resolv.conf
Backs up your current torrc
Renders a Tor config from template
Restarts the Tor service
Waits until Tor bootstrap finishes
Applies firewall rules to route traffic through Tor
Stays active until you press Ctrl+C
Restores everything on disconnect

📦 Installation

Build

make build

The binary will be created at:

build/torsen

Install

sudo make install

This installs:

binary to /usr/local/bin/torsen
state directory at /var/lib/torsen
log directory at /var/log/torsen

Uninstall

sudo make uninstall

✅ Requirements

Torsen is designed for Linux systems with:

tor
iptables
iptables-save
iptables-restore
ip6tables
systemctl

Optional but useful:

obfs4proxy
nmcli

Check everything with:

sudo torsen verify

🚀 Quick Start

1) Verify your system

sudo torsen verify

2) Connect through Tor

sudo torsen connect

When the connection becomes active, Torsen will keep running in the foreground.

Press:

Ctrl+C

to disconnect and restore your original settings.

3) Check status

sudo torsen status

4) Disconnect manually

sudo torsen disconnect

5) Recover a broken or partial state

sudo torsen recover

🕹️ Commands

sudo torsen connect
sudo torsen disconnect
sudo torsen status
sudo torsen verify
sudo torsen recover
sudo torsen edit
sudo torsen reset-template

Command Summary

Command	Description
`connect`	Start Tor routing workflow and stay attached until interrupted
`disconnect`	Restore previous network and Tor state
`status`	Show current state of Tor, DNS, firewall, and internal state
`verify`	Check whether required system dependencies exist
`recover`	Force cleanup and restore the machine to a clean state
`edit`	Open the custom Tor template in your editor
`reset-template`	Restore the default embedded Tor template

⚙️ Configuration

Torsen reads configuration from:

.env
/etc/torsen/.env

It loads the first one that exists.

Example `.env`

TOR_USER=tor
TOR_CONTROL_PORT=9051
TOR_CONTROL_PASSWORD=change-this-password
TOR_BOOTSTRAP_TIMEOUT=120
SYSTEM_TORRC_PATH=/etc/tor/torrc

TOR_DNS_PORT=5353
TOR_DNS_IP=127.0.0.1
TOR_TRANSPARENT_PORT=9040
NON_TOR_NETWORKS=192.168.0.0/16 10.0.0.0/8 172.16.0.0/12

RESOLV_CONF_PATH=/etc/resolv.conf
DNS_SERVICE_NAME=

STATE_DIR=/var/lib/torsen
LOG_DIR=/var/log/torsen
LOG_LEVEL=info

Configuration Fields

Variable	Default	Description
`TOR_USER`	`tor`	System user used by Tor
`TOR_CONTROL_PORT`	`9051`	Tor control port
`TOR_CONTROL_PASSWORD`	`torsen2025`	Control password used at runtime
`TOR_BOOTSTRAP_TIMEOUT`	`120`	Bootstrap wait timeout in seconds
`SYSTEM_TORRC_PATH`	`/etc/tor/torrc`	Main Tor configuration path
`TOR_DNS_PORT`	`5353`	Tor DNS port
`TOR_DNS_IP`	`127.0.0.1`	DNS resolver IP written into `resolv.conf`
`TOR_TRANSPARENT_PORT`	`9040`	Transparent proxy port
`NON_TOR_NETWORKS`	private networks	CIDRs excluded from Tor redirection
`RESOLV_CONF_PATH`	`/etc/resolv.conf`	Path to system resolver file
`DNS_SERVICE_NAME`	empty	Optional DNS service to stop/restart explicitly
`STATE_DIR`	`/var/lib/torsen`	State and backup directory
`LOG_DIR`	`/var/log/torsen`	Log directory
`LOG_LEVEL`	`info`	Console log verbosity

Recommended: set your own strong TOR_CONTROL_PASSWORD.

🧩 Custom Tor Template

Torsen ships with an embedded torrc template and lets you override it locally.

Edit template

sudo torsen edit

Reset template back to default

sudo torsen reset-template

Runtime placeholders

These values are automatically replaced when the template is rendered:

{{TOR_USER}}
{{TOR_CONTROL_PORT}}
{{HASHED_CONTROL_PASSWORD}}
{{TOR_TRANSPARENT_PORT}}
{{TOR_DNS_PORT}}

You can safely customize things like:

bridges
pluggable transports
exit policies
logging
client behavior
performance tuning

🧪 Example Workflow

sudo torsen verify
sudo torsen edit
sudo torsen connect

In another terminal:

sudo torsen status

If anything looks inconsistent:

sudo torsen recover

📁 State and Logs

Torsen stores its working data here by default:

State

/var/lib/torsen

This may include:

state.json
iptables.v4.bak
ip6tables.v6.bak
resolv.conf.bak
torrc.bak
torrc.template

Logs

/var/log/torsen/torsen.log

🔎 Status Output

torsen status checks:

internal state file
Tor service activity
DNS hijack marker
Torsen firewall chains

Typical states:

CONNECTED through Tor
PARTIALLY CONNECTED
NOT CONNECTED

If you see a partial state, run:

sudo torsen recover

🛠 Troubleshooting

Tor does not bootstrap

Check:

your internet connection
bridge settings in the template
control port settings
whether Tor starts manually
firewall conflicts from other tools

Try:

systemctl status tor
journalctl -u tor -e

DNS does not restore correctly

Run:

sudo torsen recover

If your machine uses a custom resolver manager, set:

DNS_SERVICE_NAME=your-dns-service

Firewall looks broken after interruption

Run:

sudo torsen recover

Then verify:

sudo torsen status

🏗 Project Structure

.
├── cmd/torsen
├── internal/config
├── internal/dns
├── internal/firewall
├── internal/logger
├── internal/runner
├── internal/state
├── internal/tor
├── scripts
├── Makefile
└── go.mod

Internal Packages

Package	Responsibility
`config`	Reads `.env` and builds runtime config
`dns`	Takes over and restores system DNS
`firewall`	Backs up, applies, and restores iptables rules
`logger`	Console and file logging
`runner`	Command execution wrapper
`state`	Stores connection and backup metadata
`tor`	Manages torrc, service lifecycle, and bootstrap

🧭 Design Goals

Keep the CLI simple
Keep rollback easy and predictable
Prefer explicit system control over hidden magic
Stay hackable for custom Tor setups
Be useful for self-hosted and lab environments

❗ Limitations

Linux only
Requires root
Assumes systemctl is available
Assumes an iptables-compatible environment
Not intended for mobile or desktop portability without adaptation
Not a replacement for a full security audit

🤝 Contributing

Contributions are welcome.

If you want to improve Torsen, useful areas include:

tests
nftables support
safer restore paths
stronger defaults
packaging for distributions
CI workflows
docs and examples

Feel free to open:

issues
feature requests
pull requests

📜 License

This project is open-source and available under the GNU AGPLv3 License.

Thanks for visiting! ☕

Name		Name	Last commit message	Last commit date
src		src
LICENSE		LICENSE
README.md		README.md
default-torrc.txt		default-torrc.txt

Latest commit

History

Folders and files

Repository files navigation