TorBox v.0.4.2 released — hardening

Again, thanks to several approaches by nyxnor, the core changes in TorBox v.0.4.2 is about hardening it (see also our discussion here). Our goal is to offer users in authoritarian countries the safest possible way to install and use TorBox. That said, I want to remind you once more that it is strongly advised not to use TorBox if your well-being depends on your anonymity. In such a situation, it is advisable to use Tails.

The hardening of TorBox also slightly changes the first time start procedure. After finishing the installation with the installation script or with flashing the image file of the SD Card (at least 8 Gb are necessary), login to the TorBox by using a  SSH client ( on a WiFi client and on a cable client) or a web browser ( on a WiFi client and on a cable client) is mandatory, because TorBox will ask the user during its first start if he wants to activate OBFS4 bridges for hiding the use of tor. The integrated OBFS4 bridges should help with that, although patience is necessary because that process could easily take 5 minutes to be successful. Also, activating OBFS4 bridges can be problematic behind a tightly configured (see more here). However, if you cannot connect to the Tor network yet, don’t panic – your selection is saved, and you can choose safely entry 5-10 in the main menu (we will improve the usability with the next version). This is only necessary during the first start after flashing the TorBox image on the SD cards. However, you can change your decision and configure the use of bridges later in the Countermeasure sub-menu.

After finishing the installation with the installation script or with flashing the image file during the first start-up, TorBox will ask the user, if he wants to activate OBFS4 bridges (remark: the dialogue box will slightly differ if installed with the installation script).

TorBox Image (about 910 MB): v.0.4.2 (02.08.2021) – SHA-256 values
TorBox Menu only: v.0.4.2 (02.08.2021) – SHA-256 values

Since we had to install additional software packages and update the configuration files, we recommend using the new image rather than updating an existing system. However, we have added a short guide at the end of this post for those who absolutely must update from the previous version (not older!).

