I want to build it from scratch on a Raspberry Pi with Raspberry Pi OS Lite!

Whether you like to implement TorBox to an existing system, to another hardware, respectively another operating system, or you don’t trust an image file, which you didn’t bundle of your own, this detailed manual helps you to build a TorBox from scratch.

This manual is written for Raspberry Pi OS “Buster” Lite (based on Debian 10 “Buster”) on a Raspberry Pi 3 (Model B / Model B+) or Raspberry Pi 4 Model B.

Before you create all configuration files by yourself: some of the below-mentioned configuration files are stored in the “TorBox Menu” file or on our GitHub page in the “etc” folder.

1. Prepare your system
  1. Download the latest version of the Raspberry Pi OS Lite (about 442 MB)
  2. Transfer the downloaded Raspian Lite image on an SD Card; for example, with Etcher. TorBox needs at least a 8 GB SD Card.
  3. Log into your newly set up system and configure it with “sudo raspi-config.
    You must set the “WLAN country” (in raspi-config menu entry 4 – i4), or TorBox doesn’t
    work because WiFi is blocked!!
    – You need to have a stable internet connection.

An alternative way to unblock WiFi on Rapberry Pi OS whitout using raspi-config:

sudo iw reg set US
sudo sed -i "s/^REGDOMAIN=.*/REGDOMAIN=US/" /etc/default/crda
sudo rfkill unblock wlan

– To overcome cheap censorship during the installation, put some well known public name servers into /etc/resolv.conf:

sudo printf "nameserver\nnameserver\nnameserver\nnameserver\n" | sudo tee /etc/resolv.conf
2. Update your system and install all necessary packages

To build a TorBox from scratch, some packages have to be installed first. To be sure to have the latest version of the base system, the package list, and the firmware, you should use the following commands:

sudo apt-get -y update
sudo apt-get -y dist-upgrade
sudo apt-get -y clean
sudo apt-get -y autoclean
sudo apt-get -y autoremove

Depending on the updated packages (firmware, kernel, driver etc.) a reboot is recommended.

Following additional packages are necessary and have to be installed:

  • hostapd -> provides a wireless access point (AP).
  • isc-dhcp-server -> act as our DHCP server.
  • tor-geoipd, obfs4proxy, python3-stem, apt-transport-tor -> gives access to the Tor network (tor will be installed later, see further below).
  • nyx -> a command-line monitor for Tor.
  • usbmuxd -> a socket daemon to multiplex connections from and to iOS devices (support for tethering with iOS devices).
  • dnsmasq -> DNS forwarder (necessary to deal with captive portals).
  • dnsutils, tcpdump, iftop, vnstat -> analytical and statistical network tools.
  • debian-goodies, apt-transport-https -> other necessary tools.
  • dirmngr -> GNU privacy guard – network certificate management service.
  • python3-pip -> necessary for Python 3.
  • python3-pil, imagemagick, tesseract-ocr -> necessary libraries and programs for bridges_get.py.
  • ntpdate -> necessary to set the correct system time.
  • screen -> a terminal multiplexer allowing a user to access multiple separate login sessions inside a single terminal window, or detach and reattach sessions from a terminal.
  • git -> distributed revision control system.
  • openvpn -> software that implements virtual private network.
  • ppp -> Point-to-Point Protocol
  • wiringpi -> PIN based GPIO access library written in C for the BCM2835, BCM2836 and BCM2837 SoC devices used in all Raspberry Pi. Needed for the support of the Sixfab Shields/HATs for cellular connections.
  • raspberrypi-kernel-headers dkms -> necessary to compile / install additional drivers
  • shellinabox -> SSH in a webbrowser

Install all necessary packages with the following command:

# Installation of standard packages
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

# If you use a Debian distribution instead of Raspberry Pi OS, you may need to install the following additional packages
apt-get -y install wget curl gnupg net-tools unzip sudo resolvconf iptables

# Installation of developper packages - THIS PACKAGES ARE NECESARY FOR THE COMPILATION OF TOR!! Without them, tor will disconnect and restart every 5 minutes!!
sudo apt-get -y install build-essential automake libevent-dev libssl-dev \
asciidoc bc devscripts dh-apparmor libcap-dev liblzma-dev libsystemd-dev \
libzstd-dev quilt zlib1g-dev

