TechEarl

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.

Ishan Karunaratne⏱️ 5 min readUpdated
Share thisCopied
torrc cheat sheet: SOCKS ports, control port auth, circuits, country pinning, v3 hidden services, bridges, logging, and performance directives with examples.

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.

Cheat sheet

torrc Cheat Sheet

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.

Where torrc lives

The Tor daemon reads its config from a single text file. Locations vary by how you installed it.

InstallPath
Linux (Debian/Ubuntu, Fedora, Arch packages)/etc/tor/torrc
Linux (compiled from source)/usr/local/etc/tor/torrc
macOS (Homebrew)/opt/homebrew/etc/tor/torrc (Apple Silicon) or /usr/local/etc/tor/torrc (Intel)
Tor BrowserBrowser/TorBrowser/Data/Tor/torrc inside the bundle
Tails / Whonix/etc/tor/torrc (managed by the distro; user changes get overwritten on shutdown)

After editing, reload (don't restart unless you need to):

bash
# systemd-managed
sudo systemctl reload tor

# everything else (sends SIGHUP)
sudo pkill -HUP tor

A SIGHUP tells the daemon to re-read torrc without dropping current circuits.

Complete example: client-only torrc

A reasonable starting torrc for using Tor as a SOCKS proxy from a laptop:

text
# Listen for SOCKS5 from local apps
SocksPort 9050 IsolateDestAddr IsolateDestPort

# Local DNS resolver so I can iptables-route DNS through Tor
DNSPort 5353
AutomapHostsOnResolve 1

# Control port for nyx and per-script NEWNYM
ControlPort 9051
CookieAuthentication 1
CookieAuthFileGroupReadable 1

# Reasonable circuit settings
MaxCircuitDirtiness 600
NumEntryGuards 3

# Quiet-ish logging
Log notice file /var/log/tor/notices.log
DataDirectory /var/lib/tor

# Never be an exit
ExitPolicy reject *:*

Complete example: hidden service operator

text
# Keep client-side knobs
SocksPort 9050
ControlPort 9051
CookieAuthentication 1

# The hidden service itself
HiddenServiceDir /var/lib/tor/myservice/
HiddenServicePort 80 127.0.0.1:8080
HiddenServicePort 443 127.0.0.1:8443

# Resilience tuning
HiddenServiceNumIntroductionPoints 6
HiddenServiceMaxStreams 50
HiddenServiceMaxStreamsCloseCircuit 1

Log notice file /var/log/tor/notices.log

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.

Complete example: bridge user behind ISP block

text
UseBridges 1
ClientTransportPlugin obfs4 exec /usr/bin/obfs4proxy

# Replace with bridge lines from https://bridges.torproject.org/options
Bridge obfs4 192.0.2.1:443 0123456789ABCDEF0123456789ABCDEF01234567 cert=AAAA... iat-mode=0
Bridge obfs4 192.0.2.2:443 9876543210FEDCBA9876543210FEDCBA98765432 cert=BBBB... iat-mode=0

SocksPort 9050
Log notice file /var/log/tor/notices.log

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.

FAQ

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.

See also

Sources

Authoritative references this article was fact-checked against.

TagsTORtorrcNetworkingPrivacyAnonymityCheat SheetCommand Line

Found this useful? Pass it on.

Copied

Ishan Karunaratne

Software Systems Architect · Senior Software Engineer · Engineering Leadership

Software systems architect and senior software engineer with more than two decades designing, building, and running production software, Linux systems, and DevOps infrastructure, and lately working AI into the stack. Now a CTO, though what I write here is drawn from the full arc of that work, across architecture, engineering, and operations, not any single job.

More by Ishan →LinkedIn
Keep reading

Related posts