GnoppixCTL User Manual

With Gnoppix 26.11 we added more options into GnoppixCTL. Now GnoppixCTL routes by default your internet traffic through the Tor network. It can run Tor as a local proxy for the apps that follow system proxy settings, or as a system-wide VPN tunnel that carries everything this computer sends. It picks working connection strategies for censored networks (Smart Connect, bridges, pluggable transports), lets you publish private .onion services, and can volunteer as a Snowflake proxy for others. If you know Orbot (Android) we have now something similar.

Please note: Not only web traffic is routed anonymously; all network traffic is routed. Depending on your internet speed, the first connection may take up to 20 seconds.

Disclaimer — GnoppixCTL is provided “as-is”. Tor usage may be restricted or illegal in some jurisdictions; you are solely responsible for complying with local laws. As always, and not limited by this application which is part of Gnoppix Linux please see our Terms of Service.

1. Install and start (Linux .deb)

sudo apt install gnoppixctl

Start GnoppixCTL from your applications menu, or run gnoppixctl in a terminal. The app ships its own runtime and Tor bundle under /opt/gnoppixctl — nothing else to install.

Closing the window can keep the app alive in the tray/menu bar (Settings → General → “Minimize to tray on close”). The tray menu offers Show, Connect, Disconnect and Exit.
On first start, Home shows a short welcome card. Press Got it once; it never returns.

2. Home — connecting

The Home page is where you connect and watch what the tunnel is doing.

Connect / Disconnect / Cancel — the main button starts or stops Tor. While connecting you can press Cancel.

Mode — how your traffic reaches Tor:

TUN/VPN Mode (default) — every app on this computer goes through Tor. Needs administrator/root rights for the network adapter.
Proxy Mode — only apps that follow the system proxy settings go through Tor (browsers usually do; downloaders, games and many programs don’t).

The mode is locked while a session is running — disconnect to change it.

Smart Connect (recommended) — automatically picks the best connection strategy for your network and country. When it is on, some bridge/censorship settings may be overridden. Leave it on unless you have a specific reason to control everything yourself.

Exit Location — the country your traffic appears to come from. “Automatic” is the safe default; forcing a country can reduce anonymity.

System proxy — whether system proxy settings point at Tor. You can toggle it while connected without dropping Tor. When OFF, only apps manually set to the SOCKS port use Tor.

LAN sharing — lets other devices on your network use Tor through the addresses shown.

Current IP / Refresh IP / Copy IP — the exit-side view of your address. The displayed country is estimated from that IP and can differ from your chosen exit.

New Identity — builds fresh circuits (a confirmation dialog warns that existing .onion service addresses change). Use it to get a new exit path without restarting.

Update bridges — fetches fresh, tested bridges over your normal connection (works behind a VPN; you do not need Tor connected first).

This session — circuits built, identity changes, uptime, downloaded/uploaded.

Tunnel verified / leak warning — after connecting, GnoppixCTL tests that a new connection really left through Tor. If it comes out with your real IP you get “Your traffic is not going through Tor” — don’t rely on that session; disconnect and check the Sing-box/Xray tab under Logs.

Kill switch — if enabled (Settings → Advanced) and the tunnel drops, all internet traffic stays blocked so nothing leaks out unencrypted. Home then shows “Blocked by kill switch” with Restore internet or reconnect.

3. Censored networks: bridges

If your network blocks plain Tor, turn on bridges (Settings → Network → “Bridges & Censored Networks”):

Use Tor bridges — master switch.
Bridge type — Automatic (recommended), or pick one: vanilla, obfs4, snowflake, conjure, webtunnel, meek-azure, DNS tunnel (dnstt), custom.
Bridge source — Auto (GnoppixCTL collector + Tor bridge service, then offline lists), bridge service only, offline only, collector only, or your custom list.
Custom bridges — paste lines from bridges.torproject.org (one per line).
Snowflake: Use AMP cache — turn on if you see “Snowflake broker unreachable”; it reaches the broker through Google’s AMP cache.

Entry-node pinning is unavailable while bridges are on — the bridge is your entry.

The Scanner page (see §5) can test which bridges actually answer from your network and apply the working ones.

4. Settings

Three tabs: General, Network, Advanced. A search box at the top filters settings by name on the current tab.

General

Startup & Behavior — Auto-connect on launch, Auto-start (with the desktop session, optionally minimized), Minimize to tray on close.
Appearance — theme (system/light/dark), accent color, language, native window chrome, “Show advanced connection details on Home”, Reduce motion (turns off interface animations).
Privacy & security — clear session data on disconnect, block LAN access, DNS leak protection, clipboard protection (auto-clears copied values), keep the admin helper running (so TUN/VPN mode doesn’t ask for permission every connect).
Restore default settings — resets everything to defaults.

Network

Bridges & Censored Networks — see §3.
Upstream proxy (advanced) — make Tor connect out through a corporate/SOCKS or HTTPS proxy first. Requires the Classic Tor engine.
Proxy Mode — proxy behavior (system proxy for all apps / SOCKS-only for browsers and .onion / local-only for manual setup), preferred SOCKS and HTTP tunnel ports.
Secure DNS (DoH) in VPN mode — DNS provider (Auto benchmarks providers and picks the fastest healthy one) or a custom DoH host/path.
Onion services — see §6.
Snowflake bridge (volunteer) — relay other censored users’ traffic over WebRTC. It does not route your own traffic. Options: run now, start with the app, max concurrent clients.