# IMPORTANT tor-geoipdb installs also the tor package. In a authoritarian country, you may mask tor and activate it later with OBFS4 bridge support to hide the use of tor.
sudo systemctl mask tor
sudo apt-get -y install tor-geoipdb
sudo systemctl mask tor
sudo systemctl stop tor

# Installation of wiringpi
wget https://project-downloads.drogon.net/wiringpi-latest.deb
sudo dpkg -i wiringpi-latest.deb
sudo rm wiringpi-latest.deb

# Additional installations for Python
sudo pip3 install pytesseract
sudo pip3 install mechanize
sudo pip3 install PySocks
sudo pip3 install urwid
sudo pip3 install Pillow
sudo pip3 install requests

# Additional installation of GO (go1.16.6.linux-armv6l.tar.gz for a 32bit OS; go1.16.6.linux-arm64.tar.gz for a 64bit OS on a Raspberry Pi)
cd ~
sudo rm -rf /usr/local/go
wget https://golang.org/dl/go1.16.6.linux-armv6l.tar.gz
sudo tar -C /usr/local -xzvf go1.16.6.linux-armv6l.tar.gz
export PATH=$PATH:/usr/local/go/bin
sudo printf "\n# Added by TorBox\nexport PATH=$PATH:/usr/local/go/bin\n" | sudo tee -a .profile

# Installation of additional network drivers from http://downloads.fars-robotics.net/wifi-drivers/
# First, go to website to check for the available network drivers. 
# Get the kernel version:
uname -rv | cut -d ' ' -f1-2 | tr '+' ' ' | tr '#' ' ' | sed -e "s/[[:space:]]\+/-/g"

# Install the network driver that fits to kernel version with the following commands:
cd ~
mkdir install_network_driver
cd install_network_driver
wget http://downloads.fars-robotics.net/wifi-drivers/<path>/<filename>
tar xzf <filename>
chmod a+x install.sh
sudo ./install.sh
cd ~
rm -r install_network_driver

# If you need a network driver, but it is not yet available for the installed Linux kernel,you have to step back to an older, supported kernel.
# Go to https://github.com/Hexxeh/rpi-firmware/commits/master and search for the "Bump to ..." entry with the supported kernel.
# Copy the full commit number (for example: dc6dc9bc6692d808fcce5ace9d6209d33d5afbac) and execute the following command:
sudo rpi-update <COMMITNUMBER>

We don’t want to start dnsmasq automatically after booting the system:

sudo systemctl disable dnsmasq
sudo systemctl daemon-reload
3. Compiling, installing and configuring Tor

There are at least three ways to install Tor:

  1. From the Raspberry Pi OS itself: this has probably already happened with the installation of tor-geoipdb. This method is recommended in authoritarian countries. However, usually that installs an older long-term-supported version of tor.
  2. From the Debian repository of the TorProject: we don’t recommend to use this way because it doesn’t support 32bit ARM systems/OS anymore with a debian package.
  3. From the unofficial Tor repositories on GitHub: we recommend this method as the standard way to install tor on the TorBox (used below). If necessary, forks can be used as mirror sites.

First step: Compiling and installing a specific version of tor from the unofficial Tor repositories on GitHub
Select a specific tor version from the unofficial Tor repositories on GitHub (alpha versions are not recommended!) and copy the link for the .tar.gz file (right click on the little .tar.gz sign); you need that link for the wget command below.

wget https://github.com/torproject/tor/archive/refs/tags/<torversion>.tar.gz
tar xzf <torversion>.tar.gz
cd <torversion>
sudo make install
cd ..
sudo rm -r <torversion>
sudo mv /usr/local/bin/tor* /usr/bin 

Second step: Installation of Snowflake

# Additional installation of Snowflake
cd ~
git clone https://git.torproject.org/pluggable-transports/snowflake.git
export GO111MODULE="on"
cd ~/snowflake/proxy
go get
go build
sudo cp proxy /usr/bin/snowflake-proxy

cd ~/snowflake/client
go get
go build
sudo cp client /usr/bin/snowflake-client

cd ~
sudo rm -rf snowflake
sudo rm -rf go*

Third step: Configuring Tor

