A list of applications which currently require onion-grater can be found here: Special:WhatLinksHere/Template:Control_Port_Filter_Python_Profile_Add

onion-grater Warning[edit]

The following onion-grater warning is shown for all applications that require it.

This application requires incoming connections through a Tor onion service. Supported Whonix-Gateway ™ modifications are therefore necessary for full functionality; see instructions below.

For better security, consider using Multiple Whonix-Gateway ™ and Multiple Whonix-Workstation ™. In any case, Whonix ™ is the safest choice for running it. ^[1]

Add Profile[edit]

Extend the onion-grater whitelist in Whonix-Gateway ™ (sys-whonix).

On Whonix-Gateway ™. ^[2] ^[3]

Add onion-grater profile.

sudo onion-grater-add 40_onion_authentication

sudo onion-grater-add 40_onion_authentication

Source Code[edit]

Original upstream by Tails:

Fork by Whonix ™:

Whonix ™ supplementary:

Footnotes[edit]

↑
Security considerations:
- By using Whonix ™, additional protections are in place for greater security.
- This application requires access to Tor's control protocol.
- In the Whonix ™ context, Tor's control protocol has dangerous features. The Tor control command GETINFO address reveals the real, external IP of the Tor client.
- Whonix ™ provides onion-grater, a Tor Control Port Filter Proxy - filtering dangerous Tor Control Port commands.
- When this application is run inside Whonix ™ with an onion-grater whitelist extension, this will limit application rights to Tor control protocol access only. Non-whitelisted Tor control commands such as GETINFO address are rejected by onion-grater in these circumstances.
- During the application's normal operations it should not attempt to use dangerous Tor control commands such as GETINFO address. In the event the application or Whonix-Workstation ™ are compromised, this command would be rejected.
- In comparison, if the application is run on a non-Tor focused operating system like Debian, it will have unlimited access to Tor's control protocol (a less secure configuration).
- If the (non-)Whonix platform is used to host onion services, then running applications are more vulnerable to attacks against the Tor network compared to when Tor is solely used as a client; see also Onion Services Security.
In conclusion, Whonix ™ is the safest and correct choice for running this application.
↑ Using /usr/local/etc/onion-grater-merger.d/ because that onion-grater settings folder is persistent in Qubes-Whonix ™ TemplateBased ProxyVMs i.e. Whonix-Gateway ™ (commonly called sys-whonix). Non-Qubes-Whonix ™ users could also utilize /etc/onion-grater-merger.d/. Qubes-Whonix ™ users could also utilize /etc/onion-grater-merger.d/ but then /etc/onion-grater-merger.d/ must be made persistent, which means doing this procedure inside the Whonix-Gateway ™ TemplateVM (commonly called whonix-gw-16) and then restarting the Whonix-Gateway ™ ProxyVM or using bind-dirs ^[archive]. Both techniques are more complicated than simply using /usr/local/etc/onion-grater-merger.d/, since it is persistent either way. Further, it even allows multiple Whonix-Gateway ™ ProxyVMs based on the same Whonix-Gateway ™ TemplateVM; for example, one Whonix-Gateway ™ ProxyVM extending and relaxing onion-grater's whitelist and the other Whonix-Gateway ™ ProxyVM having the default onion-grater whitelist which is more restrictive.
↑
Previously manual instructions. No longer needed. onion-grater-add automates that.
```
sudo mkdir -p /usr/local/etc/onion-grater-merger.d/
```
sudo mkdir -p /usr/local/etc/onion-grater-merger.d/
Symlink the onion-grater profile to the onion-grater settings folder.
```
sudo ln -s {{{filename_new}}}.yml /usr/local/etc/onion-grater-merger.d/
```
sudo ln -s {{{filename_new}}}.yml /usr/local/etc/onion-grater-merger.d/
Restart onion-grater.
```
sudo service onion-grater restart
```
sudo service onion-grater restart