Configure (Private) (Obfuscated) Tor Bridges

From Whonix

Bridges Description and User Groups[edit]


Info If a website cannot be reached over Tor, this does not necessarily relate to network level censorship that requires a bridge to be configured; it may relate to blacklisting of Tor IP addresses by the server. In that case, simple bypass methods usually succeed in circumventing censorship by destination servers. It is rarely necessary to combine Tor with a proxy, VPN or SSH tunnel in order to access content or services that are blocked.

When Tor is used with Whonix ™ in the default configuration, anybody observing the flow of network traffic from the Internet connection can determine that Tor is being used. Potential observers include the Internet Service Provider (ISP), advanced adversaries, censorship enforcement bodies and other interested parties.

Tor bridges ("Tor bridge relays") are alternative entry points to the Tor network, not all of which are listed publicly. Using a bridge makes it harder, but not impossible, for the ISP to determine a user is connecting to Tor.

Intended User Groups[edit]

Info Tor non-functionality is often related to local configuration problems rather than ISP or state-level censorship.

For the majority of Whonix ™ users, connecting to Tor with the default configuration is appropriate and will work successfully. The minority of users requiring a bridge normally fall into three categories: [1]

  • Tor is blocked, and some way - any way - to reach the network has to be found. The adversary is not very dangerous, but very annoying.
  • Tor may or may not be blocked, but the user is trying to hide the fact they're using Tor. The adversary may be extremely dangerous.
  • Other bridge users: Testing whether the bridge works (automated or manual), probing, people using bridges without their knowledge because they came pre-configured in their bundle.

The first group of users is only concerned with circumventing Tor censorship that is based on IP address or fingerprinting of protocols. Circumvention is necessary because Whonix ™ would otherwise be rendered useless for most activities except working offline on documents and so on, since all Internet traffic is routed through Tor by default. This group is not worried about hiding the use of Tor and will need to use bridges or possibly other circumvention tools.

The second user group is unable to safely start Whonix ™ in the default configuration due to Tor being considered dangerous or suspicious in their locality. In this case private bridges or a VPN/SSH tunnel should be utilized instead of public obfuscated bridges, as this makes it harder (not impossible) to detect Tor. [2]

Note that meek_lite pluggable transports may be necessary to deal with highly aggressive ISP censorship or national firewalls, like those found in China and the Middle East.

The third group is only concerned with testing bridge connections.

Before Configuring a Bridge[edit]

Ambox warning pn.svg.png Warning: Bridges are important tools that work in many cases but they are not an absolute protection against the technical progress an adversary might make in identifying Tor users. Using bridges might be advisable to prevent identification as a Tor user, but the Tor Project's bridges documentation is primarily focused on censorship circumvention, that is, overcoming attempts by ISPs or government to block Tor use.

Users falling into one of the three groups described above should consider using Tor bridges. Before taking this step, please review The Tor Project's dedicated bridges page to better understand their design and operation. It is also recommended to review how Obfsproxy works, since it is the most commonly used application for connecting bridges.

Always remember that bridges are not bullet-proof. The following is a reminder about bridge versus non-bridge anonymity:

Quote Roger Dingledine, cofounder of Tor:

[...] Bridges are less reliable and tend to have lower performance than other entry points. If you live in a uncensored area, they are not necessarily more secure than entry guards. [...]

Quote question:

If that is true, that also means, that bridge users are sufficiently more vulnerable to attacks, which are circumvented by entry guards?

Quote Roger Dingledine, cofounder of Tor:

[...] They're probably more vulnerable, but I don't know if I'd say "sufficiently". [...]

If a user is only concerned with connectivity (getting Whonix connected) and there is no need to Hide Tor and Whonix from your ISP and/or local ISPs do not usually hinder connections to the public Tor network, then something simpler than Bridges can be tried. See Better Connectivity without Real Censorship Circumvention.

Additional Information and Recommendations[edit]

