Installation – TorBox mini (experimental!)

There are situations when a TorBox on a Raspberry Pi 3 Model B+, a Raspberry Pi 4 Model B or a Raspberry Pi 5 is to big or expensive to use, and also the TorBox on a cloud is also not a possible solution. Sometimes it would be nice, if TorBox would be smaller and stealthier. That’s exactly the aim of TorBox mini.

For TorBox mini we need the following:

Remarks

Installing TorBox mini on a Raspberry Pi Zero 2 W can take hours! We recommend using a Raspberry Pi 5 with an attached display to install TorBox mini on a SDCard. In this case, we recommend doing the following steps below: 1, 4, 5 and 6.
After removing the SDCard from the Raspberry Pi 5 and putting it into the Raspberry Pi Zero 2 W, you should be faced with the First Start-up Dialogue. If not, please rerun the First Start-up Dialogue in the Update & Maintenance menu to unblock the functionality.

Solderless USB-A adapters mounted on Raspberry Pi Zero W
Solderless USB-A adapters mounted on Raspberry Pi Zero W
1 – Installation: Create a proper configured SD Card

Create a SD Card with Raspberry Pi OS “Bookworm” lite 32-bit or Raspberry Pi OS “Bookworm” lite 64-bit using the Raspberry Pi Imager or Balena Etcher.

After creating the SD Card, pull it, but plug it into the computer again. Go to the root directory of the SD Card  (usually called boot, bootfs or something similar) and edit cmdline.txt. The old one on the root directory will look something like this:

console=serial0,115200 console=tty1 root=PARTUUID=662b4900-02 rootfstype=ext4 fsck.repair=yes rootwait quiet init=/usr/lib/raspberrypi-sys-mods/firstboot

You have to add the following options: modules-load=dwc2,g_ether, cfg80211.ieee80211_regdom=CH (you have to use the right two-letter country code; CH is standing for Switzerland), and systemd.run=/boot/firstrun.sh systemd.run_success_action=reboot systemd.unit=kernel-command-line.target. The rights sequence of this options is important; at the end your cmdline.txt has to look similar like this:

console=serial0,115200 console=tty1 root=PARTUUID=662b4900-02 rootfstype=ext4 fsck.repair=yes modules-load=dwc2,g_ether rootwait quiet init=/usr/lib/raspberrypi-sys-mods/firstboot cfg80211.ieee80211_regdom=CH systemd.run=/boot/firstrun.sh systemd.run_success_action=reboot systemd.unit=kernel-command-line.target

Important: You cannot copy&past this line and you cannot overwrite cmdline.txt with another because the option root=PARTUUID=nnnnn changes depending on the running kernel.

Next copy config.txt and firstrun.sh to the root directory of the SD Card.

2 – Installation: Log into the Raspberry Pi Zero 2 W

If it’s done, put the SD Card into the Raspberry Pi Zero 2 W, which is connected to a USB-A adapter as shown in the foto above. Lets call the machine in which you plug in the Pi the “client”.

Plugged into a Mac, the Raspberry Pi Zero 2 W will be recognized as a RNDIS/Ethernet Gadget, which you can use like every other network interface (for example Ethernet or Wireless). This may take 1-2 minutes, because Raspberry Pi OS has to expand the file system and start up again. Under macOS it is not necessary to install any additional software.

Under Linux, the g_ether driver is needed to use a RNDIS/Ethernet Gadget. Most likely the kernel module will be automatically loaded by plugging in the Raspberry Pi Zero 2 W. If this is not the case use modprobe g_ether to load the module. If successful, usb0 will be available as a network device, which can be used as every other network device. You can check if the module is loaded with lsmod (see also here).

Under Windows, a little bit more work is necessary:

  • Install a RNDIS/Ethernet driver as explained here. If this is not working, try it manually a explained here.
  • Install Bonjour for Windows.
  • In Windows’ firewall settings (Settings\System and Security\Windows Defender Firewall\Authorized Apps) Windows’ Bonjour service needs the allowance to access to public networks.
  • If the Raspberry Pi Zero 2 W is connected, Windows detects a new, unidentified network without Internet access. Now, the Pi can be accessed using a SSH client (see below).
3 – Installation: Log into the RNDIS/Ethernet Gadget

You have to configure RNDIS/Ethernet Gadget network entries on the client as followed (this is important because using torbox.local will break the installation):

Don't use DHCP
IPv4 address: 192.168.44.10
Subnet mask: 255.255.0.0
Router: 192.168.44.1
DNS-Server: 192.168.44.1

Next log into your Raspberry Pi Zero 2 W using an SSH client (we recommend using Termius) with the following options:

Address: 192.168.44.1
Login: torbox
Password: CHANGE-IT

Important: You have to disable all other network connections on your client machine to avoid any interference.

4 – Installation: Connect to a wifi network
  • Unblock the wireless interfaces with sudo rfkill unblock wlan.
  • Stop an already running wpa_supplicant with sudo systemctl stop wpa_supplicant.
  • Stop NetworkManager: sudo systemctl stop NetworkManager
  • Prepare the wireless interface: sudo ip link set dev wlan0 up
  • Find wireless networks and note down the name (SSID): sudo iw wlan0 scan | grep SSID:
  • Build the wpa_supplicant.conf (<SSID> is the name of the wireless network to connect, <wifi-password> the password of <SSID>): wpa_passphrase <SSID> <wifi-password> | sudo tee -a /etc/wpa_supplicant/wpa_supplicant.conf
  • Connect to the wireless network: sudo wpa_supplicant -B -c /etc/wpa_supplicant/wpa_supplicant.conf -i wlan0
  • Start dhclient to get an IP: sudo dhclient wlan0
5 – Fix for unstable SSH client connections

The installation of TorBox on a Raspberry Pi Zero 2 W is very power-consuming for the little device. In some circumstances, for example, if the power supply is only through the USB connection and not from an external source, it could lead to the loss of the connection between the Raspberry Pi Zero 2 W and the SSH client. For that reason, we highly recommend installing screen so that the installation will continue in the background, even in the case of a connection loss. In such a case, you can just log in again with our SSH client and attach screen again to see your installation progress.

  • Installation of screen: sudo apt-get -y install screen
  • Log into your Raspberry Pi Zero 2 W using an SSH client
  • Start screen: screen
  • After losing the SSH connection, the installation will continue in the background. To see the progress, log in again with your SSH client and attache screen again: screen -x
6 – Installation of TorBox mini
cd
wget https://raw.githubusercontent.com/radio24/TorBox/torbox_v054/install/run_install.sh
chmod a+x run_install.sh
screen
./run_install.sh --select-branch torbox_v054 --torbox_mini

To install TorBox on a Raspberry Pi Zero 2 W, you have to be very patient. Especially during the installation of the necessary packages, sometimes it seems as the installation is stucked (for example with the packages texlive-pictures or at-spi2-core) – just wait. However, if the installation is really stuck, then restart the Raspberry Pi Zero 2 W, connect again to the wifi network, run the following command – sudo dpkg --configure -a – and restart the installation again. If you know at which step the installation dropped (for example, during step 2b), you can also add the following option to the installation script: --continue_with_step n (n represents the main step, for example: --continue_with_step 2).