Version 421 (modified by karsten, 6 years ago) (diff)

Name changed from TheOnionRouter/TorifyHOWTO to doc/TorifyHOWTO

Copyright (c) 2004 Thomas Sjogren.
Copyright (C) 2004, 2005, 2006, 2007 Contributors
Distributed under the MIT license, see Legal Stuff for a full text.

Torifying software HOWTO

This document explains how to configure particular programs to use Tor. It was originally written for a Linux/UNIX environment, but it should include some instructions for Windows and OS X users too. Please 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. One note: use only link identifiers which start with a letter or the underscore character (_) and don't use identifiers with spaces inside them. Things like that make the page invalid (X)HTML and nobody wants that.

Basic Configuration Issues

Unix and Linux Configuration

First, we assume you installed Privoxy or Polipo. Many applications can be set to use an http proxy, and that will make your life much easier.

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

Mac OSX Configuration

First, we assume that you downloaded the Vidalia Bundle and not the Browser Bundle. Vidalia comes with Tor and Polipo. Polipo is a pre-configured HTTP and HTTPS proxy server. Using it we can connect everything on our Mac that requires an internet connection to run through Tor!

Once Vidalia is installed open System Preferences, and open up your Network settings. Choose the network connection on the left hand side that you use to connect to the internet, and then click on the advanced button near the bottom right of the window. Go to the Proxies Tab.

You need to Select and set both the HTTP Web Proxy, and the HTTPS Secure Web Proxy server. Click on the proxy you are setting (remember to set both of them) Set the Web Proxy Server to: "localhost" without the quotes and set the Port to 8118. It is important that you set both the HTTP, and HTTPS proxies to these settings, otherwise only some of your data will be sent through Tor.

About torsocks allows you to use most socks-friendly applications in a safe way with Tor. It ensures that DNS requests are handled safely and explicitly rejects UDP traffic from the application you're using.

Once you have installed torsocks, just launch it like so:

  usewithtor [application]

So, for example you can use ssh to a by doing:

  usewithtor ssh username @ 

or launch pidgin by doing:

  usewithtor pidgin 

An alternative to usewithtor is torsocks:

  torsocks pidgin

The tables below list applications that usewithtor/torsocks will send through Tor. At the moment a 100% guarantee of safe interoperability with Tor can only be given for a few of them. This is because the operation of the applications and the data they transmit has not been fully researched, so it is possible that a given application can leak user/system data at a level that neither Tor nor torsocks can control.

The following administrative applications are known to be compatible with usewithtor:

Application 100% Safe DNS Comments
ssh M Y Potential for identity leaks through login.
telnet M Y Potential for identity leaks through login and password.
svn M Y
gpg M Y gpg --refresh-keys works well enough.

The following messaging applications are known to be compatible with usewithtor:

Application 100% Safe DNS Comments
pidgin M Y Potential for identity leaks through login and password.
kopete M Y Potential for identity leaks through login and password.
konversation M Y Potential for identity leaks through login and password.
irssi M Y Potential for identity leaks through login and password.
silc M Y Potential for identity leaks through login and password.

The following email applications are known to be compatible with usewithtor:

Application 100% Safe DNS Comments
claws-mail M Y in German or in English
thunderbird N Y Probable identity leaks through javascript, mail headers. Potential for identity leaks through login, password.

The following file transfer applications are known to be compatible with usewithtor:

Application 100% Safe DNS Comments
wget N N Probable identity leaks through http headers. Leaks DNS and connects directly in certain cases when used with polipo and torsocks.
ftp M Y Passive mode works well generally.

Table legend:

DNS: DNS requests safe for Tor?
           N - The application is known to leak DNS requests when used with torsocks.
           Y - Testing has shown that application does not leak DNS requests.
100% Safe: Fully verified to have no interoperability issues with Tor?
           N - Anonymity issues suspected, see comments column.
           M - Safe enough in theory, but either not fully researched or anonymity can be compromised 
               through indiscreet use (e.g. email address, login, passwords).
           Y - Application has been researched and documented to be safe with Tor.

Differences between torsocks and tsocks

A complete history of changes is maintained in the The initial working copy of torsocks was obtained through the following steps in June 2008:

To help with reconstructing the above steps a list of applied patches is available in the subdirectory of the torsocks tree.

Enhancements unique to torsocks

The first release of torsocks contained the following enhancements:

  • Torifying reverse dns requests through gethostbyaddr()
  • Blocking of UDP traffic from sendto() and its variants.
  • Use of Tor-friendly defaults if no configuration file available.
  • The addition of all RFC defined private address ranges to the default configuration.

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 Socks and DNS for more information.

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

About dante

As the tsocks package appears to be unmaintained since 2002, you may want to consider alternatives. The dante proxy package includes a SOCKS5 client that can do proper name resolution over tor, which is required to be able to access .onion addresses.

Put the following lines into /etc/socks.conf

resolveprotocol: fake
route { 
        from:   to: .   via: port = 9050
        protocol: tcp
        proxyprotocol: socks_v5

example usage is then socksify lynx http://anegvjpd77xuxo45.onion/services/

About 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 for details.

Socat on OpenBSD

For enhanced security you can use socat like this:

## 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. An example policy for IRC can be found at /SystracePolicy

About OnionCat

OnionCat is software that allows users to tunnel TCP, UDP, ICMP or any other protocol through Tor.

It is now possible to tunnel more than TCP through Tor using OnionCat. OnionCat uses an IPv6 VPN-like TAP/TUN tunneling device.

More OnionCat information can be found at the OnionCat homepage, OnionCat download page, and through Tor at the Hidden Wiki.

How to torify several programs

The following pages have good explanations of how you can configure programs to use Tor. Please follow the below mentioned links.



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


Thomas Sjogren with Northern Security started this howto. Other Contributing Authors:

  • Dave Vehrs
  • Nick Mathewson
  • Thomas Hardly
  • tyranix
  • thalunil
  • Bogdan Drozdowski (FTP stuff, 3proxy stuff with great help from it's author - 3APA3A, Gadu-Gadu, TB, SVN, Yum and KDE stuff)