Info For safety reasons, the first run of Whonix ™ will not automatically connect to the public Tor network. Instead, user networking decisions are guided by Anon Connection Wizard which automatically starts.

When deciding on the type of bridge to configure, it is recommended to:

  • Prefer obfuscated bridges, since they are harder to identify than other bridges.
  • Use less well-known bridges, since it is safer. [3]
  • Consider whether Hiding Tor and Whonix ™ from your ISP is advisable in your circumstances.
  • Avoid using a meek provider that also runs DNS core servers, like Google's (now defunct) bridge. [4]
  • Note that domain fronting has been pulled by Google and Amazon, limiting the meek_lite pluggable transport options.
  • For greater safety, use a private obfuscated bridge bridge run by a trusted friend or organization in a different country. In this case "private" means that the bridge is configured with the option PublishServerDescriptor 0. [5]

Finding a Bridge and Choosing the Right Protocol[edit]

In order to use bridges, the address of at least one bridge must be known in advance. It is preferable to have a private obfuscated bridge because the alternative -- public obfuscated bridges -- are more likely to be censored, since they are publicly listed. The Tor Project distributes public bridge addresses in several ways, including from their website and via email. The easiest way to find a list of public bridges is from The Tor Project Bridge Database.

In early 2017, The Tor Project advice regarding recommended bridges changed: [6]

... in Tor Browser to obfs4, given that we now have several high capacity obfs4 bridges and obfs4 is more likely to work in more regions than obfs3."

As time has gone on, more obfs4 bridge operators have come online, and obfs4 is now routinely recommended by Tor developers over obfs3, because the former: [7]

... should be able to defend more effectively against active probing.

Also see: obfs4 Transport Evaluation. [8]

The Tor Project provides a database of public obfs3 bridges and public obfs4 bridges. A more exhaustive list of public obfuscated bridges is available at The Tor Project Bridge Database. It is not recommended to use obfs and obfs2 bridges, which: [9]

... are now deprecated and were replaced by obfs3 . . . and obfs4.

Do not select the "IPv6 compatible" check box when sourcing bridges from the database, as they cannot be used in Whonix ™ yet.

How to Use Bridges in Whonix ™[edit]

This section will explain how to use bridges in Whonix ™ 14 and above.

It is possible to configure obfs3, obfs4, and meek_lite bridges.

For most users, the Anon Connection Wizard GUI application is recommended. Advanced users also have the option of Manual Bridge Configuration.

1. Start Anon Connection Wizard.

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q")Whonix-Gateway ™ ProxyVM (commonly named sys-whonix)Anon Connection Wizard

If you are using a graphical Whonix-Gateway ™, complete the following steps.

Start MenuApplicationsSystemAnon Connection Wizard

If you are using a terminal Whonix-Gateway ™, type.

kdesudo anon-connection-wizard

2. Use the Bridge Configuration Page

Option 1: Anon Connection Wizard has some built-in bridges. To use them, complete the following steps.

Select "Configure" in the beginning pageSelect "I need Tor bridges to bypass the Tor censorship" Select "Connect with provided bridges" Select a transport type that is suitable.

Info Tip: If it is unknown which transport type is the most suitable or likely to work, then simply try them all until one is functional. It is recommended to first start with obfs4, and then only try meek if it does not work.

Option 2: If none of the default bridges work, the user can try to obtain a set of bridges manually. See Finding a Bridge and Choosing the Right Protocol. After obtaining a set of Tor bridges, complete the following step.

Select "Configure" in the beginning pageSelect "I need Tor bridges to bypass the Tor censorship"Select "Enter custom bridges"Copy and paste the set of bridges to that input box(one bridge per line)


Check Tor Network Connection is Using a Tor Bridge[edit]

Concerned bridge users can complete a simple check.

1. Open Nyx as follows.

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q")Whonix-Gateway ™ ProxyVM (commonly named sys-whonix)Nyx - Status Monitor for Tor

If you are using a graphical Whonix-Gateway ™, complete the following steps.

