I want to build it from scratch!

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 Raspbian “Buster” Lite (based on Debian 10 “Buster”) on a Raspberry Pi 3 (Model B / Model B+) or Raspberry Pi 4 Model B. We suppose that you have already basically configured your Raspberry Pi with raspi-config (localization, keyboard layout and so on), that your Raspbian installation is working properly, that the Raspberry Pi has access to the Internet and that it is connected to a reliable power supply (see also “All about the power supply: ‘Under-voltage detected!’ / Red blinking LED on the Raspberry Pi 3 Model B+ / Unusual, strange behaviors – What do these things mean?).

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

1. 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 update
sudo apt-get dist-upgrade
sudo apt-get clean
sudo apt-get autoclean
sudo apt-get 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, obfs4proxy -> gives access to the Tor network.
  • usbmuxd -> a socket daemon to multiplex connections from and to iOS devices (support for tethering with iOS devices).
  • wicd-curses -> an easy to use wireless network connection manager (wicd stands for “Wireless Interface Connection Daemon”).
  • dnsmasq -> DNS forwarder (necessary to deal with captive portals).
  • dnsutils, tcpdump, iftop, vnstat, links2 -> analytical and statistical network tools.
  • debian-goodies, apt-transport-https -> other necessary tools.
  • dirmngr -> GNU privacy guard – network certificate management service.
  • python3-setuptools -> necessary tools for Python 3.
  • 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.
  • nyx -> a command-line monitor for Tor.

Install all necessary packages with following command:

sudo apt-get -y install hostapd isc-dhcp-server tor obfs4proxy usbmuxd wicd \
dnsmasq dnsutils tcpdump iftop vnstat links2 debian-goodies apt-transport-https \
dirmngr python3-setuptools ntpdate screen nyx

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

sudo systemctl dnsmasq disable
2. Disable Bluetooth

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

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

# Add to the end of /boot/config.txt:
dtoverlay=disable-bt

# 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.

3. Setting up a DHCP server
# Set up yoour 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;
authoritative;

subnet 192.168.42.0 netmask 255.255.255.0 {
range 192.168.42.10 192.168.42.50;
interface wlan0;
option broadcast-address 192.168.42.255;
option routers 192.168.42.1;
option domain-name "local";
option domain-name-servers 192.168.42.1;
}

subnet 192.168.43.0 netmask 255.255.255.0 {
range 192.168.43.10 192.168.43.50;
interface eth1;
option broadcast-address 192.168.43.255;
option routers 192.168.43.1;
option domain-name "local";
option domain-name-servers 192.168.43.1;
}

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

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

The classless static route option (RFC3442) will give us some headache with certain AP under certain conditions (see also here). Therefore we will 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;
4. 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)     Tethering-internet or cable (external ethernet adapter)
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)     Cellular-internet or USB dongles
PPP0         WLAN0(+ETH0)     Cellular-internet

 At the beginning, only the standard /etc/network/interface — listed below — is necessary. Depending on your choice in the TorBox menu, this file will be 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

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

iface wlan0 inet static
  address 192.168.42.1
  netmask 255.255.255.0

iface eth1 inet static
  address 192.168.43.1
  netmask 255.255.255.0

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

# Replace /etc/hostapd/hostapd.conf with the following content:
interface=wlan0
driver=nl80211
ssid=TorBox030
country_code=US
hw_mode=g
channel=6
ieee80211n=1
ieee80211ac=1
wmm_enabled=1
#ht_capab=[HT40-][HT40+][SHORT-GI-20][SHORT-GI-40][DSSS_CCK-40]
#vht_oper_chwidth=1
#vht_oper_centr_freq_seg0_idx=42
macaddr_acl=0
auth_algs=1
ignore_broadcast_ssid=0
wpa=2
wpa_passphrase=CHANGE-IT
wpa_key_mgmt=WPA-PSK
rsn_pairwise=CCMP

Important
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! TorBox will change this file along to your selection in the configuration sub-menu. However, if you delete values (even the ones with #), TorBox will not re-add them again!

# Edit /etc/default/hostapd
sudo nano /etc/default/hostapd

# Old entry:
#DAEMON_CONF=""

# New entry:
DAEMON_CONF="/etc/hostapd/hostapd.conf"

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
6. Configuring Network Address Translation (NAT)
# Edit /etc/sysctl.conf:
sudo nano /etc/sysctl.conf

# Old entry:
#net.ipv4.ip_forward=1

# New entry:
net.ipv4.ip_forward=1

# 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"
7. Installing and configuring Tor

First step: Installing the latest stable version of Tor
By default, Raspbian offers an old stable package of Tor (version 0.3.5.x). We did install it during updating the system and installed already all necessary packages. However, we should install the latest version of Tor (currently version 0.4.2.x) to benefit from the bug fixes and improvements.

# We have to edit /etc/apt/sources.list to add the Tor repository:
sudo nano /etc/apt/sources.list

# We have to add the following repositories:
deb https://deb.torproject.org/torproject.org buster main
deb-src https://deb.torproject.org/torproject.org buster main

# Then execute following commands:
cd
sudo curl https://deb.torproject.org/torproject.org/A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89.asc | sudo apt-key add -
sudo apt-get update
sudo apt-get -y install tor deb.torproject.org-keyring

Second 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
## DON'T CHANGE THE FOLLOWING 13 LINES!
######################################################
## Configuration for TorBox

Log notice file /var/log/tor/notices.log
VirtualAddrNetworkIPv4 10.192.0.0/10
AutomapHostsSuffixes .onion,.exit
AutomapHostsOnResolve 1
TransPort 192.168.42.1:9040
#TransPort 192.168.43.1:9040
DNSPort 192.168.42.1:9053
#DNSPort 192.168.43.1:9053
SocksPort 192.168.42.1:9050
#SocksPort 192.168.43.1:9050
DisableDebuggerAttachment 0
ControlPort 9051
HashedControlPassword 16:E68F16640ED8C0F7601F5AA3D229D8DFD8715623CB055577F9434F7FB7

## THE CONFIGURATION OF THE BRIDGE RELAY STARTS HERE!
######################################################
## This will setup an obfs4 bridge relay.
#BridgeRelay 1
#ORPort 4235
#ExtORPort auto
#ServerTransportPlugin obfs4 exec /usr/bin/obfs4proxy
#ServerTransportListenAddr obfs4 0.0.0.0:443
#ContactInfo <[email protected]>
#Nickname TorBox030

## TO OVERCOME A FIREWALL, START HERE!
## HOWEVER, USE IT ONLY, IF REALLY NECESSARY!
######################################################
## 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 99.0.0.0/8, reject 18.0.0.0/8:80, 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

## TO OVERCOME CENSORSHIP, START HERE!
######################################################
## 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 obfs4 exec /usr/bin/obfs4proxy

## ...and add your bridges below (the bridges below are examples which may or
## may not work. Uncomment to use them). Please give us feedback, if some of
## the bridges below doesn't work anymore: [email protected]
##
## You have two 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, Gmail or Yahoo with "get transport obfs4" in the
##    body of the mail.

Important
Don’t remove or change the “#-lines”. TorBox will change this file automatically. If you delete values (even the ones with #), TorBox will not re-add them again and TorBox may not work properly!

You should change the “HashedControlPassword” at the end of the installation with the help of the configuration sub-menu entry 8.

Third step: Configuring obfs4proxy

# Execute following commands:
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]

