torrc Cheat Sheet: Complete Tor Configuration Reference
Every torrc directive worth knowing in 2026, grouped by what you're trying to do: SOCKS and control ports, circuit construction, country pinning, hidden services, bridges, logging, and performance tuning.
The torrc file is Tor's configuration, at /etc/tor/torrc on Debian and Ubuntu. The directives you reach for most: SocksPort 9050 for the SOCKS proxy, ControlPort 9051 with CookieAuthentication 1 for scripted control, ExitNodes and StrictNodes 1 for country pinning, and HiddenServiceDir plus HiddenServicePort for an onion service.
A torrc cheat sheet is a single-page reference of the configuration directives the Tor daemon accepts, grouped by what you are trying to do: open a SOCKS proxy for applications, lock down the control port, build longer or shorter circuits, pin entry or exit countries, run a hidden service, route through bridges, tune logging, or squeeze out more performance. This covers Tor 0.4.x through the current stable in 2026, with the "as of which version" notes added where a directive changed behavior recently.
Reference for every common torrc directive in Tor 0.4.x, grouped by use case. Includes SOCKS and control ports, country pinning, hidden services, bridges, performance tuning, and logging.
Network and SOCKS
SocksPort 9050Open a SOCKS5 proxy for applications on the given port. Default 9050. Tor Browser uses 9150 to coexist with a system tor on 9050.
SocksPort 0.0.0.0:9050Bind SOCKS to all interfaces (exposes the proxy on the network). Default is localhost only; only do this on a trusted LAN.
SocksPort 9050 IsolateDestAddr IsolateDestPortIsolate streams by destination, a separate circuit per host:port. Improves anonymity when one app talks to many destinations.
DNSPort 5353Run a Tor-internal DNS resolver on the given port. Use with `iptables` to force all DNS through Tor and prevent leaks.
AutomapHostsOnResolve 1Auto-map .onion and .exit lookups to virtual IPs so legacy apps that can't talk SOCKS5h still reach onion sites.
VirtualAddrNetworkIPv4 10.192.0.0/10The IP range used for AutomapHostsOnResolve. Defaults are fine; change only if it clashes with a real LAN range.
TransPort 9040Transparent proxy port. With `iptables`, force all TCP through Tor without per-app config. The Whonix gateway is the canonical use.
Control port and authentication
ControlPort 9051Open the control port, lets external programs (nyx, stem, your scripts) send signals like NEWNYM or query circuit state.
ControlSocket /var/run/tor/controlUnix-domain socket alternative to ControlPort. Preferred locally because filesystem permissions handle auth.
CookieAuthentication 1Authenticate to the control port using a cookie file Tor writes at start. Combined with `CookieAuthFileGroupReadable 1`, the cleanest local auth.
HashedControlPassword 16:...Password auth for the control port. Generate the hash with `tor --hash-password 'yourpass'` and paste the output here.
ControlPortWriteToFile /var/run/tor/control.txtWrite the bound port number to a file (useful when ControlPort is `auto`). Lets wrappers discover the chosen port.
Circuit construction
CircuitBuildTimeout 10Seconds to wait for a circuit to build before discarding it. Lower = faster failover, higher = more patient on slow links.
MaxCircuitDirtiness 600Seconds before a circuit is rotated for new streams. Lower for stronger unlinkability (more circuit churn), higher for stable long-lived TCP connections.
NewCircuitPeriod 30How often (seconds) Tor considers building a new clean circuit. Don't lower without good reason, circuit churn hurts performance.
NumEntryGuards 1Number of long-lived primary guard relays to use. With the default value 0, Tor learns this from the `guard-n-primary-guards-to-use` consensus parameter and falls back to 1 if it is unset. Higher = more entry-point exposure.
EnforceDistinctSubnets 1Refuse to build a circuit that includes two relays in the same /16. On by default. Disable only for testing.
UseEntryGuards 1Use the guard set rather than a fresh entry per circuit. Default. Disable only for research; defeats important security properties.
Country pinning
ExitNodes {us},{de},{nl}Allowed exit countries (last hop). Two-letter ISO codes in braces. See the full country-code table for every code Tor accepts.
EntryNodes {se},{ch}Allowed entry guard countries (first hop). Most users should leave this alone, guard pinning weakens long-term security properties.
ExcludeNodes {cn},{ru},{ir},{kp}Banned countries for any hop in the circuit. Combined with `StrictNodes 1`, becomes a hard ban.
ExcludeExitNodes {us},{gb},{ca},{au},{nz}Ban countries only from being the exit. Useful when you want to avoid a jurisdiction terminating the connection but don't mind it in the middle.
StrictNodes 1Turn country directives from preferences into hard rules. Without this, Tor falls back silently when no relay matches.
GeoIPFile /usr/share/tor/geoipPath to the IPv4 GeoIP database Tor uses to map relays to countries. Override if you maintain your own.
GeoIPv6File /usr/share/tor/geoip6Path to the IPv6 GeoIP database. Same idea, separate file.
Hidden services (v3 onion)
HiddenServiceDir /var/lib/tor/myservice/Directory where Tor stores the .onion private key and hostname for this service. Permissions must be 700 and owned by the tor user.
HiddenServicePort 80 127.0.0.1:8080Map public onion port 80 to a local service at 127.0.0.1:8080. Add one line per port you want to expose.
HiddenServiceVersion 3Use the modern v3 onion address format (56 chars + .onion). v2 was removed in Tor 0.4.6, so this is implicit, but spelling it out makes the config explicit.
HiddenServiceNumIntroductionPoints 6Number of introduction points the service advertises. More = more resilience under load, more rendezvous traffic.
HiddenServiceMaxStreams 0Per-circuit stream cap. 0 means unlimited. Set a low value (e.g., 10) for services that don't need many concurrent connections to mitigate burst abuse.
HiddenServiceSingleHopMode 1Single-onion service: skip the rendezvous on the service side. Has no effect on its own. It also requires `HiddenServiceNonAnonymousMode 1`, and with single-hop mode enabled Tor refuses to start unless `SocksPort 0` is also set. Faster, but no anonymity for the service operator.
Bridges and pluggable transports
UseBridges 1Route entry traffic through bridges instead of the public guard set. Required when your ISP blocks the public Tor relays.
Bridge obfs4 192.0.2.1:443 FINGERPRINT cert=... iat-mode=0An obfs4 bridge line. Get the full line from bridges.torproject.org or by emailing bridges@torproject.org.
Bridge snowflake 192.0.2.3:1 2B280B23E1107BB62...Snowflake bridge. The exact IP is fake (Snowflake hops via WebRTC volunteers), but the line is still required for the daemon.
ClientTransportPlugin obfs4 exec /usr/bin/obfs4proxyTell Tor where the obfs4 transport binary lives. Path varies by distro: `/usr/bin/obfs4proxy` on Debian, `/opt/homebrew/bin/obfs4proxy` on macOS Homebrew.
ClientTransportPlugin snowflake exec /usr/bin/snowflake-clientSame idea for Snowflake. The client opens a WebRTC tunnel to a volunteer browser before reaching the actual relay.
Performance and bandwidth
RelayBandwidthRate 1 MBytesWhen running a relay, soft cap on average bandwidth. Use `KB`, `MB`, `GB` suffixes.
RelayBandwidthBurst 2 MBytesAllowed burst on top of `RelayBandwidthRate`. Tor smooths to the rate over time.
BandwidthRate 200 KBytesClient-side bandwidth cap. Affects both relay and client traffic if you're running both.
BandwidthBurst 400 KBytesClient-side burst cap, same pattern as relay version.
KeepalivePeriod 60Seconds between keepalive cells on connections. Lower if NAT is dropping idle connections.
AvoidDiskWrites 1Skip writing state files to disk between sessions. Lower wear on SSDs, but means rebuilt circuits and re-fetched directory on every restart.
Logging
Log notice file /var/log/tor/notices.logSend notice-level and above to a file. `notice` is the default; raise to `warn` or `err` to quiet a noisy daemon.
Log info file /var/log/tor/info.logVerbose logging, useful while debugging circuit issues, very chatty otherwise.
Log debug file /var/log/tor/debug.logFull firehose. Will fill a disk if left on. Set a logrotate policy if you must keep it on.
Log notice syslogSend notice-level logs to syslog instead of a file. Plays nicely with journalctl on systemd hosts.
DataDirectory /var/lib/torWhere Tor keeps its descriptor cache, state file, and (with `AvoidDiskWrites 0`) any persistent state. Permissions matter, must be owned by the tor user.
PidFile /run/tor/tor.pidPath Tor writes its PID to. systemd usually handles this; only set manually for non-systemd setups.
Safety and policy
ExitPolicy reject *:*Refuse to act as an exit. The default for a relay is to allow exits, which has legal implications, set this if you don't want to be an exit operator.
ExitPolicy accept *:80,*:443,reject *:*Allow exits only to common web ports. Reduces the abuse surface but still useful for the network.
SafeLogging 1Scrub log lines of potentially sensitive data (IP addresses, .onion names). On by default since Tor 0.2.x.
SafeSocks 1Reject SOCKS connections that don't use SOCKS5 with hostname resolution (i.e., reject DNS-leaking apps). Worth enabling for any public proxy.
TestSocks 1Log a warning for every SOCKS connection that resolves DNS locally rather than through Tor. Useful while auditing apps for DNS leaks.
A reasonable starting torrc for using Tor as a SOCKS proxy from a laptop:
text
# Listen for SOCKS5 from local appsSocksPort 9050 IsolateDestAddr IsolateDestPort# Local DNS resolver so I can iptables-route DNS through TorDNSPort 5353AutomapHostsOnResolve 1# Control port for nyx and per-script NEWNYMControlPort 9051CookieAuthentication 1CookieAuthFileGroupReadable 1# Reasonable circuit settingsMaxCircuitDirtiness 600NumEntryGuards 3# Quiet-ish loggingLog notice file /var/log/tor/notices.logDataDirectory /var/lib/tor# Never be an exitExitPolicy reject *:*
The directory at HiddenServiceDir is created automatically on first start. Tor writes the public hostname to hostname and the private key to hs_ed25519_secret_key inside it. Back up the secret key, losing it means losing the .onion address forever.
Three bridges is the sweet spot, enough redundancy that one going down doesn't cut you off, not so many that you're hammering volunteer-run infrastructure.
The path depends on how Tor was installed. On Debian/Ubuntu and most Linux distros it's /etc/tor/torrc. On macOS Homebrew it's /opt/homebrew/etc/tor/torrc on Apple Silicon and /usr/local/etc/tor/torrc on Intel. Tor Browser keeps its own at Browser/TorBrowser/Data/Tor/torrc inside the bundle.
You can also pass tor -f /path/to/torrc to run with an arbitrary config file, which is how multi-instance setups work.
No. Send SIGHUP and Tor re-reads the file in place: sudo systemctl reload tor on systemd, or sudo pkill -HUP tor elsewhere. Existing circuits keep working; new circuits use the new settings.
A few directives (port changes, DataDirectory moves) need a full restart because they affect bound sockets or on-disk layout.
None functionally. 9050 is the default for the standalone Tor daemon you install from your package manager; 9150 is what Tor Browser ships with so it doesn't collide with a system-wide tor on 9050. If both are running, point your scripts at one or the other consciously.
Two clean options. With CookieAuthentication 1, Tor writes a binary cookie file at $DataDirectory/control_auth_cookie on startup; your script reads it and sends AUTHENTICATE <hex-cookie>. With HashedControlPassword, you set the hash in torrc and your script sends AUTHENTICATE "yourpassword".
Cookie auth is preferred locally because filesystem permissions handle access control. Use a password when the controller runs on a different host.
Yes. Each instance needs its own SocksPort, ControlPort, and DataDirectory. Start each with tor -f /etc/tor/torrc-foo and they coexist happily. This is the standard pattern for switching exit countries per command, one daemon per country, each on a different SOCKS port.
Don't, unless you have to. The control port can rotate circuits, read your guard list, and dump the descriptor cache. If you must, set HashedControlPassword, bind ControlPort to 127.0.0.1 only (the default), and SSH-tunnel from your client: ssh -L 9051:127.0.0.1:9051 user@host. Never bind ControlPort 0.0.0.0:9051.
The canonical reference is man tor on a host that has Tor installed, every directive has its earliest-version note. The web copy at torproject.org's manual page is the same content. If a directive isn't in your installed man page, your Tor is older than the directive.
TagsTORtorrcNetworkingPrivacyAnonymityCheat SheetCommand Line
Found this useful? Pass it on.
Copied
Ishan Karunaratne
Systems and Network Architect · Chief Technology Officer
Systems and network architect and Chief Technology Officer with more than two decades designing, building, and running production software, cloud and network architecture, Linux systems, and the bare metal underneath them, and lately working AI into the stack. A US Army veteran who served in Operation Iraqi Freedom. What I write here is drawn from the full arc of that work, across architecture, engineering, and operations, not any single job.
A scannable SSH reference: ssh-keygen, ssh-copy-id, port forwarding (-L, -R, -D), ProxyJump, ~/.ssh/config blocks, scp and rsync over SSH, with the Windows OpenSSH differences and PuTTY equivalents.
A scannable grep reference with the flags I actually use, the GNU vs BSD differences that bite on macOS, and the Windows equivalents (Select-String, findstr) for the same patterns.
Every docker run flag I actually use, grouped by job: detach, interactive shells, ports, volumes, environment, network, restart, resources, platform, user, and the one-shot --rm pattern.