# Edit /etc/tor/torrc
sudo nano /etc/tor/torrc

# Replace /etc/tor/torrc with the following content:
## This is the configuration file of Tor
## Configuration for TorBox

Log notice file /var/log/tor/notices.log
AutomapHostsSuffixes .onion,.exit
AutomapHostsOnResolve 1
SocksPort IsolateDestAddr
#SocksPort IsolateDestAddr
DisableDebuggerAttachment 0
HashedControlPassword 16:E68F16640ED8C0F7601F5AA3D229D8DFD8715623CB055577F9434F7FB7

## This will setup an obfs4 bridge relay.
#BridgeRelay 1
#ORPort 4235
#ExtORPort auto
#ServerTransportPlugin obfs4 exec /usr/bin/obfs4proxy
#ServerTransportListenAddr obfs4
#ContactInfo <[email protected]>
#Nickname TorBox042
#BridgeDistribution any

## This will allow you to run Tor as a client behind a firewall with
## restrictive policies, but will not allow you to run as a server behind such
## a firewall.
## ReachableAddresses IP[/MASK][:PORT]…
## A comma-separated list of IP addresses and ports that your firewall allows
## you to connect to. The format is as for the addresses in ExitPolicy, except
## that "accept" is understood unless "reject" is explicitly provided. For
## example, 'ReachableAddresses, reject, accept *:80'
## means that your firewall allows connections to everything inside net 99,
## rejects port 80 connections to net 18, and accepts connections to port 80
## otherwise.
#ReachableAddresses *:80, *:443

## If you like to use bridges to overcome censorship, EDIT THE LINES BELOW!
## To use bridges, uncomment the three lines below...
#UseBridges 1
#UpdateBridgesFromAuthority 1
#ClientTransportPlugin meek_lite,obfs4 exec /usr/bin/obfs4proxy
#ClientTransportPlugin snowflake exec PluggableTransports/snowflake-client -url https://snowflake-broker.torproject.net.global.prod.fastly.net/ -front cdn.sstatic.net -ice stun:stun.l.google.com:19302,stun:stun.voip.blackberry.com:3478,stun:stun.altar.com.pl:3478,stun:stun.antisip.com:3478,stun:stun.bluesip.net:3478,stun:stun.dus.net:3478,stun:stun.epygi.com:3478,stun:stun.sonetel.com:3478,stun:stun.sonetel.net:3478,stun:stun.stunprotocol.org:3478,stun:stun.uls.co.za:3478,stun:stun.voipgate.com:3478,stun:stun.voys.nl:3478

## Meek-Azure
#Bridge meek_lite 97700DFE9F483596DDA6264C4D7DF7641E1E39CE url=https://meek.azureedge.net/ front=ajax.aspnetcdn.com

## Snowflake
#Bridge snowflake 2B280B23E1107BB62ABFC40DDCC8824814F80A72

## OBFS4 bridges
## You have three ways to get new bridge-addresses:
## 1. Get them here https://bridges.torproject.org/
##    (chose "Advanced Options", "obfs4" and press "Get Bridges)
## 2. Or send an email to [email protected], using an address
##    from Riseup or Gmail with "get transport obfs4" in the body of the mail.
## 3. (Not recommended, only if needed): Via Telegram: https://t.me/tor_bridges


  • Don’t remove or change the “#-lines”. TorBox changes this file automatically. If you delete values (even the ones with #), TorBox doesn’t re-add them again, and TorBox may not work correctly!
  • You should change the “HashedControlPassword” at the end of the installation with the help of the configuration sub-menu entry 3.

Fourth step: Install Vanguards

cd ~
sudo git clone https://github.com/mikeperry-tor/vanguards
sudo chown -R debian-tor:debian-tor vanguards
sudo mv vanguards /var/lib/tor/
sudo cp /var/lib/tor/vanguards/vanguards-example.conf /etc/tor/vanguards.conf
sudo sed -i "s/^control_pass =.*/control_pass = ${DEFAULT_PASS}/" /etc/tor/vanguards.conf
#This is necessary to work with special characters in sed
REPLACEMENT_STR="$(<<< "$VANGUARDS_LOG_FILE" sed -e 's`[][\\/.*^$]`\\&`g')"
sudo sed -i "s/^logfile =.*/logfile = ${REPLACEMENT_STR}/" /etc/tor/vanguards.conf
# Because of TorBox's automatic counteractions, Vanguard cannot interfere with tor's log file
sudo sed -i "s/^enable_logguard =.*/enable_logguard = False/" /etc/tor/vanguards.conf
sudo sed -i "s/^log_protocol_warns =.*/log_protocol_warns = False/" /etc/tor/vanguards.conf
sudo chown -R debian-tor:debian-tor /var/lib/tor/vanguards
sudo chmod -R go-rwx /var/lib/tor/vanguards