Start MenuApplicationsSystemNyx - Status Monitor for Tor

If you are using a terminal Whonix-Gateway ™, type.


2. Use the right arrow button to navigate to page 2 of 5 in Nyx.

3. If a bridge is in use, the circuit information will be similar to this. UNKNOWN 1 / Guard

4. If a bridge is not in use, the circuit information will be similar to this.

IP Nickname 1 / Guard

The IP is the real IP (not of the Guard, and the Nickname is the name of that Guard relay.

5. Exit Nyx by pressing the following.


Connection Issues[edit]

After configuration, connection problems can relate to firewall settings that block outgoing connections to the ports provided by the bridge. To check the port the bridge is using, see the following example.


In this example, the IP address is, while the the port is 22321.

Try using a (private) (obfuscated) bridge that uses port 80 or 443, as these ports are mostly used for web browsing and therefore usually unblocked.

Trying Packet Size and Timing Obfuscation for obfs4[edit]

If a provided obfs4 bridge does not work, the user can try enabling packet size and timing obfuscation by changing the iat-mode value in each last line to either 1 or 2. [10]

Better Connectivity without Real Censorship Circumvention[edit]

If a user is only concerned with connectivity (getting Whonix connected) and there is no need to Hide Tor and Whonix from your ISP and/or local ISPs do not usually hinder connections to the public Tor network, then something simpler than Bridges can be tried.

The following setting only establishes Tor connections to public Tor network relays that listen on ports 80 and 443.

1. Edit the Tor configuration file.

Open /usr/local/etc/torrc.d/50_user.conf.

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q")Whonix-Gateway ™ ProxyVM (commonly named sys-whonix)Tor User Config (Torrc)

If you are using a graphical Whonix-Gateway ™, complete the following steps.

Start MenuApplicationsSettings/usr/local/etc/torrc.d/50_user.conf

If you are using a terminal-only Whonix-Gateway ™, complete the following steps.

sudo nano /usr/local/etc/torrc.d/50_user.conf

2. Add the following setting. [11]

FascistFirewall 1

3. Save the file and have the changes take effect.

Reload Tor.

After editing /usr/local/etc/torrc.d/50_user.conf, Tor must be reloaded for changes to take effect.

Note: If Tor does not connect after completing all these steps, then a user mistake is the most likely explanation. Recheck /usr/local/etc/torrc.d/50_user.conf and repeat the steps outlined in the sections above. If Tor then connects successfully, all the necessary changes have been made.

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q")Whonix-Gateway ™ ProxyVM (commonly named 'sys-whonix')Reload Tor

If you are using a graphical Whonix-Gateway ™, complete the following steps.

Start MenuApplicationsSettingsReload Tor

If you are using a terminal-only Whonix-Gateway ™, press on Expand on the right.

Complete the following steps.

Reload Tor.

sudo service tor@default reload

Check Tor's daemon status.

sudo service tor@default status

It should include a a message saying.

Active: active (running) since ...

In case of issues, try the following debugging steps.

Check Tor's config.

sudo -u debian-tor tor --verify-config

The output should be similar to the following.

Sep 17 17:40:41.416 [notice] Read configuration file "/usr/local/etc/torrc.d/50_user.conf".
Configuration was valid

The procedure is complete.

Missing ClientTransportPlugin Line[edit]

When a user has configured the following.

bridge obfs4 ...:... ... cert=... iat-mode=0

But forgot to add the corresponding line.

ClientTransportPlugin obfs4 exec /usr/bin/obfs4proxy

Then warnings will only be shown in logs.

[warn] We were supposed to connect to bridge '...:...' using pluggable transport 'obfs4', but we can't find a pluggable transport proxy supporting 'obfs4'. This can happen if you haven't provided a ClientTransportPlugin line, or if your pluggable transport proxy stopped running.

Missing ClientTransportPlugin Executable[edit]

[warn] Could not launch managed proxy executable at '/usr/bin/obfs4proxy' ('No such file or directory').

Deprecated Tor Pluggable Transports[edit]


scramblesuit: Unrecommended (see footnote). Use the provided obfs4 instructions instead. [12]


flashproxy: Unrecommended (see footnote). Use the provided obfs4 instructions instead. [13]

See Also[edit]


  2. Over time, censors have gotten better at detecting Tor network traffic between the client and the first hop, even with the use of more advanced pluggable transports. There is a cyber-censorship arms race in effect.
  3. Some bridge addresses are freely provided by the Tor website or by email upon request, meaning adversaries likely use these methods to obtain bridge information. The Tor Project has some protection against adversary threats, but they are far from perfect.
  4. Google sees forty percent of Tor Exits' DNS traffic and so using them as a bridge aids website fingerprinting attacks. That said, there is evidence that website fingerprinting is more difficult to mount than previously thought. See: The Effect of DNS on Tor’s Anonymity
  5. Tor manual: PublishServerDescriptor Without this option set, The Tor Project can learn about the bridge and may distribute its address to others, potentially handing this information to an adversary seeking to generate a list of all known bridges.
  8. The obfs4 protocol was developed and is in the process of being deployed by the Tor Project in response to the vulnerability of the obfs3 protocol to detection via active probing attacks. It is expected to supersede the obfs3 protocol as the front-line Pluggable Transport used by most Tor users.

  10. 1 = Enabled: ScrambleSuit-style with bulk throughput optimizations. 2 = Paranoid: Each IAT write will send a length sampled from the length distribution (expensive). See:
  12. Quote intrigeri (Tails developer):

    On tor-talk we've been told "You shouldn't prioritise ScrambleSuit because it is superseded by obfs4", and there are now pressing plans in the Tor Project to deprecate obfs2 and obfs3 in favour of obfs4. Hence rejecting this ticket, and focusing on #7980 [obfs4 support] instead.

    Also see Tor Announcement under heading "obfs4 and scramblesuit"

  13. Flashproxy has been removed from Tor Browser, therefore it can be considered deprecated.


Whonix ™ Bridges wiki page Copyright (C) Amnesia <amnesia at boum dot org>
Whonix ™ Bridges wiki page Copyright (C) 2012 - 2019 ENCRYPTED SUPPORT LP <>

This program comes with ABSOLUTELY NO WARRANTY; for details see the wiki source code.
This is free software, and you are welcome to redistribute it under certain conditions; see the wiki source code for details.

No user support in comments. See Support. Comments will be deleted after some time. Specifically after comments have been addressed in form of wiki enhancements. See Wiki Comments Policy.

Add your comment
Whonix welcomes all comments. If you do not want to be anonymous, register or log in. It is free.

Random News:

Bored? Want to chat with other Whonix users? Join us in IRC chat (Webchat).

https | (forcing) onion

Follow: Twitter | Facebook | | Stay Tuned | Whonix News

Share: Twitter | Facebook

This is a wiki. Want to improve this page? Help is welcome and volunteer contributions are happily considered! Read, understand and agree to Conditions for Contributions to Whonix ™, then Edit! Edits are held for moderation.

Copyright (C) 2012 - 2019 ENCRYPTED SUPPORT LP. Whonix ™ is a trademark. Whonix ™ is a licensee of the Open Invention Network. Unless otherwise noted, the content of this page is copyrighted and licensed under the same Freedom Software license as Whonix ™ itself. (Why?)

Whonix ™ is a derivative of and not affiliated with Debian. Debian is a registered trademark owned by Software in the Public Interest, Inc.

Whonix ™ is produced independently from the Tor® anonymity software and carries no guarantee from The Tor Project about quality, suitability or anything else.

By using our website, you acknowledge that you have read, understood and agreed to our Privacy Policy, Cookie Policy, Terms of Service, and E-Sign Consent. Whonix ™ is provided by ENCRYPTED SUPPORT LP. See Imprint.