Fourth step: Activate Tor

# Execute following commands:
sudo systemctl unmask tor
sudo systemctl enable tor
sudo systemctl start tpr
sudo systemctl daemon-reload
8. Configuring the Wireless Interface Connection Daemon (wicd)

The Wireless Interface Connection Daemon (wicd) is an easy to use network connection manager. It provides a graphical text-interface to choose, configure and connect to a wireless network. Usually, it is not necessary to run it manually. If needed, the TorBox will start it for you.

# Edit /etc/wicd/manager-settings.conf
sudo nano /etc/wicd/manager-settings.conf

# Change following lines (yes, eth2 is right!):
wireless_interface = wlan1
wired_interface = eth2
dhcp_client = 1

# Edit /etc/wicd/wired-settings.conf
sudo nano /etc/wicd/manager-settings.conf

# Change following line
dhcphostname = TorBox030
9. Installing the TorBox Menu

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 or a SSH-client access TorBox’s IP address (192.168.42.1). 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”. If necessary, the menu can be started there with “./menu”. To install the menu, use the following commands (or download the complete TorBox repository from our GitHub page):

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

# Edit .profile:
sudo nano .profil

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

# Add the following lines at the end of /etc/rc.local, bot befor "exit 0":
sudo /sbin/iptables-restore < /etc/iptables.ipv4.nat
sudo service dnsmasq start
sleep 10
sudo /usr/sbin/ntpdate pool.ntp.org
sudo service dnsmasq stop

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

# Replace /etc/iptables.ipv4.nat with the following content:
*filter
:INPUT DROP [2785:306676]
:FORWARD DROP [71:4544]
:OUTPUT ACCEPT [1011779:1380260141]
-A INPUT -m state --state RELATED,ESTABLISHED -j ACCEPT
-A INPUT -m state --state INVALID -j DROP
-A INPUT ! -s 192.0.0.0/8 -i wlan0 -j LOG --log-prefix "SPOOFED PKT "
-A INPUT ! -s 192.0.0.0/8 -i eth0 -j LOG --log-prefix "SPOOFED PKT "
-A INPUT ! -s 192.0.0.0/8 -i wlan0 -j DROP
-A INPUT ! -s 192.0.0.0/8 -i eth0 -j DROP
-A INPUT -i lo -j ACCEPT
-A INPUT -i wlan0 -j ACCEPT
-A INPUT -i eth0 -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 127.0.0.1/32 ! -d 127.0.0.1/32 ! -o lo -p tcp -m tcp --tcp-flags RST,ACK RST,ACK -j DROP
-A OUTPUT -o wlan1 -p tcp -m tcp --dport 53 -j LOG --log-prefix "SSH SHELL DNS-REQUEST TCP" --log-tcp-options --log-ip-options
-A OUTPUT -o wlan1 -p udp -m udp --dport 53 -j LOG --log-prefix "SSH SHELL DNS-REQUEST UDP" --log-ip-options
COMMIT
#
#
*nat
:PREROUTING ACCEPT [4956:869847]
:INPUT ACCEPT [4496:607791]
:POSTROUTING ACCEPT [200:15526]
:OUTPUT ACCEPT [370:37403]
-A PREROUTING -d 192.168.42.1/32 -i wlan0 -p tcp -j REDIRECT
-A PREROUTING -d 192.168.43.1/32 -i eth0 -p tcp -j REDIRECT
-A PREROUTING -i wlan0 -p tcp -j REDIRECT --to-ports 9040
-A PREROUTING -i eth0 -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 eth0 -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 eth0 -p udp -j REDIRECT --to-ports 9040
-A POSTROUTING -o wlan1 -j MASQUERADE
COMMIT

 Make sure that the SSH-client will be able to access the TorBox after the restart:

# Execute following commands:
sudo systemctl unmask ssh
sudo systemctl enable ssh
sudo systemctl start ssh
10. Restart your system
# Execute the following command
sudo reboot

After restarting your system, choose the preferred connection setup and change the default passwords as soon as possible. Check if your data stream is routed through the Tor network: https://check.torproject.org

For more information about TorBox, take a look in our documentation.