Changelog: v.0.4.1 (13.06.2021) –> v.0.4.2 (02.08.2021)
  • IMPORTANT: Installing TorBox requires at least an 8 GB SD Card.
  • Update: The system is based on Raspberry Pi OS “Buster” Lite with a Linux Kernel 5.10.49 and Tor version Tor version fixes several security issues, including a denial-of-service attack against onion service clients and another denial-of-service attack against relays. The 0.4.6.x series includes numerous features and bugfixes, including a significant improvement to our circuit timeout algorithm that should improve observed client performance and a way for relays to report when they are overloaded. 
  • Update: Internal list of OBFS4 bridges is actualized, and the Meek-Azure, as well as the Snowflake configurations are updated in torrc based on the Tor Browser 10.5.2.
  • Update: The Adafruit’s PiTFT display installer.
  • New: The install scripts were extensively rewritten to be more reliable and secure in highly authoritarian countries. Tor will only be activated after a restart and a login by SSH or a web browser. This gives the user the possibility to start pluggable transports and bridges from the beginning to hide the use of tor in a better way and improve the user’s security. These improvements were proposed and highly influenced by nyxnor. Also, the installation script is more configurable, and these configurations will be stored into run/ after the installation.
  • New: Optional but highly recommended, automatic counteractions on log related events can be activated in the Countermeasure sub-menu. These counteractions should avoid the downtime of the connection to the tor network and give a better user experience, especially on connections with lower bandwidth. Most likely, this feature will be implemented as default in the next TorBox version. However, we are dependent on your feedback on this new feature. For more information, see under “Test and play with the ‘automatization’ feature“.
  • New: Wifi driver for RTL8812bu for Raspberry Pi OS added and for Debian/Ubuntu updated.
  • Fixed: Access on the Tor Control port from the clients produces a warning message in the tor log. Even if we don’t assess this as a security risk, to avoid the warning message, access on the Tor Control Port from the clients is disabled by default but can be activated in the Configuration sub-menu
  • Improved: By default, all access to a tor related URL ( will be done through tor for security reasons of users in highly authoritarian countries. This includes tor and Torbox menu updates as well as bridge fetching and checking. If a connection through tor is not possible, the user is asked if it is safe to access the URL directly. If the user agrees, the local DNS resolution will be made through public name servers to avoid cheap censorship mechanisms (for more information, see here); if the user disagrees, the access on the tor related URL is blocked.
  • Improved: The file run/ is modified to a configuration file. The public name servers and the connectivity-check URL can be changed there and are used by every script (for more information, see here).
  • Improved: Configuring the TorBox bridge relay allows to set the bridge distribution method (requested by DEC-entralized, see details in the commit d5b0045eec2e79c60dfd33b0239a5d1e4291597f).
  • Improved: The configuration of the TorBox bridge relay can also be changed when the OBFS4 bridge relay is running. No deactivation before and activation after the changes are necessary anymore.
  • Improved: Pressing ENTER in the TorBox bridge relay configuration dialogue doesn’t set the default values but the latest used ones.
  • Improved: The installations scripts and the compatibility for Debian and Ubuntu systems as well as for 64 bit systems.
  • Improved: We have a new way to set the hostname, which should avoid error messages.
  • Removed: We don’t install tor from the Torproject repository anymore. As a fallback, a LTS version of tor is installed from the Raspberry Pi OS and the Debian repository (depending on your system), which is replaced from the latest stable version from the Tor’s Github Repository. This gives us a fallback – if someone uses the installation script and Tor’s Github Repository is blocked, the LTS version of tor is still installed, and the user can update to a newer version later through tor. So far, this is the best way to solve the „chicken or the egg“ problem.
  • Removed: The new_ident script is replaced by tor-prompt commands in the menu script (SIGNAL NEWNYM).
  • Experimental: Vanguards – Guard discovery and related traffic analysis protection – added (mentioned by nyxnor, see details in issue #72). Vanguards are optional and have to be activated in the Countermeasure sub-menu.
How to update from TorBox v.0.4.1 (13.06.2021)?

To update a TorBox v.0.4.1 (13.06.2021) installation, you can perform the following tasks. This deletes all your custom made configurations but does not alter your bridge relay keys. Nevertheless, we recommend, if possible, using the new image.

  1. Please, make sure that TorBox has Internet connectivity.
  2. Update the system: Go to the Update and Reset sub-menu, update the base system and the TorBox menu (entries 1 and 5).
  3. To ensure that all necessary packages are installed, execute the following commands (please, make sure that you copy the entire line!):
    sudo apt-get -y install hostapd isc-dhcp-server usbmuxd dnsmasq dnsutils tcpdump iftop vnstat debian-goodies apt-transport-https dirmngr python3-pip python3-pil imagemagick tesseract-ocr ntpdate screen git openvpn ppp shellinabox python3-stem raspberrypi-kernel-headers dkms nyx obfs4proxy apt-transport-tor build-essential automake libevent-dev libssl-dev asciidoc bc devscripts dh-apparmor libcap-dev liblzma-dev libsystemd-dev libzstd-dev quilt zlib1g-dev
  4. Update tor: Go to the Update and Reset sub-menu again and actualize the the TorBox menu (entry 4).
  5. Install Vanguards, if you want to use it:
    sudo bash install/
  6. Replace the changed configuration files:
    # Backup in case
    sudo cp /etc/tor/torrc /etc/tor/torrc.bak
    # ATTENTION: This will overwrite your modifications as well as the configuration for the OBFS4 bridge relay
    # If you run a bridge relay use "backup/restore the Bridge Relay configuration"
    sudo cp etc/tor/torrc /etc/tor/
    cp etc/system/system.d/rc.local /etc/system/system.d/
    The commands above should work. Alternatively, you could also go to the Update and Reset sub-menu and reset the entire TorBox configuration from there (entry 8).
  7. Reboot TorBox.
Your feedback is welcome!!

We hope this version pleases you. However, we are dependent on feedback. It is not just about fixing bugs and improving usability, but also about supporting additional interfaces and hardware in future releases:

  • What do you like?
  • What should be improved (why and how)?
  • What would you like to see next? Which features do you request?

With the TorBox GitHub repository, it is straightforward for everyone to report issues or to change the code and to propose it in a pull request. Because we continue to travel around, it sometimes needs a little more time to address the issues and proposals. 

Known problems and bugs
  • BUG: The current image file is built with Linux Kernel 5.10.52. Unfortunately, we didn’t realize that all the additional network drivers (Realtek 8188eu, 8188fu, 8192eu, 8812au, 8812bu, 8814au, 8821au, 8821cu, and 8822bu) are not yet available for this Linux Kernel Version. The latest supported Linux Kernel is version 5.10.49. Those already working with the current image file or who have updated the system and need one of these network drivers can fix the bug by updating the TorBox menu (update and reset sub-menu entry 5) and executing the following command on TorBox’s command prompt:
    cd ~/torbox
    bash install/step_back_to_kernel_5.10.49

    Afterwards, rerun menu entry 2 in the Update and Reset sub-menu.
    The current image is updated. BUG FIXED✔︎
  • BUG: The integration of TorBox’s automatic counteractions into rc.local resulted in some nasty bugs, which we didn’t see before: rc.local needs absolute paths, not relative ones; there was also an error in getting the name of the internet interface from the run-file, which broke the execution of the automat script. We also put the logs of TorBox’s automatic counteractions into a separate file (/var/log/tor/automat.log) so that it is easier to see if automatic counteractions were activated or not. You can fix the bug by updating the TorBox menu (update and reset sub-menu entry 5). The current image is updated. BUG FIXED✔︎
  • BUG: Due to a little bug in the script, TorBox tells during the activation of the Meek-Azure bridge that the bridge is offline, which is not the case. However, you can continue, and the bridge will work without any problem. You can fix the bug by updating the TorBox menu (update and reset sub-menu entry 5). The current image is updated. BUG FIXED✔︎
  • BUG: Pressing the enter key in the OBFS4 port definition (“port number of the OBFS4”) during the OBFS4 Bridge Relay configuration will not automatically take the latest used or the default number. This will result to a faulty torrc entry (ServerTransportListenAddr obfs4 instead of, for example, ServerTransportListenAddr obfs4 This will prevent tor from starting until the ServerTransportListenAddr line is fixed or deactivated. The workaround is easy: don’t press the enter key during the OBFS4 Bridge Relay configuration, but write the number into the dialogue. However, you can fix the bug by updating the TorBox menu (update and reset sub-menu entry 5). The current image is updated. BUG FIXED✔︎