Skip to main content

Running Cwtch on Whonix

New Feature

New in Cwtch 1.13

This functionality may be incomplete and/or dangerous if misused. Please help us to review, and test.

Configure the Whonix-Gateway​

The following steps should be done in the Whonix-Gateway.

Onion Grater​

Whonix uses Onion Grater to guard access to the control port. We have packaged an onion-grater configuration cwtch-whonix.yml which is present in the root directory of the tarball.

This file needs to be placed in /usr/share/doc/onion-grater-merger/examples/40_cwtch.yml.

Whonix has also packaged the profile 40_cwtch.yml_, therefore you can use either one.

Enable the Cwtch onion-grater profile:

sudo onion-grater-add 40_cwtch

Configure the Whonix-Workstation​

The following steps should be done in the Whonix-Workstation.

Linux Firewall​

The Whonix-Workstation Firewall needs to have the possible Cwtch binding port open. Follow the upstream firewall guide.

Use the following configuration in the file /usr/local/etc/whonix_firewall.d/50_user.conf:

EXTERNAL_OPEN_PORTS+=" $(seq 15000 15378) "

Running Cwtch​

When launching, Cwtch on Whonix, some environment variables must be set:

  • CWTCH_TAILS=true - automatically configure Cwtch for running in a Whonix-like environment.
  • CWTCH_RESTRICT_PORTS=true - forces connectivity to bind to a subset of ports 15000-15378, easier to manage on the firewall configuration.
  • CWTCH_BIND_EXTERNAL_WHONIX=true - forces connectivity to bind to external interfaces (only supported/recommended on for Whonix-based setups where the machine (Workstation) which is running Cwtch is firewalled, where the only source of network is through the Gateway.
cd ~/.local/lib/cwtch
env LD_LIBRARY_PATH=~/.local/lib/cwtch/:~/.local/lib/cwtch/Tor CWTCH_TAILS=true CWTCH_RESTRICT_PORTS=true CWTCH_BIND_EXTERNAL_WHONIX=true ~/.local/lib/cwtch/cwtch
Install Location

The above command, and the below onion grater configuration assume that Cwtch was installed in ~/.local/lib/cwtch/cwtch - if Cwtch was installed somewhere else (or if you are running directly from the download folder) then you will need to adjust the commands.

Removing Cwtch from Whonix

Remove configuration from the Whonix-Gateway​

The following steps should be done in the Whonix-Gateway.

Disable the Cwtch onion-grater profile:

sudo onion-grater-remove cwtch-whonix

Remove configuration from the Whonix-Workstation​

The following steps should be done in the Whonix-Workstation.

Delete the Cwtch application directory $HOME/.local/lib/cwtch and Cwtch data directory $HOME/.cwtch.

The firewall ports should also be closed manually by removing the configuration added above and reloading the firewall.