Advanced

Tor engine — Automatic (recommended), Classic stable, Arti next-gen, or ArtiHop fast (2-hop; lower latency, weaker anonymity).
Circuit pinning — manual guard/middle/exit fingerprints and “strict” options (fail if the chosen fingerprint is unavailable). Manual shaping can reduce anonymity; leave empty unless you know why you need it.
TUN engine — TUN core (sing-box recommended, xray experimental), TUN stack (Mixed recommended), MTU (empty = auto; 576–9000), strict route, disable IPv6 (use if the tunnel fails with “set ipv6 address”), kill switch.
Routing rules (TUN/VPN mode) — per-line lists of domains or CIDR ranges to bypass Tor (direct) or block entirely. Country routing (ISO codes, auto-updating geoip) and domain-category routing (e.g. category-ads-all to block ads, auto-updating geosite) work the same way.
Split Tunneling (Hybrid mode) — in TUN/VPN mode, route only chosen apps through Tor (“Choose running apps…” picker: Default / Through Tor / Direct). Options to route all web traffic (80/443) and block QUIC/UDP for Tor-routed apps. The kill switch is unavailable while split tunneling is on.
Automation & updates — update channel (Stable/Preview), open a page on connect (default check.torproject.org) or on disconnect, relay data refresh interval, connection timeout.

Invalid values are flagged right under the field (e.g. fingerprints must be 40 hex characters; MTU 576–9000; timeout 1–3600 s) and connecting is refused until fixed.

5. Scanner — find what works on your network

Bridge Scanner — TCP-ping bridges from the collector list (or your own pasted lines) filtered by category/transport/IP. Green = reachable, amber = slow, red = blocked. Then Export Working or Use Working as Bridges.
SNI Scanner — find front hosts that work for domain-fronted transports. Test a list of domains, or one SNI across an IPv4 range. Green = TLS handshake succeeded. Apply the results as SNI hosts.
Saved — your library of saved bridges and SNI hosts: apply one, relabel, delete, or copy all.

6. Onion services — publish a private .onion

Settings → Network → Onion services: publish a camera, NAS or web app under a .onion address — no port forwarding, no static IP, and it is not exposed to the open internet.

Add a service: name, the onion port, and the local target host + port.
Connect — the service publishes and gets its address (“Connect to publish it and get the address”).
Copy the address. It stays the same across sessions.

Warning: anyone who has the address can reach that device — the device’s own password is what protects it. Use a strong one and treat the address as a secret. Removing a service deletes its saved key; re-creating it produces a different address (a confirmation dialog says so).

7. Relays

Browse the live Tor relay list with filters (search, country, role, flags, bandwidth). You can pin a relay as preferred guard/middle/exit (experimental). Manual relay selection can reduce anonymity — use it only if you understand the tradeoffs.

8. Logs

Tabs: App, DNS, Current Bridge, Xray, Sing-box. Search, filter by level (Info/Warning/Error), pause, auto-scroll. Copy, Export… and Clear (with a confirmation; export first if you need the entries). Logs are local-only — they are never uploaded.

9. Troubleshooting

Connection fails or is slow — keep Smart Connect on; if it still fails, enable bridges (§3) and try a different bridge type (snowflake and webtunnel are usually the hardest to block).
“Snowflake broker unreachable” — turn on the Snowflake AMP cache option.
Tunnel starts but traffic leaks — heed the leak warning, disconnect, and check the Sing-box/Xray log tab for routing errors.
TUN tunnel won’t start (“set ipv6 address”) — enable “Disable IPv6 in the tunnel” (Advanced → TUN engine).
No admin prompt wanted each time (TUN mode) — enable “Keep admin helper running” in General → Privacy & security.
Another app already uses the SOCKS port — change the preferred SOCKS port (Network → Proxy Mode).
Everything back to normal — Settings → General → Restore default settings.

10. Good practice

Leave Smart Connect and Automatic exit location on unless you have a specific need.
Don’t pin entry/middle/exit nodes or relays unless you know why — it weakens anonymity.
Bridges are for censorship resistance, not for ordinary location switching.
In Proxy Mode, remember that apps ignoring the system proxy bypass Tor — use TUN/VPN mode for full coverage (it also covers WebRTC/UDP leaks).

Cheatcodes

In case the application looks bit blurry, it mean you’re not using gnoppix, jokes aside. Is is a wayland problem, GTK3 does not support fractional scaling. The app renders at 1x, then kwin_wayland upscales it with bilinear filtering — this is what makes everything blurry, regardless of font size or anti-aliasing settings.

Fix options:

Per-app launch — run with GDK_DPI_SCALE to compensate (avoids compositor upscaling): GDK_SCALE=1 GDK_DPI_SCALE=1.5 sudo gnoppixctl-gui

(adjust 1.5 to match your screen scale)

System-wide GTK3 fix — create ~/.config/gtk-3.0/settings.ini:

[Settings] gtk-xft-dpi=147456 (147456 = 144 DPI = 96 × 1.5) — tells GTK3 to render fonts at the correct size without compositor scaling.

KDE setting — System Settings → Display → set “Scale method” to “Prefer crisp text” (if available) or disable fractional scaling and use integer scaling instead.