Fifth step: Configuring geoip and obfs4proxy

# Execute the following commands:
sudo chmod a+x /usr/share/tor/geoip*
sudo cp /usr/share/tor/geoip* /usr/bin
sudo setcap 'cap_net_bind_service=+ep' /usr/bin/obfs4proxy
sudo sed -i "s/^NoNewPrivileges=yes/NoNewPrivileges=no/g" /lib/systemd/system/[email protected]
sudo sed -i "s/^NoNewPrivileges=yes/NoNewPrivileges=no/g" /lib/systemd/system/[email protected]
4. Configuring Shellinabox

With Shellinabox, it is possible to access the TorBox terminal through any JavaScript and CSS enabled web browser without any additional browser plugins. This should offer an alternative way to access the TorBox main menu, however, the standard method is still using an SSH client. Moreover, Shellinabox is only usable with an external keyboard. For that reason, it is not the best solution for smartphones and other devices without a real keyboard. Because it uses a self-signed certificate for its secure connections, browsers will show a warning message during the first connection, which has to be ignored. To use a secure connection between the web browser and Shellinabox, the user has to accept this certificate.

On TorBox, we put the port to Shellinabox to 9000:

# Edit /etc/default/shellinabox:
sudo nano /etc/default/shellinabox

# Change the following line with "SHELLINABOX_PORT" and set it to 9000:

To have a white font on a black background, you have to rename the links in /etc/shellinabox/options-enabled and to restart the shellinabox daemon:

sudo mv /etc/shellinabox/options-enabled/00+Black\ on\ White.css /etc/shellinabox/options-enabled/00_Black\ on\ White.css
sudo mv /etc/shellinabox/options-enabled/00_White\ On\ Black.css /etc/shellinabox/options-enabled/00+White\ On\ 
sudo systemctl restart shellinabox.service

To open the TorBox main menu, following URL has to be used in a JavaScript and CSS enabled web browser (from a wifi client) or (from a cable client)

5. Installing the TorBox Menu (and download all configuration files)

The “TorBox Menu” is a user-friendly way to use and change the settings of your TorBox. The menu is automatically started, whenever a Terminal, a SSH-client ( on a WiFi client or on a cable client) or a web browser ( on a WiFi client or on a cable client) access the TorBox. The menu works with shell scripts, which set the correct packet filtering and NAT rules as well as starts other supporting tools. All scripts are located under “~/torbox” and all configuration file under “~/torbox/etc”. If necessary, the menu can be started there with “./menu”. Use the following commands to install the menu (or download the complete TorBox repository from our GitHub page):

# Execute the following commands:
cd ~
wget https://github.com/radio24/TorBox/archive/refs/heads/master.zip
unzip master.zip
rm -r torbox
mv TorBox-master torbox
rm -r master.zip

# Edit .profile:
sudo nano .profil

# Add the following lines to the end of ".profile":
cd torbox
bash menu

Optionally, in ~/torbox/etc/motd you can find a logo, which you can copy into your /etc/motd.

# Execute following commands:
cp ~/torbox/etc/motd /etc/motd

 Finally, you need to change /etc/rc.local to be sure, that TorBox will work properly after a restart:

# Edit /etc/rc.local:
sudo nano /etc/rc.local

# Replace /etc/rc.local with the following content:
#!/bin/sh -e
# rc.local
# Added by TorBox
rfkill unblock all

# Print the IP address
_IP=$(hostname -I) || true
if [ "$_IP" ]; then
  printf "My IP address is %s\n" "$_IP"

