Adding webtunel bridges to whonix

Support
1

The best method I can get is Configure (Private) (Obfuscated) Tor Bridges, can I follow this method to add webtunel bridges to Whonix?

1 Like
2

No, unfortunately not at time of writing. It is undocumented.

Added just now a new chapter on the same wiki page:
WebTunnel

1 Like
3

WebTunnel is an undocumented pluggable transport.

See also Rationale for Unsupported Bridges.

Without volunteer development contributions to Whonix this will probably take a few years, if it ever happens.

2 Likes
4

Is it possible to manually install WebTunnel? (and is it located in lyrebird?) I think it’s possible, but can the devs maybe create a small guide on how to install it and set it up manually to work with whonix Tor since it’s not available via the debian packages?
Thanks.

1 Like
5
1 Like
6

Tails work on Debian 12 and added webtunnel in the new version. Perhaps you could try using Tails as a gateway for the workstation, or add the Tails repository to gateway and attempt to install the needed packages from there.

1 Like
7

This is a very difficult modification.

It’s most likely not a repository. It’s probably similar to this:
make TBB usable as "system Tor", so latest pluggable transports and the tor-launcher graphical user interface can be used in Whonix

1 Like
8

Yeah, thanks, but can’t you integrate the lyrebird executable with clienttransportplugin webtunnel to work with whonix? Like if you add that line into the place where you can add ‘custom user torrc‘ stuff, it doesn’t work with Tor. The gui only supports a few bridge types, but why can’t I add another one named ‘webtunnel‘? How to modify it like that, if possible, or is it not recommended or anything else?

1 Like
9
1 Like
11

I am once again asking you to consider adding support for WebTunnel bridges in Whonix.

I think you should give users the ability to use all Tor options. Tor has repeatedly stated that these bridges are currently the most effective method for hiding a connection to Tor (the same bridges are recommended in support services for all heavily censored countries). You’re doing fantastic work by adding many security tools and fingerprint‑hiding features to Whonix, but it’s crucial to hide the Tor connection as effectively as possible. You would gain millions of new users from Russia, China, Iran, and many other totalitarian countries, who now have to rely solely on Tails or the Tor Browser. Please consider this solution. This would be big news in the media if Whonix added WebTunnel support.

@arraybolt3 you are a brilliant master, and I can see how Whonix and Kicksecure have improved thanks to you! Maybe you could implement this important option. It seems that implementing it isn’t as difficult as the Tor documentation suggests

3 Likes
12

I live in a country with very strict censorship, and I also feel sorry that the Whonix developers aren’t interested in users from such countries. I agree that, in 2026, not supporting WebTunnel looks outdated. The only bridges that work even a little sometimes are Snowflake, but it will become obsolete by the end of the year due to Debian’s rapid turnover. If this trend continues, the gap between Whonix and Tor/Tails will be huge by the time Debian 14 is released. The Tor and Tails projects have a priority: to give everyone in the world access to Tor, and they’re succeeding at it. Whonix is useless in my country, whereas Tails has become very popular thanks to WebTunnel support. I don’t quite understand how one can focus on protection against keyboard fingerprinting when many Asian countries can’t use Whonix right now. Tor and Tails test their systems for robustness in those regions, but Whonix simply avoids them, providing protection tools for areas where surveillance is much weaker and a Mullvad VPN is usually enough. Is it really that hard to add Lyrebird download from the official repository, as is done with the Tor browser? I hope this will be fixed; otherwise, Whonix will remain a limited, stripped‑down version of Tor. And of course, Whonix‑Host is doomed to fall behind Tails. Running a hidden VM in Tails with WebTunnel and a fresh Lyrebird would be a far more effective and secure solution than Whonix-Host.

Developers, please pay attention to this and give people the ability to fully use Tor’s features.

2 Likes
13

Quote Community Feedback:

It is generally unhelpful to debate the priorities laid out in the future Whonix roadmap, as this diverts energy from core development. Some major suggestions might become available in the long-term or might never eventuate. See also Linux User Experience versus Commercial Operating Systems to learn about organizational and funding issues in the Open Source ecosystem.

Please be aware that @arraybolt3 works with Kicksecure, Whonix under contract and not as a volunteer. Maintaining Whonix causes expenses (money, work hours). For these reasons, please don’t tag @arraybolt3, so that I can triage/prioritize issues before assigning them to @arraybolt3.

A note [under contract] in column @arraybolt3 on Contributors and Authorship - Whonix has been added just now.

2 Likes
14

That’s understandable. Which means that manual customization is required, since no one contributed any changes to Whonix.

I tried to download lyrebird into sys-whonix and modify the torrc using the sysmaint user. After correctly setting the Clienttransportplugin line and adding a webtunnel bridge there, I logged in as the regular user and tried to connect. It doesn’t work, the error is:

Managed proxy died at state Launched

