System-wide transparent Tor proxy and Portage sync over Tor. https://lainos.net
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-16 17:11:33 -07:00
lainos-private-sync add private-sync 2026-11-16 17:11:33 -07:00
lainos-private-sync.sh add private-sync 2026-11-16 17:11:33 -07:00
make.conf.example add private-sync 2026-11-16 17:11:33 -07:00
README.md add private-sync 2026-11-16 17:11:33 -07:00

lainos-private-sync

Fail-closed system-wide transparent proxying through Tor for LainOS. Designed for integration with private-mode.

Overview

This package provides kernel-level traffic enforcement to ensure all outbound network traffic is routed through Tor's transparent proxy, eliminating clearnet leaks. While it protects the entire system (including web browsers and background services), it also provides intelligent, fail-closed safety wrappers specifically for package management. It consists of two components:

  1. /usr/sbin/lainos-private-sync - An nftables firewall script that intercepts and forces all system-wide TCP and DNS traffic through Tor's TransPort (9040) and DNSPort (9059).
  2. /etc/profile.d/lainos-private-sync.sh - Shell wrapper functions (demerge, drepo) that enforce a two-tier safety check: they prefer routing via the active kernel firewall, but will safely fall back to a scoped Tor SocksPort proxy if the firewall is inactive, refusing to run only if neither is available.

Architecture

The firewall operates at the kernel level using nftables NAT rules. When active:

  • All outbound system-wide TCP traffic is redirected to Tor's TransPort (127.0.0.1:9040)
  • All DNS queries (UDP port 53) are redirected to Tor's DNSPort (127.0.0.1:9059)
  • Tor's own traffic is exempted to prevent routing loops
  • Localhost traffic is allowed directly
  • IPv6 traffic is blocked to prevent leaks

The demerge and drepo functions act as intelligent safety checks for system updates. They operate on a two-tier logic:

  1. Tier 1 (Preferred): If the kernel firewall is active, the command runs normally, and the kernel handles transparent routing.
  2. Tier 2 (Fallback): If the firewall is inactive but the Tor daemon is running, the wrapper injects scoped socks5h:// proxy variables only for that specific execution. The h ensures DNS resolution is also forced through Tor, preventing DNS leaks.
  3. Fail-Closed: If neither the firewall nor Tor is active, the command refuses to execute, preventing accidental clearnet updates.

Usage

Flexible Workflow

Option A: Full System Anonymity (Recommended for sensitive work)

# Activate private mode (starts Tor, randomizes MAC, enables firewall)
doas private-mode on

# Sync Portage through Tor (routes via kernel TransPort)
demerge --sync

# Deactivate private mode (stops Tor, restores DNS, disables firewall)
doas private-mode off

Option B: Tor-Only Sync (Clearnet browsing remains unaffected)

# Start the Tor daemon manually
torctl s

# Sync Portage through Tor (routes via scoped SocksPort 9050 proxy)
demerge --sync

Manual Firewall Control

The firewall is automatically managed by private-mode. Manual control is not recommended, but available:

# Check firewall status
doas lainos-private-sync status

# Manually activate firewall (requires Tor to be running with TransPort/DNSPort)
doas lainos-private-sync on

# Manually deactivate firewall
doas lainos-private-sync off

Requirements

Kernel Configuration

The following kernel options must be enabled:

CONFIG_NF_CONNTRACK=y
CONFIG_NF_NAT=y
CONFIG_NF_TABLES=y
CONFIG_NF_TABLES_INET=y
CONFIG_NFT_CT=y
CONFIG_NFT_META=y
CONFIG_NFT_REDIR=y
CONFIG_NFT_NAT=y

If these are missing, the firewall will be skipped with a warning, and demerge/drepo will fall back to the Tier 2 SocksPort proxy (or refuse to run if Tor is also down).

Tor Configuration

Tor must be configured with transparent proxy ports in /etc/tor/torrc (required for private-mode):

TransPort 127.0.0.1:9040 IsolateDestAddr IsolateDestPort
DNSPort 127.0.0.1:9059 IsolateDestAddr IsolateDestPort
AutomapHostsOnResolve 1

Verification

Check Firewall Status

doas lainos-private-sync status

Expected output when active:

[+] firewall: ON
[+] Tor SocksPort 9050: UP
[+] Tor TransPort 9040: UP

Verify Traffic Routing

Watch packet counters in real-time:

doas watch -n 1 "nft list table ip lainos_private_sync_nat"

In another terminal, run demerge --sync or open a web browser. You should see the redirect to :9040 and redirect to :9059 counters increasing, proving the kernel is intercepting and redirecting traffic.

Fail-Closed Test

Stop Tor while the firewall is active:

doas rc-service tor stop
demerge --sync

This should fail immediately with connection errors, proving the firewall cannot bypass Tor to reach the clearnet.

Security Model

This package implements a fail-closed security model:

  1. The kernel firewall is the primary source of truth for system-wide traffic routing.
  2. Shell wrappers enforce a two-tier safety check: they prefer the kernel firewall, but safely fall back to scoped socks5h:// proxying if Tor is running, preventing shell environment leaks.
  3. If neither the firewall nor Tor is active, system updates are strictly blocked to prevent clearnet leaks.
  4. IPv6 is completely blocked by the firewall to prevent address-based leaks.
  5. Tor's own traffic is exempted to prevent routing loops.

The only way to bypass this protection is to manually unload the firewall, stop Tor, and intentionally run raw emerge commands.

Files

  • /usr/sbin/lainos-private-sync - Firewall control script
  • /etc/profile.d/lainos-private-sync.sh - Shell wrapper functions
  • /etc/tor/torrc - Tor configuration (requires TransPort/DNSPort)

Integration

This package is designed to work seamlessly with LainOS's private-mode orchestration script, which handles:

  • Starting/stopping Tor with proper configuration
  • Randomizing MAC addresses
  • Switching DNS resolvers
  • Managing the firewall lifecycle

Manual use of lainos-private-sync is supported but not recommended for typical users.

Troubleshooting

"Kernel lacks nftables NAT/REDIRECT support"

Your kernel is missing required modules. Recompile with the kernel options listed above. demerge will automatically fall back to the SocksPort proxy if Tor is running.

"ERROR: Kernel firewall is inactive AND Tor is not running on port 9050."

The fail-closed safety check triggered. Start Tor (torctl s) or enable full private mode (private-mode on) before attempting to sync.

DNS Resolution Fails during Sync

Ensure Tor is running with DNSPort enabled:

ss -tlnup | grep :9059

If nothing is listening, check /etc/tor/torrc for the DNSPort configuration.

Git/Portage Hangs on IPv6

The firewall blocks IPv6 to prevent leaks. If you see IPv6-related hangs, ensure the ip6 table is loaded:

doas nft list table ip6 lainos_private_sync_ip6_block