Version 330 (modified by trac, 10 years ago) (diff)


#pragma section-numbers on ## Copyright (c) 2004 Thomas Sjogren. ## Copyright (C) 2004, 2005, 2006 Contributors ## Distributed under the MIT license, ## See ./LegalStuff for a full text [:../:up to Tor]

TORifying software for Linux and Unix environments HOWTO

This document explains how to configure particular programs to use Tor in a Linux/UNIX environment. It does not cover Windows yet, but experienced Windows users can glean the proper settings by reading this document. You are free to add your own Windows configurations to this document.

Note that this is a very brief document on how to make various programs use Tor as a proxy; you should read the documentation at first. Since most programs use similar locations for various settings, the following examples will get you going most of the time. If you're using anything that needs some exotic workarounds, or your distribution doesn't use SysV (/etc/init.d/ startup scripts), for example, this guide currently won't help you a lot, since it is a bit bash and Debian specific. Feel free to edit this page; it's a Wiki, after all.

Table of Contents TableOfContents?


Basic Configuration Issues



Unix and Linux Configuration


Under Unix and GNU/Linux, most HTTP capable applications, like lynx, wget and curl, will honor the value of the http_proxy environment variable. Some applications use all lower case, some all upper, so specify both to be safe.

Add the following lines to your $HOME/.bash_profile, $HOME/.bashrc, or env settings:

export http_proxy HTTP_PROXY


About DNS and tsocks


tsocks correctly replaces connect(2) calls with calls to your SOCKS proxy (Tor), but it doesn't do anything about requests to your DNS server. This means that if you refer to any machines by hostname when you're using tsocks, you'll be sending that hostname over the network, perhaps leaking the fact that you are about to connect to the corresponding server.

Other applications that use SOCKS 4 or SOCKS 5 directly often have the same shortcoming.

Tor 0.0.8 (or later) has a workaround for this problem; until we can hack tsocks (or a work-alike) to support DNS, instead of using a hostname directly, first use tor-resolve to resolve the hostname into an IP (via Tor) and then use that IP address with your tsocks-ified application.