and

Managed proxy [lyrebird] having PID [XXX] terminated with status code 1

Does anyone know how to fix this?

Can this be because of the Whonix tor control panel GUI not supporting webtunnel bridges, so it “breaks”?

If that’s specifically the case, then does anyone know how to fix it? Or could there be another cause?

If we figure this out, then there could be a universal (unofficial) guide on adding lyrebird support manually to Whonix.

2 Likes
15

If you need specialists to implement a webtunnel in Whonix, and they’re not volunteering, why not host a crowdfunding campaign on a platform like Kickstarter? Set a target amount for hiring a specialist and announce the crowdfunding campaign. Payments can be made in Bitcoin, Monero, and regular currency. I think people could easily (and willingly) raise the required amount, perhaps even in a very short time.

1 Like
16

Log Analysis

Absolutely not. Graphical user interface (GUI) tools such as Tor Control Panel (TCP) won’t stay in the way of anyone configuring anything on the command line.
Related wiki chapter: Unsuitable Connectivity Troubleshooting Tools

Easier said than done. Documented just now:
Crowdfunding Model

At the time of writing, I don’t think Kickstarter supports Bitcoin, let alone Monero. See:
https://help.kickstarter.com/hc/en-us/articles/115005066433-What-forms-of-payment-can-I-use-to-make-a-pledge

Also easier said than done. These are’t readily available.

Written just now:

1 Like
17

Thanks for the knowledge, but after trying a few more configurations, the same error is present. The Tor log (sudo anon-log) is saying that there are no errors in the torrc configuration. Other bridge types also don’t work with lyrebird. The weird part is that it just doesn’t work out of the box, so it’s hard to believe that nothing overrides the configuration. Unless there is an unmet dependency. Lyrebird seems to use Go, but having it doesn’t make a difference.

1 Like
18

Tor is configured by text configuration only. And Tor text configuration is a limited amount of files that can be reviewed.

By design, GUI tools write to 1 configuration file only.

We don’t have complex configuration by Tor control protocols.

If you don’t like GUI tools you can use Whonix-Gateway CLI or uninstall GUI tools using dummy-dependency.

sudo dummy-dependency tor-control-panel

sudo dummy-dependency anon-connection-wizard

Many things can interfere. File permissions, AppArmor and systemd unit file hardening are top candidates.

2 Likes
19

@Patrick Thanks for pointing me in the right direction. After quite some trial and error, I got it working. I created a guide that people can follow, if there are any issues, please point them out. (such as: should webtunnel be run as managed or not, is giving lyrebird the rix permission in AppArmor ok?)

How to set up lyrebird to work in whonix?

First of all, login to your whonix gateway as if you are accessing a regular sysmaint session.
Run this command to open and edit the AppArmor settings:
sudo nano /etc/apparmor.d/local/system_tor
Scroll down near the end of the file, spot ## obfsproxy and make a space above it, and add this:
## lyrebird
/usr/bin/lyrebird rix,
Save the file by clicking Ctrl + X, Y, Enter.

If you want to use the latest version of Tor, then you can add the Tor Project’s official Tor repository to the gateway by following the instructions in this link:
https://support.torproject.org/little-t-tor/getting-started/installing/
Or https://support.torproject.org/little-t-tor/getting-started/apt-over-tor/ for a .onion repository.

Now you have to install lyrebird, it’s not available in any apt repository, so you have to download it manually.
You can compile it yourself following the instructions here: https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/lyrebird
Or you can use an already-compiled version by copying it from the Tor Expert Bundle, which you can download here:
https://www.torproject.org/download/tor/
Copy the correct link and use this command to download it:
scurl --proxy http://127.0.0.1:8082 https://download_url -o output.tar.gz
After downloading the correct file, extract it
tar -xvf nameofthefile.tar.gz
and run these commands from the directory in which you extracted the Bundle:
sudo cp /tor/pluggable_transports/lyrebird /usr/bin/
sudo chmod +x /usr/bin/lyrebird (to make it executable)
To run lyrebird you need Go.
sudo apt install golang-go -y

You can now shut down your whonix gateway vm.
Now boot your sys-whonix instance using the sysmaint user.
Select the “Tor User Config” GUI option.
There, add something similar to this:
ClientTransportPlugin webtunnel exec /usr/bin/lyrebird managed
Bridge webtunnel … (input a bridge or several bridges that you have, or get one from the Tor Project using your preferred method of getting them: https://support.torproject.org/tor-browser/circumvention/getting-bridges/ )

Save the changes, shut down and log in to sys-whonix as the USER and check if your Tor connection works in the Tor Control Panel. You can pick ‘None’ (bridges) as a connection method there and the default configuration file will get overwritten by your custom torrc.
You can also assign other bridge types to lyrebird such as snowflake, meek, obfs4 and webtunnel.

3 Likes