Whonix Networking Implementation Documentation

From Whonix
< Dev
Jump to navigation Jump to search

This page documents the differences between Debian and Whonix related to networking.

Base Image[edit]

Debian installer and or various desktop environments (GNOME etc.) might be using systemd-networkd and/or network manager (GUI) to set up networking. This might differ depending on Debian flavors and/or Debian installer options.

The Debian base config assumed in this developer documentation is build-steps.d/*_create-raw-image our minimal (grml-)debootstrap created Debian image. These don’t come with any network configuration at all. Using our minimal base image would have no networking configuration to begin with.

Someone who wanted to build Whonix manually and from scratch would have to start with a minimal base Debian image. Not with for example a Debian Xfce installed with Debian installer DVD since that already comes with functional/different network configuration.



Tor Configuration and Tweaks for Anonymity Distributions[edit]

Tor config file with distribution defaults (for stream isolation, etc.), example user configurations and other tweaks required. The Tor binary itself does not get modified.

Deactivates IPv4 forwarding using /etc/sysctl.d/ IPv4 forwarding is not required for a Tor based Anonymity Distribution Gateways. Deactivating it as defense in depth to prevent leaks.

Deactivates IPv6 using /etc/sysctl.d/ There are no IPv6 Anonymity Distribution Gateways featuring an IPv6 firewall yet. Therefore deactivating it to prevent leaks.

This package is produced independently of, and carries no guarantee from, The Tor Project.


Tor is disabled by default. Users are supposed to enable Tor through setup-dist which would create file /usr/local/etc/torrc.d/40_tor_control_panel.conf with "DisableNetwork 0" or by removing the hash ('#') in front of "DisableNetwork 0" in /usr/local/etc/torrc.d/40_tor_control_panel.conf

  • DisableNetwork 1
  • VirtualAddrNetwork
  • AutomapHostsOnResolve 1
  • Log notice file /run/tor/log


Tor settings for Gateway: `ClientOnionAuthDir`, `SocksPort`s, `TransPort`, `DnsPort`, `HTTPTunnelPort`s and stream isolation settings.


Tor settings for Workstation: `SocksPort`s, `TransPort`, `DnsPort`, `HTTPTunnelPort`s and stream isolation settings. IP HARDCODED unfortunately.


Network Configuration for Whonix-Gateway[edit]

Includes etc/network/interfaces.d/30_non-qubes-whonix for Non-Qubes-Whonix-Gateway.

Sets up two network interfaces, an external one eth0 and an internal one eth1.

Provides /usr/share/whonix-gw-network-conf/network_internal_ip.txt.

DNS configuration Anonymity Linux Distribution Gateways

  • Pointing /etc/resolv.conf to
  • Whether a Anonymity Linux Distribution Gateway supports system DNS for its

own traffic in the clear or anonymized mainly depends on the Gateway's firewall.

  • Routing the workstation's system DNS through the anonymizer (also known as

Transparent DNS Proxy) or not is up to the Gateway's firewall as well.


Disable Predictable Network Interface Names as these are problematic. https://forums.whonix.org/t/whonix-14-0-0-0-7-developers-only/3449/4archive.org Disabling them as per 'zless /usr/share/doc/udev/README.Debian.gz'.

  • /dev/null /etc/systemd/network/99-default.link


Required for /etc/systemd/network/99-default.link to take effect as per 'zless /usr/share/doc/udev/README.Debian.gz'.

  • activate-noawait update-initramfs


network interfaces configuration eth0 (external network interface) and eth1 (internal network interface)

static network configuration

IP HARDCODED below but comment only. No need to change. eth0 #address

eth1 #address


No DNS configuration. Only comments. Whonix-Gateway by default does not have system default DNS. See https://www.whonix.org/wiki/Whonix-Gateway_Own_Traffic_Transparent_Proxyarchive.org and footnotes.


onion-grater systemd unit file extension

Run /usr/lib/onion-grater-merger as root to avoid permission conflicts. ExecStartPre=+/usr/lib/onion-grater-merger

Reconfigure onion-grater to listen on network interface eth1.



anonymity, privacy and security settings pre-configuration[edit]

Most settings take effect for newly created user account onlys, and not for existing user accounts.

Sets timezone to UTC.

Enables Menubar in Dolphin by default.

gnupg configuration for Anonymity Distributions:

  • Sets `use-tor` in `/etc/skel/.gnupg/dirmngr.conf`.
  • Ships Thunderbird torbirdy configuration file

`/etc/thunderbird/pref/30_whonix.js` that allows torified keyserver access.

  • Deactivates KGpg's first run wizard. Disables tip of the day. Disables KGpg's systray.

Double click instead of single click in KDE.

Deactivates maximize windows when moved to the top. In context of anonymity it might be better not to maximize the browser window (https://gitlab.torproject.org/legacy/trac/-/issues/7255archive.org). To prevent users from accidentally maximizing their browser window, it is better when KDE's feature to maximize windows when moved to the top is disabled.

Deactivates KDE's system sounds.

Disables KDE graphics effects. Disables some background processes.

Stream Isolation (proxy) settings for KDE apps for Anonymity Distributions Configures global proxy settings, which acts as a fallback if no other proxy settings are set, for KDE applications to socks IP HARDCODED above but no need to change since it is description only. Otherwise unconfigured KDE applications would use no proxy settings (Transparent Proxying) if the anonymity distribution features a transparent proxy. Useful to improve stream isolation. On the other hand, anonymity distributions not featuring transparent proxying should probably not install this package by default, because then unconfigured KDE applications should by default not be able to connect.

Sets Unlimited Scrollback in Konsole.

Disables klipper clipboard history.

Deactivates automatic updates for Package Manager APT and Apper Useful in context of networks with limited traffic quota, slow networks and anonymity distributions. In latter case, the default automatic updates interval would be too predictable (expectable amount of traffic every X), thus eventually be vulnerable for traffic fingerprinting. Disabling Apper automatic updates only takes effect for newly created user accounts. Not for existing user accounts. This is most useful to help Linux distribution maintainers setting divergent defaults.

Longer Timeouts for Package Manager APT Raising timeout and retries using configuration snippet. Useful in context of slow networks and anonymity distributions.

Ships a configuration file /etc/apt/apt.conf.d/90longer-timeouts to configure apt-get.

Ships a configuration file /etc/skel/.config/vlc/vlcrc to configure VLC to not ask for network policy at start and sets vout=xcb_x11 to enable VM compatibility out-of-the-box.

Disabled gajim update manager by default for better security since it does not verify software signatures by hiding file /usr/share/gajim/plugins/plugin_installer/__init__.py using 'config-package-dev' 'hide'.

Disables systemd-resolved during boot unless file /etc/dns-enable exists.

Disables systemd-resolved fallback DNS (which by default is set to Google).

Removes capabilities from `/bin/ping` if [security-misc](https://github.com/Kicksecure/security-miscarchive.org) is installed as ping doesn't work with Tor anyway and its capabilities are just unneeded attack surface.

Create a dummy Tor binary '/home/user/.local/share/Bisq/btc_mainnet/tor/tor' to avoid Tor over Tor.

Improves HexChat Privacy Settings

- `/usr/lib/xchat/plugins/python.so` - `/usr/lib/xchat/plugins/tcl.so` - `/usr/lib/xchat/plugins/perl.so` to `/usr/share/anon-apps-config`, so these plugins get disabled by default.

Due to technical limitations some settings only take effect for applications being started for the very first time, i.e. when the user config of that application in the user's home folder does not exist yet. Works best for new user accounts.

This package is most useful to help Linux distribution maintainers setting divergent defaults.


longer APT timeouts and more retires


Disable systemd-resolved unless file /etc/dns-enable exists.


do not default to using Google nameservers https://phabricator.whonix.org/T793archive.org https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=761658archive.org https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=761658#216archive.org https://www.freedesktop.org/software/systemd/man/systemd-resolved.service.htmlarchive.org https://forums.whonix.org/t/os-generated-network-trafficarchive.org

  • [Resolve]
  • FallbackDNS=


KDE stream isolation settings.

  • [Proxy Settings]
  • NoProxyFor=
  • ProxyType=1
  • ReversedException=false



disable session saving https://forums.whonix.org/t/kdesudo-error-popup-window-sdwdate-guiarchive.org

  • loginMode=default


Prevents Tor over Tor in Anonymity Distribution Workstations[edit]

Supposed to be installed on Workstations, which prevents installing the real Tor package from upstream (ex: Debian, The Tor Project) APT repositories. Its purpose is to prevent, running Tor over Tor.

It allows installation of packages, which depend on Tor, such as TorChat, parcimonie and torbrowser-launcher.

This package uses the "Provides: tor" field[1], which should avoid any kinds of conflicts, in case upstream releases a higher version of Tor. This won't work for packages, which depend on an explicit version of Tor (such as TorChat). This is non-ideal, since for example the torchat package will install Tor, but still acceptable, because of the following additional implementations.

Binaries eventually installed (by the tor Debian package) /usr/bin/tor as well as /usr/sbin/tor are replaced with a dummy wrapper that does nothing (dpkg-diverted using config-package-dev).

systemd-socket-proxyd listens on Tor's default ports. system Tor's, and TBB's,, which prevents the default Tor Browser Bundle or Tor package by The Tor Project from opening these default ports, which will result in Tor failing to open its listening port and therefore exiting, thus preventing Tor over Tor.

See also:

[1] See "7.5 Virtual packages - Provides" on https://www.debian.org/doc/debian-policy/ch-relationships.htmlarchive.org

This package is produced independently of, and carries no guarantee from, The Tor Project.


config-package-dev displace the following files:

  • /etc/default/tor.anondist
  • /usr/bin/tor.anondist
  • /usr/sbin/tor.anondist


/etc/X11/Xsession.d/ hook to source /usr/lib/anon-ws-disable-stacked-tor/torbrowser.sh

Add user "user" to the group "debian-tor", so user "user" can access Tor's control port. User "user" already exists thanks to the dist-base-files package.

  • addgroup --quiet user debian-tor


systemd-unit-files-generator and socat-unix-sockets configuration examples.


/etc/profile.d hook to source /usr/lib/anon-ws-disable-stacked-tor/torbrowser.sh


rsyslog configuration drop-in snippet

No longer required since no longer using rinetd.

Workaround for: 'rinetd fills up the logs until disk is full up if it cannot bind' https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=796235archive.org

  • :msg, contains, "accept(0): Socket operation on non-socket" stop


/etc/X11/Xsession.d/ hook to source /usr/lib/anon-ws-disable-stacked-tor/torbrowser.sh


Runs /usr/lib/anon-ws-disable-stacked-tor/state-files and /usr/lib/anon-ws-disable-stacked-tor/socat-unix-sockets.



Clear 'ConditionPathExists=/run/qubes-service/whonix-gateway' set by the qubes-whonix package, which is useful on the gateway but not on the workstation.

In effect the dummy Tor service will run on Whonix-Workstation.

  • ConditionPathExists=


Compatibility with system Tor package.

Overrides systemd unit file by system Tor package for compatibility so the dummy Tor binary /usr/bin/tor gets load instead.

Makes all systemctl restart reload status commands compatible with dummy Tor.


Make 'sudo service tor status' exit '0' for better compatibility.

  • RemainAfterExit=yes


  • /usr/bin/tor.anondistarchive.org
  • ~/derivative-maker/packages/anon-ws-disable-stacked-tor/usr/bin/tor.anondist
  • workstation only

dummy Tor wrapper doing nothing but wait forever and

OnionShare support for configuration option "bundled Tor".


socat-unix-sockets starter.


Emulates Tor by copying and chmodding the correct state files such as /run/tor/control.authcookie.


Generates systemd unit files in /lib/systemd/system/anon-ws-disable-stacked-tor_autogen_* which listen on common local ports used by popular Tor applications such as Tor Browser.

Redirect Whonix-Workstation port 9050 to Whonix-Gateway port 9050 and so forth.

Create a unix domain socket files such as /run/anon-ws-disable-stacked-tor/ and forward those to $GATEWAY_IP:9150 etc. See also: https://phabricator.whonix.org/T192archive.org

system Tor default SocksSocket is /run/tor/socks redirect Whonix-Workstation unix domain socket file /run/tor/socks to Whonix-Gateway port 9050

Debian /usr/share/tor/tor-service-defaults-torrc uses '/run/tor/control' Tor ControlSocket Redirect Whonix-Workstation unix domain socket file /run/tor/control to Whonix-Gateway port 9051


Environment variables for Tor Browser integration.

Prevents Tor over Tor.

Deactivate tor-launcher, a Vidalia replacement as browser extension, to prevent running Tor over Tor. https://gitlab.torproject.org/legacy/trac/-/issues/6009archive.org https://gitweb.torproject.org/tor-launcher.gitarchive.org

  • export TOR_SKIP_LAUNCH=1

The following TOR_SOCKS_HOST and TOR_SOCKS_PORT variables do not work flawlessly, due to an upstream bug in Tor Button:


(As an alternative,


could be used.) Fortunately, this is not required for Whonix by default anymore, because systemd-socket-proxyd is configured to redirect Whonix-Workstation ports IP HARDCODED but no need to change since comment only. to Whonix-Gateway to Whonix-Gateway to Whonix-Gateway to Whonix-Gateway #export TOR_SOCKS_HOST=""
#export TOR_SOCKS_PORT="9150"
#export TOR_CONTROL_PORT="9151"
this is to satisfy Tor Button just filled up with anything #export TOR_CONTROL_PASSWD='"password"'

We are not using TOR_TRANSPROXY=1 because that would break Tor Browser's per tab stream isolation. (Tor Browser talks to a Tor SocksPort and sets a socks user name and Tor is using IsolateSOCKSAuth by Tor default.) #export TOR_TRANSPROXY=1

Environment variable to configure Tor Browser to use a pre existing unix domain socket file instead of creating its own one to avoid Tor over Tor and to keep it being able to connect. systemd-socket-proxyd is being used for creation of unix domain socket file /run/anon-ws-disable-stacked-tor/ and forwarding it to to Whonix-Gateway port 9150. https://phabricator.whonix.org/T192archive.org https://gitlab.torproject.org/legacy/trac/-/issues/20111#comment:5archive.org

  • export TOR_SOCKS_IPC_PATH="/run/anon-ws-disable-stacked-tor/"
  • export TOR_CONTROL_IPC_PATH="/run/anon-ws-disable-stacked-tor/"

environment variable to skip TorButton control port verification https://gitlab.torproject.org/legacy/trac/-/issues/13079archive.org


Environment variable to disable the "TorButton" -> "Open Network Settings..." menu item. It is not useful and confusing to have on a workstation, because Tor must be configured on the Whonix-Gateway, which is for security reasons forbidden from the Whonix-Gateway. https://gitlab.torproject.org/legacy/trac/-/issues/14100archive.org https://www.whonix.org/wiki/Tor_Browser/Advanced_Users#Open_Network_Settingsarchive.org



Create folder /run/anon-ws-disable-stacked-tor.

  • d /run/anon-ws-disable-stacked-tor 0775 root root


  • /usr/sbin/tor.anondistarchive.org
  • ~/derivative-maker/packages/anon-ws-disable-stacked-tor/usr/sbin/tor.anondist
  • workstation only

dummy Tor wrapper doing nothing but wait forever.


Binding specific IP and Port for Linux Running Application[edit]

This package is probably most useful for Anonymity Distributions.

This package is produced independently of, and carries no guarantee from, The Tor Project.


Compiles /usr/lib/bindp.c to /usr/lib/libindp.so during package installation using gcc.


Network Configuration for Whonix-Workstation[edit]

Includes /etc/network/interfaces for Whonix-Workstation.

Sets up an internal network interface eth0.

DNS configuration Anonymity Linux Distribution Workstations Whether a Anonymity Linux Distribution Gateway supports anonymized system DNS for Workstation's traffic (also known as Transparent DNS Proxy) mainly depends on the Gateway's firewall.

This package is simply installing /etc/resolv.conf which points to, where an Anon-Gateway is supposed to provide a DnsPort on port 53. IP HARDCODED but no need to change because only description.

Currently relevant for Non-Qubes-Whonix only.


Disable Predictable Network Interface Names as these are problematic. https://forums.whonix.org/t/whonix-14-0-0-0-7-developers-only/3449/4archive.org Disabling them as per 'zless /usr/share/doc/udev/README.Debian.gz'.

  • /dev/null /etc/systemd/network/99-default.link


Required for /etc/systemd/network/99-default.link to take effect as per 'zless /usr/share/doc/udev/README.Debian.gz'.

  • activate-noawait update-initramfs


network interfaces configuration eth0 to communicate with Whonix-Gateway

static network configuration

IP HARDCODED but not need to change since only comment. #address


set nameserver This works different in Qubes-Whonix.

Shared by Whonix-Gateway and Whonix-Workstation[edit]


/etc/apt/sources.list.d/debian.list for Anonymity Linux Distributions[edit]

A question of distribution maintenance strategies. The more standard way would indeed be populating /etc/apt/sources.list at install or build time and leaving /etc/apt/sources.list.d alone. The idea of managing /etc/apt/sources.list.d/debian.list for the user is, the anonymity distribution maintainers can decide when it is a better "change stable to oldstable", "keep wheezy as long as needed to work out [eventual!] issues that would break during upgrade to jessie" and such.


Debian APT repository sources.list

Configured to use tor+https.

Technical notes: - Why are sources (deb-src) disabled by default?

 Because those are not required by most users, to save time while
 running sudo apt update.

- See also: https://www.debian.org/security/archive.org - See also: /etc/apt/sources.list.d/


Adds TPO's APT repository to Anonymity Linux Distributions[edit]

Comes with "deb https://deb.torproject.org/torproject.orgarchive.org stable main", The Tor Project's APT signing key.

This package is produced independently of, and carries no guarantee from, The Tor Project.


Tor Project APT repository sources.list


Qubes Configuration for Whonix-Gateway and Whonix-Workstation[edit]

This package contains all the scripts and configuration options to be able to run Whonix-Gateway and Whonix-Workstation within a Qubes environment.

Whonix-Gateway should run as a ProxyVM.

Whonix-Workstation should run as an AppVM.

Template updates over Tor.

Package: qubes-whonix-shared-packages-recommended Architecture: all Depends: qubes-core-agent-passwordless-root | dummy-dependency, qubes-kernel-vm-support, initramfs-tools, qubes-mgmt-salt-vm-connector, qubes-usb-proxy, qubes-input-proxy-sender, qubes-core-agent-thunar, qubes-core-agent-nautilus, ${misc:Depends} Description: Recommended packages for Qubes-Whonix-Gateway and Qubes-Whonix-Workstation

Recommended packages for Qubes-Whonix-Gateway and Qubes-Whonix-Workstation[edit]

A metapackage, which includes recommended packages to ensure, Qubes-Whonix standard tools are available and other useful recommended packages.

Safe to remove, if you know what you are doing.

Package: qubes-whonix-gateway-packages-recommended Architecture: all Depends: tinyproxy, yum, yum-utils, qubes-core-agent-dom0-updates, ${misc:Depends} Description: Recommended packages for Qubes-Whonix-Gateway

Recommended packages for Qubes-Whonix-Gateway[edit]

A metapackage, which installs packages, which are recommended for Qubes-Whonix-Gateway.

Safe to remove, if you know what you are doing.

Package: qubes-whonix-workstation-packages-recommended Architecture: all Depends: qubes-thunderbird, qubes-gpg-split, qubes-pdf-converter, qubes-img-converter, pulseaudio-qubes, ${misc:Depends} Description: Recommended packages for Qubes-Whonix-Workstation

Recommended packages for Qubes-Whonix-Workstation[edit]

A metapackage, which installs packages, which are recommended for Qubes-Whonix-Workstation.

Feel free to remove, if you know what you are doing.


Configure Qubes to not modify files shipped by Whonix:

  • /etc/hostname
  • /etc/hosts
  • /etc/localtime
  • /etc/timezone
  • /etc/resolv.conf


uwt Qubes-Whonix Integration

Runs only inside Qubes Template.

This configuration snippets configures uwt to wait before running apt until status file /run/updatesproxycheck/whonix-secure-proxy or status file /run/updatesproxycheck/whonix-secure-proxy-check-done exists. It will timeout after 120 seconds.

This is to determine if torified Qubes updates proxy was detected.

If torified Qubes updates proxy detection fails, it will prevent running apt and show the following warning.

WARNING: Execution of apt prevented by @file_name@ because no torified Qubes updates proxy found.

If torified Qubes updates proxy detection succeeds, it will disable apt uwtwrapper. In other words, run apt normally. Run apt without torsocks. Because apt config file. /etc/apt/apt.conf.d/01qubes-proxy will already have http proxy settings for TCP based Qubes Updates proxy Acquire::http::Proxy ""; or for qrexec based Qubes updates proxy. Acquire::http::Proxy "";


Detects read-only disks and automatically enables live-boot[edit]

Allows booting the system in live mode. Meaning, no persistent modifications will be written to the disk. All changes stay in RAM.

No claims are made with regard to anti forensics.


Make changes by ro-mode-init take effect.

  • activate-noawait update-initramfs


Secure Distributed Network Time Synchronization[edit]

Time keeping is crucial for security, privacy, and anonymity. Sdwdate is a Tor friendly replacement for rdate and ntpdate that sets the system's clock by communicating via onion encrypted TCP with Tor onion webservers.

At randomized intervals, sdwdate connects to a variety of webservers and extracts the time stamps from http headers (RFC 2616). Using sclockadj option, time is gradually adjusted preventing bigger clock jumps that could confuse logs, servers, Tor, i2p, etc.

This package contains the sdwdate time fetcher and daemon. No installation on remote servers required. To avoid conflicts, this daemon should not be enabled together with ntp or tlsdated.


hook to run /usr/lib/sdwdate/suspend-post in Qubes-Whonix.


hook to run /usr/lib/sdwdate/suspend-pre in Qubes-Whonix.


Enhances Miscellaneous Security Settings[edit]




Happening primarily in Whonix forums. https://forums.whonix.org/t/kernel-hardening/7296archive.org


TCP/IP stack hardening

Protects against time-wait assassination. It drops RST packets for sockets in the time-wait state.

  • net.ipv4.tcp_rfc1337=1

Disables ICMP redirect acceptance.

  • net.ipv4.conf.all.accept_redirects=0
  • net.ipv4.conf.default.accept_redirects=0
  • net.ipv4.conf.all.secure_redirects=0
  • net.ipv4.conf.default.secure_redirects=0
  • net.ipv6.conf.all.accept_redirects=0
  • net.ipv6.conf.default.accept_redirects=0

Disables ICMP redirect sending.

  • net.ipv4.conf.all.send_redirects=0
  • net.ipv4.conf.default.send_redirects=0
  • net.ipv6.conf.all.accept_redirects=0
  • net.ipv6.conf.default.accept_redirects=0

Ignores ICMP requests.

  • net.ipv4.icmp_echo_ignore_all=1

Enables TCP syncookies.

  • net.ipv4.tcp_syncookies=1

Disable source routing.

  • net.ipv4.conf.all.accept_source_route=0
  • net.ipv4.conf.default.accept_source_route=0
  • net.ipv6.conf.all.accept_source_route=0
  • net.ipv6.conf.default.accept_source_route=0

Enable reverse path filtering to prevent IP spoofing and mitigate vulnerabilities such as CVE-2019-14899. https://forums.whonix.org/t/enable-reverse-path-filtering/8594archive.org

  • net.ipv4.conf.default.rp_filter=1
  • net.ipv4.conf.all.rp_filter=1


Use Applications over Tor with Stream Isolation and Time Privacy[edit]

Can add "torsocks" and/or "timeprivacy" before invocation of applications when configured to do so. For example, when simply typing "apt-get" instead of "torsocks apt-get", "apt-get" can still be routed over Tor.

The uwt package comes with the following applications pre-configured to use uwtwrapper, Tor and stream isolation: - apt - apt-file - apt-get - aptitude-curses - curl - git - gpg - gpg2 - mixmaster-update - rawdog - ssh - wget - yum - yumdownloader - wormhole

To circumvent a uwt wrapper on a by case base, you append ".anondist-real" to the command, for example "apt-get.anondist-real". You can also deactivate specific or all uwt wrappers by using the stackable .d-style configuration folder /etc/uwt.d.

Uwt can only work only as good as torsocks. If torsocks is unable to route all of an application's traffic over Tor, ex. if there is an leak, there will also be one when using uwt. For that reason, it is recommended to use Anonymity Distributions, that prevent such leaks.

If an applications has native support for socks proxy settings, those should be preferred over uwt. Also refer to the TorifyHOWTO and your distribution's documentation.

Timeprivacy can keep your time private. You can create wrappers for applications and timeprivacy will feed those applications with a fake time, which obfuscates at which time you really used that applications (such as when you made the git commit or when you signed that document). It does NOT set your time zone to UTC.

This package is probably most useful for Anonymity Distributions.

This package is produced independently of, and carries no guarantee from, The Tor Project.


replace the following files with the uwt version

Using config-package-dev displace.

/etc/tor/torsocks configuration file

  • /etc/tor/torsocks.conf.anondist

Replace apt, wget, curl, ssh, onionshare, ricochet, wormhole with uwt wrapper which then calls /usr/lib/uwtwrapper.

  • /usr/bin/apt.anondist
  • /usr/bin/apt-file.anondist
  • /usr/bin/apt-get.anondist
  • /usr/bin/aptitude-curses.anondist
  • /usr/bin/curl.anondist
  • /usr/bin/git.anondist
  • /usr/bin/gpg.anondist
  • /usr/bin/gpg2.anondist
  • /usr/bin/mixmaster-update.anondist
  • /usr/bin/rawdog.anondist
  • /usr/bin/ssh.anondist
  • /usr/bin/wget.anondist
  • /usr/bin/yum.anondist
  • /usr/bin/yumdownloader.anondist
  • /usr/bin/onionshare.anondist
  • /usr/bin/onionshare-gui.anondist
  • /usr/bin/ricochet.anondist
  • /usr/bin/wormhole.anondist


/etc/profile.d hook to source /usr/lib/uwt/uwt.sh


Disable torsocks warning spam such as. [May 20 11:45:27] WARNING torsocks[2645]: [syscall] Unsupported syscall number 224. Denying the call (in tsocks_syscall() at syscall.c:165) https://phabricator.whonix.org/T317archive.org

  • Defaults:ALL env_keep += "TORSOCKS_LOG_LEVEL"


torsocks configuration

  • AllowInbound 1
  • AllowOutboundLocalhost 1
  • IsolatePID 1


uwt configuration


/etc/X11/Xsession.d hook to source /usr/lib/uwt/uwt.sh


uwt wrapped application

  • export uwtwrapper_parent="${BASH_SOURCE[0]}"
  • exec /usr/lib/uwtwrapper "$@"


uwt wrapped application


uwt wrapped application


uwt wrapped application


uwt wrapped application

  • export uwtwrapper_parent="${BASH_SOURCE[0]}"
  • exec /usr/lib/uwtwrapper "$@"


uwt wrapped application


uwt wrapped application


uwt wrapped application


uwt wrapped application


uwt wrapped application


uwt wrapped application

ricochet does not have unix domain socket file support, therefore it depends on the TOR_CONTROL_HOST and TOR_CONTROL_PORT environment variables being set. Otherwise it would try to start its own Tor instance. https://phabricator.whonix.org/T444archive.org

  • export uwtwrapper_parent="${BASH_SOURCE[0]}"
  • exec /usr/lib/uwtwrapper "$@"


uwt wrapped application




uwt wrapped application


uwt wrapped application


uwt wrapped application


uwt wrapped application


Disable torsocks warning spam such as. [May 20 11:45:27] WARNING torsocks[2645]: [syscall] Unsupported syscall number 224. Denying the call (in tsocks_syscall() at syscall.c:165) https://phabricator.whonix.org/T317archive.org



This script is used by uwtwrapper as a workaround to preserve the zeroth argument when executing programs with other wrappers like faketime or torsocks.



When running uwt wrapped applications (such as apt, wget, curl, onionshare or others) automatically prepend torsocks or bindp. I.e.

When for example apt or curl is executed, what really happens is running torsocks apt or torsocks curl.

uwtwrappers and /usr/lib/uwtwrapper are hacks to socksify applications that do not support native socks proxy settings. Used to implement Stream Isolation. https://www.whonix.org/wiki/Stream_Isolationarchive.org

In essence, uwtwrappers are installed so users can type commands like apt-get normally while transparently injecting torsocks, thereby stream isolating them.

To understand better how uwt wrappers function, you could for example open /usr/bin/apt-get.anondist in an editor.

Also useful to run: ls -la /usr/bin/apt-get*

You will see, that /usr/bin/apt-get has been replaced with a symlink to /usr/bin/apt-get.anondist. (This was done using config-package-dev.)

/usr/bin/apt-get.anondist is a uwt wrapper.

/usr/bin/apt-get.anondist-orig is the original apt-get binary.

bindp is used to make applications which listen on the internal IP by default such as onionshare (which is the right thing to outside of Whonix) listen on the external IP instead. See also:


Whonix base system miscellaneous files[edit]

This package contains several important miscellaneous files, such as /etc/issue, /etc/motd, /etc/dpkg/origins/whonix, /etc/skel/.bashrc, /usr/bin/whonix, and others.

Anonymized operating system user name `user`, `/etc/hostname`, `/etc/hosts`, `/etc/machine-id`, `/var/lib/dbus/machine-id`, which should be shared among all anonymity distributions. See also:

Sets the WHONIX environment variable to 1 as well.

Ships marker files:

  • /usr/share/whonix/marker
  • /usr/share/anon-dist/marker


Debian default /etc/hosts + Anonymity Distribution specific additions.

Currently only host.localdomain host gets added.


Firewall for Whonix-Gateway and Whonix-Workstation[edit]

iptables rules script and firewall configuration file for Whonix-Gateway and Whonix-Workstation.

Whonix-Gateway Firewall Features: - transparent proxying - stream isolation - reject invalid packages - fail closed mechanism - optional VPN-Firewall - optional isolating proxy - optional incoming flash proxy - optional Tor relay

Do not remove, unless you no longer wish to use Whonix.


Creates linux user accounts used by firewall script clearnet tunnel notunnel systemcheck sdwdate updatesproxycheck.

Creates empty /etc/whonix_firewall.d/50_user.conf which is not owned by any package if not existing.


Whonix firewall configuration file




Whonix firewall configuration file


Fail Closed Mechanism. When the Whonix firewall systemd service failed, do not bring up the network.

TODO: does not cover Qubes-Whonix since Qubes does not use networking.service. TODO: disabled, broken. Breaks networking on package upgrades. https://phabricator.whonix.org/T875archive.org



Runs /usr/lib/whonix-firewall/enable-firewall.

On Whonix-Gateway or Whonix-Workstation (if /usr/share/anon-gw-base-files/gateway or /usr/share/anon-ws-base-files/workstation exists), loads Whonix Firewall.

(Does nothing inside Qubes Templates.)

If loading Whonix Firewall fails, creates /run/anon-firewall/failed.status.


firewall starter wrapper


firewall script


firewall script


Wrapper to start firewall and create failure status files on failure.


stream isolation developer test script

Editing this Page[edit]

This page is manually written but contains auto generated code documentation from this wiki template.

Template:Dev/Project Networking

Do not bother editing anything below since these would be lost next time these are re-generated. Instead, modify the comments in Whonix source code on github.

Forum Discussion[edit]


We believe security software like Whonix needs to remain open source and independent. Would you help sustain and grow the project? Learn more about our 12 year success story and maybe DONATE!