See [:TheOnionRouter/TorFAQ#SOCKSAndDNS: the FAQ] for more information.

NOTE: There is now a patch to the tsocks code that handles dns leaks and .onion addresses, tordns


About socat


socat is a multipurpose relay for bidirectional data transfer. It is possible to use socat as a general means by which programs agnostic of SOCKS can use Tor by connecting to a local TCP port.

Socat (for SOcket CAT) establishes two bidirectional byte streams and transfers data between them. Data channels may be files, pipes, devices (terminal or modem, etc.), or sockets (Unix, IPv4, IPv6, raw, UDP, TCP, SSL). It provides forking, logging and tracing, different modes for interprocess communication and many more options.

It can be used, for example, as a TCP relay (one-shot or daemon), as an external socksifier, as a shell interface to Unix sockets, as an IPv6 relay, as a netcat and rinetd replacement, to redirect TCP-oriented programs to a serial line, or to establish a relatively secure environment (su and chroot) for running client or server shell scripts inside network connections.

Suppose that you wanted to connect to an IRC server running on, port 6667.

socat TCP4-LISTEN:4242,fork,socksport=9050

Connecting to localhost, port 4242, would then be equivalent to connecting to, port 6667, via Tor.

What interests us most for Tor is that it supports socks4a redirection, allowing your client to connect to an hidden service. Assuming you want to join to an hidden irc server running on foo.onion on port 6667.

You might want to start a local tunnel that forwards connection for local port 4242 to this service using Tor.

socat TCP4-LISTEN:4242,fork SOCKS4A:localhost:foo.onion:6667,socksport=9050

Warning: socat versions up to and including had a bug that would use SOCKS4A only when a direct DNS resolution attempt failed, thus possibly revealing which DNS names you accessed through socat. See this post tor-dev for details.


Socat on OpenBSD 3.7


There is no port or package for socat in OpenBSD. It compiles cleanly from the source. If you only use socat for Tor, I'd suggest trying these configure options:

./configure --disable-file --disable-creat --disable-gopen --disable-pipe --disable-unix --disable-exec \
            --disable-system --disable-pty --disable-readline --prefix=/usr/local/opt
gmake && gmake install

to install everything into /usr/local/opt (to avoid overwriting normal ports).

Instead of the above socat command, you can also make it bind only to localhost:

## Connect to oftc on
/bin/systrace -e -a -t /usr/local/opt/bin/socat TCP4-LISTEN:6777,bind=localhost,range=,fork \,socksport=9050 > socat_log.$$ 2>&1 &

Now in irssi, you would just type /connect 6677 and it would connect you to through Tor.

Add /bin/systrace -e -a -t if you have a systrace policy for socat. Here's an example policy for IRC.

Policy: /usr/local/opt/bin/socat, Emulation: native
        native-__sysctl: permit
        native-issetugid: permit
        native-mmap: permit
        native-munmap: permit
        native-mprotect: permit
        native-mquery: permit
        native-break: permit
        native-write: permit
        native-close: permit
        native-exit: permit
        native-fcntl: permit
        native-fsread: filename eq "/etc/malloc.conf" then permit
        native-fsread: filename eq "/home/$USER" then deny
        native-fsread: filename eq "/home/$USER/." then deny
        native-fsread: filename eq "/var/mail/$USER" then deny
        native-fsread: filename eq "/var/run/" then permit
        native-fsread: filename eq "/usr/lib" then permit
        native-fsread: filename match "/usr/lib/*" then permit
        native-fsread: filename match "/usr/lib/*" then permit
        native-fsread: filename match "/usr/lib/*" then permit
        native-fsread: filename match "/usr/lib/*" then permit
        native-fsread: filename eq "/usr/share/nls/C/" then permit
        native-fsread: filename eq "/usr/share/zoneinfo/US/Eastern" then permit
        native-fsread: filename eq "/usr/share/zoneinfo/GMT" then permit
        native-fsread: filename eq "/usr/share/zoneinfo/posixrules" then permit
        native-fsread: filename eq "/etc/resolv.conf" then permit
        native-fsread: filename eq "/etc/hosts" then permit
        native-fsread: filename eq "/etc/pwd.db" then permit
        native-fsread: filename eq "/etc/group" then permit
        native-fstat: permit
        native-getegid: permit
        native-geteuid: permit
        native-getgid: permit
        native-getpid: permit
        native-getppid: permit
        native-gettimeofday: permit
        native-getsockname: permit
        native-getuid: permit
        native-sigaction: permit
        native-sigprocmask: permit
        native-read: permit
        native-fsread: filename eq "/" then permit
        native-execve: filename eq "/usr/local/opt/bin/socat" and argv eq "/usr/local/bin/irssi" then permit
        native-socket: sockdom eq "AF_INET" and socktype eq "SOCK_STREAM" then permit
        native-socket: sockdom eq "AF_INET" and socktype eq "SOCK_DGRAM" then permit
        native-socket: sockdom eq "AF_UNIX" and socktype eq "SOCK_DGRAM" then permit
        native-socket: sockdom eq "AF_UNIX" and socktype eq "SOCK_STREAM" then permit
        native-connect: sockaddr eq "inet-[]:9050" then permit
        native-connect: sockaddr eq "inet-[]:53" then permit
        native-bind: sockaddr eq "inet-[]:6677" then permit
        native-bind: sockaddr eq "inet-[]:6777" then permit
        native-listen: permit
        native-accept: permit
        native-getpeername: permit
        native-fork: permit
        native-chroot: filename eq "/var/empty" then permit
        native-wait4: permit
        native-wait: permit
        native-sigreturn: permit
        native-pread: permit
        native-setgroups: permit
        native-select: permit
        native-shutdown: permit

Note' that the above native-shutdown refers to the function call shutdown(2) to shut down part of a full-duplex connection and not the command shutdown.

If you didn't use the configure line above, you will have to add more native-fsread statements for the extra libraries.

This also assumes that you have dsocks' setup to handle DNS requests on


Web browsers


Web browsing and Privoxy is also covered in the tor setup docs, specifically




Settings -> Configure Konqueror -> Proxy -> Manually Specify the proxy settings -> Setup

HTTP/S Proxy: port 8118

Or edit $HOME/.kde/share/config/kioslaverc:




Setup -> Network Options

HTTP Proxy: port 8118

Or edit /etc/links.cfg (system-wide) or $HOME/.links/links.cfg (per-user):





Lynx will respect the http_proxy enviroment variable, but you can edit /etc/lynx.cfg:



Mozilla Firefox


Edit -> Preferences -> General -> Connection Settings -> Manual proxy configuration

HTTP Proxy: port 8118
SSL Proxy: port 8118

To change the proxy configuration for all Firefox users on your machine, edit the /usr/lib/mozilla-firefox/greprefs/all.js file:

pref("network.proxy.type",                  1);
pref("network.proxy.http",         "");
pref("network.proxy.http_port",          8118);
pref("network.proxy.ssl",          "");
pref("network.proxy.ssl_port",           8118);
pref("network.proxy.socks",                 "");
pref("network.proxy.socks_port",            0);
pref("network.proxy.socks_version",         5);
pref("network.proxy.no_proxies_on",         "localhost,");

In later versions of Firefox, at least in the current version under Linux, you can enable the browser to do remote domain name look ups. The option network.proxy.socks_remote_dns is available via about:config and should look like

network.proxy.socks_remote_dns 	user 	set 	boolean 	true

At you can find an excellent step-by-step introduction how to do this. Be careful, though: In some versions of Firefox (e.g., 1.0.7 under Linux) this option exists, but does nothing. In this case, you may want to use privoxy or similar projects. To find out whether your version implements remote DNS resolution correctly, you may try out a URL ending in .onion, like this one leading to the the Hidden Tor Wiki. If the Hidden Wiki shows up, remote DNS resolution works.

Also, Mac OS X users should change the above preferences by entering about:config in the URL bar because the firefox preferences dialog is a bit screwy.







This isn't the most elegant solution, but it works. Rename your /etc/init.d/fetchmail file to {fetchmail-orig, for example, then save the script below as /etc/init.d/fetchmail, and restart fetchmail with /etc/init.d/fetchmail restart. Your mail will now be fetched through the Tor network.

# Fetchmail+Tor init script

set -e

# Defaults

test -f $DAEMON || exit 0

case "$1" in
		$DAEMON $FMINIT restart
		$DAEMON $FMINIT try-restart
		$DAEMON $FMINIT awaken
		$DAEMON $FMINIT debug-run
		echo "Usage: /etc/init.d/fetchmail {start|stop|restart|force-reload|awaken|debug-run}"
		echo "  start - starts system-wide fetchmail service"
		echo "  stop  - stops system-wide fetchmail service"
		echo "  restart, force-reload - starts a new system-wide fetchmail service"
		echo "  awaken - tell system-wide fetchmail to start a poll cycle immediately"
		echo "  debug-run [strace [strace options...]] - start a debug run of the"
		echo "    system-wide fetchmail service, optionally running it under strace"
		exit 1

exit 0

An alternative configuration for fetchmail for those that prefer to start it on a per-user basis. Add the following to the user's .bashrc:


  function FetchMailAlive () {
    if test -f $CONF_FILE && test -f $FETCHMAIL; then
      if test -f $PID_FILE; then
        if ! kill -0 `cut -d \  -f1 $PID_FILE` 2>/dev/null; then
          eval $($TSOCKS $FETCHMAIL)
          echo New FetchMail started. >&2
        eval $($TSOCKS $FETCHMAIL)
        echo New FetchMail started. >&2
      echo Fetchmail not installed or configured properly. >&2

# Call it

Then it checks for a running fetchmail daemon every time a new shell is opened and starts one if needed.

You may want to look up your mail server's IP with tor-resolve and use the IP in place of a hostname; see the note on tsocks and DNS above.

If you are lazy you can also just call torify fetchmail or torify fetchmail -d 900.


Instant messaging





Preferences -> Network -> Proxy

Proxy type: Socks 5
Port: 9050

See the note on tsocks and DNS above.




Psi is a Jabber client with support for additional Jabber JEP-0027 encryption, with GnuPG and Socks 5 proxy support.

Account Setup -> Modify -> Connection -> Proxy -> Edit -> New

Name: Tor
Type: SOCKS Version 5
Port: 9050

See the note on tsocks and DNS above.







If you are running Privoxy, as recommended, you can just configure irssi's own proxy settings to use Privoxy as an HTTP proxy. Otherwise, you can run Irssi with tsocks irssi. Unfortunately, as mentioned above, Irssi's own proxy configuration options are HTTP specific.

Alternative: torify irssi. Note that torify is just a shell script that calls tsocks after setting the config file to /etc/tor/tor-tsocks.conf.

For OpenBSD users, you can either hack tsocks to work (as of 3.6 there is no port) or you can use dante. Dante is in the ports system. A simple example config that works with irssi and Tor looks like this for /etc/socks.conf (client configuration only)

route {
        from:   to:  via:  port = 9050
        proxyprotocol: socks_v4

and then you can run socksify irssi assuming that Tor is running on localhost:9050.

You may want to look up your IRC server's IP with tor-resolve and use the IP in place of a hostname; see the [:#DNSNote: note on tsocks and DNS] above.

Add the following to your .irssi/config if you want to use Privoxy as your proxy:

settings = {
  core = {
    real_name = "TorUser";
    user_name = "TorUser";
    nick = "TorUser";
    proxy_password = "";
    use_proxy = "yes";
    proxy_string = "CONNECT %s:%d HTTP/1.0\012\012";
    proxy_port = "8118";
    proxy_address = "";

Don't forget to modify the limit-connect settings in the Privoxy .action files first.

To minimize information leakage about your client and timezone add

ignores = ( { level = "CTCPS"; } );

or run

/ignore * CTCPS

and then





X-Chat supports SOCKS 5 and does not leak DNS requests.

Settings-> Preferences -> Network -> Network setup -> Proxy server

Port: 9050
Type: Socks5

Unofficial builds of X-Chat for Windows are free.

See the note on tsocks and DNS above.




Since the SILC client is based on Irssi, you can follow the same procedure to make it use Tor. Combining Tor and SILC might be one of the safest ways to communicate with someone over the Internet. More information about SILC is available at its website.




Silky is a GTK2 SILC client. It does not currently support SOCKS, so the best way to make it work with Tor is using socat (IMO).:

socat TCP4-LISTEN:6666,socksport=9050

And then tell Silky to connect to localhost:6666.




In order to use BitchX with tor, you first need to get ProxyChains, a *NIX-only HTTP and SOCKS proxy client. On Debian systems, install the proxychains package. Once installed, just add

socks5 9050
http localhost 8118

to the ProxyChains config file at ~/.proxychains/proxychains.conf. Now that it is configured, type proxychains bitchx at the command line.

The gentoo build of proxychains seems to be broken on x86 arch. Using tsocks BitchX or torify BitchX works well.

You may want to look up your IRC server's IP with tor-resolve and use the IP in place of a hostname; see the note on tsocks and DNS above.



[link] Proxies and Firewalls

File -> Options -> Connect -> Firewall

Older versions: Mark the "Use SOCKS Firewall" box. Newer versions (mIRC 6.0 and up): Select "Both" from the "Firewall support" pulldown.

Protocol: SOCKS5
Port: 9050

I get "Unable to resolve server" errors using SOCKS4 with mIRC and .onion addresses. SOCKS5 works.




Preferences -> Advanced Preferences -> Proxy Server




BitTorrent is already using a mechanism similiar to tor to communicate with other peers. torifying the bittorrent traffic would just add more overhead and reduce throughput. You may want to use tor to communicate with the tracker, though. For this, just add --tracker-proxy

btlaunchmanycurses --tracker-proxy <directory>











Warning: This will only work for HTTP because Privoxy does not support FTP.

Add the following line to /etc/apt/apt.conf:

Acquire::http::Proxy "";




Add or edit the following lines in your $HOME/.gnupg/gpg.conf:

keyserver x-hkp://yod73zr3y6wnm2sw.onion
keyserver-options honor-http-proxy broken-http-proxy

You may obviously use any public keyserver, like, but hidden services are preferred. At the time of this writing. only two key servers running as hidden servers are publicly available -- d3ettcpzlta6azsm.onion/ and yod73zr3y6wnm2sw.onion.

After that is done, just run

export http_proxy=
gpg --refresh-keys

If you don't want to write the export line every time, you can add alias gpg='http_proxy= gpg' to your .bashrc file as well; if you have set the http_proxy environment variable, you may skip this step.




Wget will also respect the http_proxy enviroment variable, but you can edit /etc/wgetrc:

http_proxy = http://localhost:8118
use_proxy = on


SSH: Method 1 (torify)


Simply run torify ssh <parameters> if the host is not on a local network and you're done.


SSH: Method 2 (connect)


These instructions should work on most *nix systems. Tested on Mac OS X 10.3.x and Debian GNU/Linux.

1 - Upgrade your SSH to an OpenSSH version that has Socks 5 support. The OpenSSH client that is shipped with Mac OS X 10.3 (aka Panther) - OpenSSH_3.6.1p1 - will not work correctly. Download, build and install the current stable version from the OpenSSH website. If you're using Mac OS X, using fink may be easier for you.

2 - Download and build the connect source code. Connect will allow socket connections using SOCKS4/5 and HTTP tunnels. For detailed information on connect, please visit its website. Note: the site appears to be down at the moment, we've mirrored the script at

A pre-compiled version of connect for Mac OS X is available at (md5sum: b5180cb789813fc958209c58b99039fa)

Install connect into the /usr/local/bin directory.

3 - Add the following line to your ssh_config file located at: /etc/ssh/ssh_config (system-wide) or $HOME/.ssh/config (on a per-user basis).

If you used fink to install OpenSSH, it is located at /sw/etc/ssh/ssh_config.

Host 10.*.*.*
ProxyCommand none
Host 172.16.*.*
ProxyCommand none
Host 172.17.*.*
ProxyCommand none
Host 172.18.*.*
ProxyCommand none
Host 172.19.*.*
ProxyCommand none
Host 172.20.*.*
ProxyCommand none
Host 172.21.*.*
ProxyCommand none
Host 172.22.*.*
ProxyCommand none
Host 172.23.*.*
ProxyCommand none
Host 172.24.*.*
ProxyCommand none
Host 172.25.*.*
ProxyCommand none
Host 172.26.*.*
ProxyCommand none
Host 172.27.*.*
ProxyCommand none
Host 172.28.*.*
ProxyCommand none
Host 172.29.*.*
ProxyCommand none
Host 172.30.*.*
ProxyCommand none
Host 172.31.*.*
ProxyCommand none
Host 192.168.*.*
ProxyCommand none
Host *
ProxyCommand /usr/local/bin/connect -4 -S %h %p

All SSH connections, except to the private address ranges defined by the IANA in RFC-1918, will now go through tor.

You may want to look up your SSH server's IP with tor-resolve and use the IP in place of a hostname; see the note on tsocks and DNS above.


SSH: Method 3 (socat)


Use socat as described above. One way to access an SSH server via Tor is to socat to make a tcp4 listener and relay to your local Tor client, then ssh to it. It's not the nicest way. Using OpenSSH, then you can use the ProxyCommand option in your ~/.ssh/config file, as follows:

{{{Host MyHost-tor

ProxyCommand socat -,socksport=9050}}}

Now you can simply use ssh MyHost-tor.

Similarly, if you have an SSH server running as a hidden service, then you will wish to ssh to it with minimal fuss.

{{{Host MyHost-tor

ProxyCommand socat - SOCKS4A:localhost:MyHost.onion:22,socksport=9050}}}

This method is more secure than using tsocks ssh MyHost.onion because ssh will first resolve the hostname, and then try to connect to it. This means that you lose by giving away your IP address during the DNS lookup.

Using wildcards and parameter expansions features of SSH you can put a single configuration for all .onion addresses:

{{{Host *.onion

ProxyCommand socat STDIO SOCKS4A:localhost:%h:%p,socksport=9050}}}

If you want every SSH communication to go through Tor, you can even say :

Host *
ProxyCommand socat STDIO SOCKS4A:localhost:%h:%p,socksport=9050




Putty is a neat suite of programs for doing Telnet, SSH, SCP, etc.
Configuration Details?




It is possible to run a (slow) vpnd through tor. How to setup this up is explained at




[:TheOnionRouter/RemailingAndTor:see Remailing: achieve strong remailing anonymity/security via. Tor and Stunnel]


For the Crazy and Lazy


If you are lazy and don't want to repeat most of the steps laid out here every time you call the program (and who would?) you can have a look at the tor aliases project.




Thomas Sjogren with Northern Security started this howto and still maintains a copy at:

Other Contributing Authors:

  • Dave Vehrs
  • Nick Mathewson
  • Thomas Hardly
  • tyranix