# Added by TorBox
if grep "iface wlan1 inet static" /etc/network/interfaces || grep "^interface=wlan1" /etc/hostapd/hostapd.conf ; then
  sudo ifdown wlan0
  sudo ifdown wlan1
  sudo sed -i "s/^auto wlan0/auto wlan1/" /etc/network/interfaces
  sudo sed -i "s/^iface wlan0 inet dhcp/iface wlan1 inet dhcp/" /etc/network/interfaces
  sudo sed -i "s/^iface wlan1 inet static/iface wlan0 inet static/" /etc/network/interfaces
  sudo sed -i "s/^interface=wlan1/interface=wlan0/" /etc/hostapd/hostapd.conf
  sudo sed -i "s/^INTERNET_IFACE=.*/INTERNET_IFACE=wlan1/" /home/torbox/torbox/run/torbox.run
  sudo sed -i "s/^CLIENT_IFACE=.*/CLIENT_IFACE=wlan0 eth0/" /home/torbox/torbox/run/torbox.run
  sudo ifup wlan0 &>/dev/null &
  sudo ifup wlan1 &>/dev/null &
  sudo systemctl restart hostapd
  sudo systemctl restart isc-dhcp-server
  sleep 5

if ip link | grep wlan1 | grep "state DOWN" ; then
  sudo /usr/bin/python3 /home/torbox/torbox/torbox_wireless_manager.py -i wlan1 -a
  sudo sed -i "s/^INTERNET_IFACE=.*/INTERNET_IFACE=wlan1/" /home/torbox/torbox/run/torbox.run
  sleep 5

if grep "LOGCHECK=1" /home/torbox/torbox/run/torbox.run ; then
  sudo /usr/bin/python3 /home/torbox/torbox/log_check.py &
  sleep 5

sudo /sbin/iptables-restore < /etc/iptables.ipv4.nat
sudo systemctl start dnsmasq
sleep 10
sudo /usr/sbin/ntpdate pool.ntp.org
sleep 5
sudo systemctl stop dnsmasq

exit 0

# Create or edit /etc/iptables.ipv4.nat:
sudo nano /etc/iptables.ipv4.nat

# Replace /etc/iptables.ipv4.nat with the following content:
:INPUT DROP [384:97594]
:OUTPUT ACCEPT [32451:18744664]
-A INPUT -m state --state INVALID -j DROP
-A INPUT ! -s -i wlan0 -j LOG --log-prefix "SPOOFED PKT "
-A INPUT ! -s -i eth1 -j LOG --log-prefix "SPOOFED PKT "
-A INPUT ! -s -i wlan0 -j DROP
-A INPUT ! -s -i eth1 -j DROP
-A INPUT -i lo -j ACCEPT
-A INPUT -i wlan0 -j ACCEPT
-A INPUT -i eth1 -j ACCEPT
-A INPUT -p icmp -m icmp --icmp-type 8 -j ACCEPT
-A INPUT -p icmp -m icmp --icmp-type 0 -j ACCEPT
-A FORWARD -m state --state INVALID -j DROP
-A FORWARD -p icmp -m icmp --icmp-type 8 -j ACCEPT
-A FORWARD -p icmp -m icmp --icmp-type 0 -j ACCEPT
-A OUTPUT -m conntrack --ctstate INVALID -j DROP
-A OUTPUT -m state --state INVALID -j DROP
-A OUTPUT ! -s ! -d ! -o lo -p tcp -m tcp --tcp-flags RST,ACK RST,ACK -j DROP
-A OUTPUT -o eth0 -p tcp -m tcp --dport 53 -j LOG --log-prefix "SSH SHELL DNS-REQUEST TCP" --log-tcp-options --log-ip-options
-A OUTPUT -o eth0 -p udp -m udp --dport 53 -j LOG --log-prefix "SSH SHELL DNS-REQUEST UDP" --log-ip-options
:INPUT ACCEPT [2303:137217]
:OUTPUT ACCEPT [80:6038]
-A PREROUTING -d -i wlan0 -p tcp -j REDIRECT
-A PREROUTING -d -i eth1 -p tcp -j REDIRECT
-A PREROUTING -i wlan0 -p tcp -j REDIRECT --to-ports 9040
-A PREROUTING -i eth1 -p tcp -j REDIRECT --to-ports 9040
-A PREROUTING -i wlan0 -p udp -m udp --dport 53 -j REDIRECT --to-ports 9053
-A PREROUTING -i eth1 -p udp -m udp --dport 53 -j REDIRECT --to-ports 9053
-A PREROUTING -i wlan0 -p udp -j REDIRECT --to-ports 9040
-A PREROUTING -i eth1 -p udp -j REDIRECT --to-ports 9040

 Make sure that the SSH-client can access the TorBox after the restart:

# Execute the following commands:
sudo systemctl unmask ssh
sudo systemctl enable ssh
sudo systemctl start ssh
sudo systemctl daemon-reload
6. Setting up a DHCP server
# Set up your hostname (for example "TorBox" instead of "raspberrypi":
sudo nano /etc/hostname
sudo nano /etc/hosts

# Adjust the configuration file of the DHCP server:
sudo nano /etc/dhcp/dhcpd.conf

# Replace /etc/dhcp/dhcpd.conf with the following content:
default-lease-time 600;
max-lease-time 7200;
ddns-update-style none;

subnet netmask {
option broadcast-address;
option routers;
option domain-name "local";
option domain-name-servers;

subnet netmask {
option broadcast-address;
option routers;
option domain-name "local";
option domain-name-servers;

# Adjust the configuration file of the DHCP server (isc-dhcp-server):
sudo nano /etc/default/isc-dhcp-server

# Add all the available interfaces to the following line:
INTERFACEv4="wlan0 wlan1 eth0 eth1"

The classless static route option (RFC3442) gives us some headaches with certain AP under certain conditions (see also here). Therefore we remove this option from the configuration:

# Remove in /etc/dhcp/dhclient.conf the classless static route option
sudo nano /etc/dhcp/dhclient.conf

# Old entries:
option rfc3442-classless-static-routes code 121 = array of unsigned integer 8;

request subnet-mask, broadcast-address, time-offset, routers, domain-name,
domain-name-servers, domain-search, host-name, dhcp6.name-servers,
dhcp6.domain-search, dhcp6.fqdn, dhcp6.sntp-servers, netbios-name-servers,
netbios-scope, interface-mtu, rfc3442-classless-static-routes, ntp-servers; 

# New entries:
#option rfc3442-classless-static-routes code 121 = array of unsigned integer 8;

request subnet-mask, broadcast-address, time-offset, routers, domain-name,
domain-name-servers, domain-search, host-name, dhcp6.name-servers,
dhcp6.domain-search, dhcp6.fqdn, dhcp6.sntp-servers, netbios-name-servers,
netbios-scope, interface-mtu, ntp-servers;
7. Setting up network interfaces

Currently, TorBox supports the following connections:

INTERNET     CLIENT           Remarks
ETH0         WLAN0(+ETH1)     Cable-internet (onboard ethernet adapter) - STANDARD
ETH1         WLAN0(+ETH0)     USB ethernet adapter or Tethering (iOS)
WLAN1        WLAN0(+ETH0)     Wireless-internet (USB wireless adapter, usually 2.4 GHz only)
WLAN0        WLAN1(+ETH0)     Wireless-internet (onboard chip, with >RPi3B+: 2.4/5 GHz)
USB0	     WLAN0(+ETH0)     USB dongle or Tethering (Android) (ppp0; usb0)
PPP0         WLAN0(+ETH0)     Cellular-internet
TUN0         WLAN0(+ETH0)     Over a VPN connection

 In the beginning, only the standard /etc/network/interface — listed below — is necessary. Depending on your choice in the TorBox menu, this file is altered by TorBox automatically.

# Edit /etc/network/interfcae:
sudo nano /etc/network/interface

# Replace /etc/network/interface with the following content:
source-directory /etc/network/interfaces.d

auto lo
auto usb0

iface lo inet loopback
iface eth0 inet dhcp
iface wlan1 inet dhcp
iface usb0 inet dhcp
allow-hotplug wlan0 wlan1 eth0 eth1 usb0

iface wlan0 inet static

iface eth1 inet static

wireless-power off
8. Configuring the TorBox AP
# Edit /etc/hostapd/hostapd.conf
sudo nano /etc/hostapd/hostapd.conf

# Replace /etc/hostapd/hostapd.conf with the following content:


  1. Only letters (upper and lower case) and numbers are allowed in the passphrase. The length must be between 8 and 63 characters.
  2. Don’t remove or change the “#-lines” and the “country_code=US” value! Otherwise, the 2.4 GHz 40 MHz and the 5 GHz 40 and 80 MHz settings will most likely not work and probably crash hostapd! In use, TorBox changes this file along to the selection in the configuration sub-menu. However, if you delete values (even the ones with #), TorBox doesn’t re-add them again!
# Edit /etc/default/hostapd
sudo nano /etc/default/hostapd

# Old entry:

# New entry:

This ensures the automatic start of the services when TorBox is started and also starts them immediately.

sudo systemctl unmask hostapd
sudo systemctl enable hostapd
sudo systemctl start hostapd
sudo systemctl unmask isc-dhcp-server
sudo systemctl enable isc-dhcp-server
sudo systemctl start isc-dhcp-server
sudo systemctl disable dhcpcd
sudo systemctl daemon-reload
9. Configuring Network Address Translation (NAT)
# Edit /etc/sysctl.conf:
sudo nano /etc/sysctl.conf

# Old entry:

# New entry:

# With the following command, we have to enable IP forwarding (necessary to overcom caprive portals):
sudo sh -c "echo 1 > /proc/sys/net/ipv4/ip_forward"
10. Disable Bluetooth

Because of security considerations, we recommend disabling the Bluetooth functionality of your Raspberry Pi completely.

# Change your /boot/config.txt:
sudo nano /boot/config.txt

# Add to the end of /boot/config.txt:

# Run following command to disable the related services:
sudo systemctl disable hciuart.service 
sudo systemctl disable bluealsa.service 
sudo systemctl disable bluetooth.service

# Remove the Bluetooth stack to make Bluetooth unavailable even if external Bluetooth adapter is plugged in:
sudo apt-get -y purge bluez 
sudo apt-get -y autoremove

You have to reboot your Raspberry Pi to apply the changes.

11. Adding the user “torbox” and removing the user “pi”

In this step the user “torbox” with the default password “CHANGE-IT” (or whatever you chose) is created. To use TorBox, you have to log in with “torbox” and the default password. Please, change all default passwords as soon as possible . The associated menu entries are placed in the configuration sub-menu.

We also disable the user “pi”.

sudo adduser --gecos "" torbox
sudo adduser torbox sudo
sudo mv /home/pi/* /home/torbox/
sudo mv /home/pi/.profile /home/torbox/
sudo mkdir /home/torbox/openvpn
sudo rm .bash_history
sudo chown -R torbox.torbox /home/torbox/
sudo printf "\n# Added by TorBox\ntorbox  ALL=NOPASSWD:ALL\n" | sudo tee -a /etc/sudoers
sudo visudo -c
cd /home/torbox/

# Disabling "pi". This can be undone by sudo chage -E-1 pi
sudo chage -E0 pi

# Removing "pi"
sudo userdel -r pi
12. Stop logging, preparing for the first start and restarting the system
# Stop logging
sudo systemctl stop rsyslog
sudo systemctl disable rsyslog
sudo systemctl daemon-reload

# Remove log files and history
sudo rm /var/log/*
history -c

# This is not mandatory, but we recommend to start our image preparation script 
#(even if you don't make an image) to check the installation and perform some routine cleaning tasks
cd /home/torbox/
bash install/prepare_image.sh

# If you don't want to use our preparation script, you have at least to set the right start trigger in torbox.run
sudo sed -i "s/^FRESH_INSTALLED=.*/FRESH_INSTALLED=2/" /home/torbox/torbox/run/torbox.run

# Restart the system
sudo reboot

After restarting your system, log into the TorBox by using a SSH client ( on a WiFi client or on a cable client) or a web browser ( on a WiFi client or on a cable client; for a connection via cable, see here; username: torbox / password: CHANGE-IT). TorBox will ask if it is necessary to activate OBFS4 bridges for hiding the use of the Tor network. 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. This is only necessary during the first start. However, you can change your decision and configure the use of bridges later in the Countermeasure sub-menu.

Finally, you should see the TorBox Main Menu. Choose the preferred connection setup and change the default passwords as soon as possible (the associated entries are placed in the configuration sub-menu). Check if your data stream is routed through the Tor network: https://check.torproject.org