diff --git a/docs/platforms/whonix.md b/docs/platforms/whonix.md index c9bfc554..40f5892f 100644 --- a/docs/platforms/whonix.md +++ b/docs/platforms/whonix.md @@ -10,18 +10,47 @@ This functionality may be incomplete and/or dangerous if misused. Please help us ::: -Whonix uses [Onion Grater](https://www.whonix.org/wiki/Onion-grater) to guard access to the control port. We have packaged -an oniongrater configuration `cwtch-whonix.yml` with Cwtch on Linux. +## Configure the Whonix-Gateway -When launching, Cwtch on Whonix should be passed the `CWTCH_TAILS=true` environment variables to automatically configure Cwtch for running in a Whonix-like environment: +The following steps should be done in the Whonix-Gateway. -`exec env CWTCH_TAILS=true LD_LIBRARY_PATH=~/.local/lib/cwtch/:~/.local/lib/cwtch/Tor ~/.local/lib/cwtch/cwtch` +### Onion Grater -Optionally, it may be desirable to pass either or both of two additional flags: +Whonix uses [Onion Grater](https://www.whonix.org/wiki/Onion-grater) to guard access to the control port. We have packaged an onion-grater configuration [`cwtch-whonix.yml` ](https://git.openprivacy.ca/cwtch.im/cwtch-ui/src/branch/trunk/linux/cwtch-whonix.yml) which is present in the root directory of the tarball. -- `CWTCH_RESTRICT_PORTS` - forces connectivity to bind to a subset of ports `15000-15378` -- `CWTCH_BIND_EXTERNAL_WHONIX` - forces connectivity to bind to external interfaces (only supported/recommended on certain Whonix-based setups. Please open an issue if you think this should be expanded.) +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`_](https://github.com/Whonix/onion-grater/blob/master/usr/share/doc/onion-grater-merger/examples/40_cwtch.yml), therefore you can use either one. + +Enable the Cwtch onion-grater profile: +```shell +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](https://www.whonix.org/wiki/Whonix-Workstation_Firewall#Open_an_Incoming_Port). + +Use the following configuration in the file `/usr/local/etc/whonix_firewall.d/50_user.conf`: +```shell +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. + +```shell +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 +``` :::info Install Location @@ -29,76 +58,21 @@ The above command, and the below onion grater configuration assume that Cwtch wa ::: -## Onion Grater Configuration +# Removing Cwtch from Whonix -The oniongrater configuration `cwtch-whonix.yml` is reproduced below. As noted this configuration is can likely be restricted much -further. +## Remove configuration from the Whonix-Gateway -This file needs to be placed in `/usr/share/doc/onion-grater-merger/examples/` on the **Whonix Gateway** portion of he system. +The following steps should be done in the Whonix-Gateway. -You can then use `sudo onion-grater-add cwtch-whonix` to enable the onion grater configuration. - -``` -# TODO: This can likely be restricted even further, especially in regards to the ADD_ONION pattern -- exe-paths: - - '' -users: - - '*' -hosts: - - '*' -commands: - AUTHCHALLENGE: - - 'SAFECOOKIE .*' - SETEVENTS: - - 'CIRC WARN ERR' - - 'CIRC ORCONN INFO NOTICE WARN ERR HS_DESC HS_DESC_CONTENT' - GETINFO: - - 'net/listeners/socks' - - '.*' - GETCONF: - - 'DisableNetwork' - SETCONF: - - 'DisableNetwork.*' - ADD_ONION: - - '.*' - DEL_ONION: - - '.+' - HSFETCH: - - '.+' -events: - CIRC: - suppress: true - ORCONN: - suppress: true - INFO: - suppress: true - NOTICE: - suppress: true - WARN: - suppress: true - ERR: - suppress: true - HS_DESC: - response: - - pattern: '650 HS_DESC CREATED (\S+) (\S+) (\S+) \S+ (.+)' - replacement: '650 HS_DESC CREATED {} {} {} redacted {}' - - pattern: '650 HS_DESC UPLOAD (\S+) (\S+) .*' - replacement: '650 HS_DESC UPLOAD {} {} redacted redacted' - - pattern: '650 HS_DESC UPLOADED (\S+) (\S+) .+' - replacement: '650 HS_DESC UPLOADED {} {} redacted' - - pattern: '650 HS_DESC REQUESTED (\S+) NO_AUTH' - replacement: '650 HS_DESC REQUESTED {} NO_AUTH' - - pattern: '650 HS_DESC REQUESTED (\S+) NO_AUTH \S+ \S+' - replacement: '650 HS_DESC REQUESTED {} NO_AUTH redacted redacted' - - pattern: '650 HS_DESC RECEIVED (\S+) NO_AUTH \S+ \S+' - replacement: '650 HS_DESC RECEIVED {} NO_AUTH redacted redacted' - - pattern: '.*' - replacement: '' - HS_DESC_CONTENT: - suppress: true +Disable the Cwtch onion-grater profile: +```shell +sudo onion-grater-remove cwtch-whonix ``` -## Removing Cwtch +## Remove configuration from the Whonix-Workstation -You can use `sudo onion-grater-remove cwtch-whonix` to disable the Cwtch Onion Grater configuration, and then delete the Cwtch -application and the `$HOME/.cwtch` data directory. +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.