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.

Table of contents
1. Update your system and install all necessary packages
2. Disable Bluetooth
3. Setting up a DHCP server
4. Setting up network interfaces
5. Configuring the TorBox AP
6. Configuring Network Address Translation (NAT)
7. Installing and configuring Tor
8. Configuring the Wireless Interface Connection Daemon
9. Installing the “TorBox Menu”

• • •

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 firmware, the packet list and the installed packages 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 needed.

Following packages are necessary:

  • 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 -> other usefull 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 install hostapd isc-dhcp-server tor obfs4proxy usbmuxd wicd\
dnsmasq dnsutils tcpdump iftop vnstat links2 debian-goodies dirmngr\
python3-setuptools ntpdate screen nyx

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

sudo update-rc.d dnsmasq disable

 
Go up to the table of contents

• • •

2. Disable Bluetooth

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

  1. Change your /boot/config.txt:
    sudo nano /boot/config.txt 
    
  2. Add following line at the end of the file:
    # ADDED: Disabling on-board Bluetooth
    dtoverlay=pi3-disable-bt
    
  3. Disable related services:
    sudo systemctl disable hciuart.service
    sudo systemctl disable bluealsa.service
    sudo systemctl disable bluetooth.service
    
  4. Remove the Bluetooth stack to make Bluetooth unavailable even if external Bluetooth adapter is plugged in:
    sudo apt-get purge bluez -y
    sudo apt-get autoremove -y
    

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

 
Go up to the table of contents

• • •

3. Setting up a DHCP server

 

  1. Set up your hostname (for example “TorBox” instead of “rasperypi”):
    sudo nano /etc/hostname 
    sudo nano /etc/hosts  
    
  2. Adjust the configuration file of the DHCP server (dhcpd.conf):
    sudo nano /etc/dhcp/dhcpd.conf 
    

    Change following lines:

    option domain-name "example.org"; —>  #option domain-name "example.org";
    option domain-name-servers ns1.example.org, ns2.example.org; —> #option 
    domain-name-servers ns1.example.org, ns2.example.org; 
    #authoritative; —> authoritative;
    

    Add following lines at the end of the file:

    subnet 192.168.42.0 netmask 255.255.255.0 {
    range 192.168.42.10 192.168.42.50;
    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;
    }
    
  3. Adjust the configuration file of the DHCP server (isc-dhcp-server):
    sudo nano /etc/default/isc-dhcp-server
    

    Change following line:

    INTERFACESv4="" -> INTERFACESv4="wlan0 eth0"
    
  4. Remove classless static route option_
    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:

    sudo nano /etc/dhcp/dhclient.conf
    

    Change following lines:

    option rfc3442-classless-static-routes code 121 = array of unsigned integer 8; -> 
    #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; ->
    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;
    

Go up to the table of contents

• • •

4. Setting up network interfaces

Currently, TorBox supports the following connections:

INPUT client <—> OUTPUT internet  MODE      Remarks
WLAN0            ETH0             WIRELESS  Cable-internet
WLAN0            WLAN1            WIRELESS  Wireless-internet
WLAN0            ETH1             WIRELESS  Tethering-internet
-----------------------------------------------------------------------
ETH0             ETH1 (via USB)   CABLE     Cable-cable-connection 
ETH0             WLAN0            CABLE     Cable-Wireless-connection
ETH0             ETH1             CABLE     Tethering-internet

 
By default, TorBox provides an AP at wlan0. Some testers requested a way to connect a device with an ethernet cable only (currently, it is not possible to have both, wireless and wired clients at the same time). This requires two different “/etc/network/interfaces” – one for wlan0 and another for eth1.

 

  • First step: /etc/network/interfaces.wlan (for the WLAN0 configuration)
    sudo nano /etc/network/interfaces.wlan
    

    Add the following lines:

    auto lo
    
    iface lo inet loopback
    iface eth0 inet dhcp
    iface eth1 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
    
    wireless-power off
    
  •  

  • Second step: /etc/network/interfaces.eth1 (for the ETH1 configuration)
    sudo nano /etc/network/interfaces.eth1
    

    Add the following lines:

    auto lo
    
    iface lo inet loopback
    iface eth0 inet dhcp
    iface wlan0 inet dhcp
    iface wlan1 inet dhcp
    allow-hotplug wlan0 wlan1 eth0 eth1
    
    iface eth1 inet static
      address 192.168.42.1
      netmask 255.255.255.0
    
    wireless-power off
    
  •  

  • Third step: set default configuration
    At the beginning, we will use the default configuration (TorBox will act as AP and accept connections from wireless clients):

    cp /etc/network/interfaces /etc/network/interfaces.ORIG
    cp /etc/network/interfaces.wlan /etc/network/interfaces
    sudo ifdown wlan0
    sudo ifup wlan0
    

Go up to the table of contents

• • •

5. Configuring the TorBox AP

This is the AP (on wlan0), which the client-devices is connected by default.

sudo nano /etc/hostapd/hostapd.conf

 
Change or add following lines:

interface=wlan0
driver=nl80211        
ssid=TorBox024
hw_mode=g
channel=6
ieee80211n=1
wmm_enabled=1
ht_capab=[HT40][SHORT-GI-20][DSSS_CCK-40]
macaddr_acl=0
auth_algs=1
ignore_broadcast_ssid=0
wpa=2
wpa_passphrase=CHANGE-IT
wpa_key_mgmt=WPA-PSK
rsn_pairwise=CCMP

 

sudo nano /etc/default/hostapd

 
Change following line:

#DAEMON_CONF="" —> DAEMON_CONF="/etc/hostapd/hostapd.conf"

 
To start the AP and the DHCP manually, use the following commands:

sudo systemctl unmask hostapd
sudo systemctl enable hostapd
sudo systemctl start hostapd
sudo systemctl start isc-dhcp-server

 
To automatically start AP and DHCP at boot, use following commands:

sudo update-rc.d hostapd enable
sudo update-rc.d isc-dhcp-server enable 

 
Go up to the table of contents

• • •

6. Configuring Network Address Translation (NAT)

sudo nano /etc/sysctl.conf

 
Change following line:

#net.ipv4.ip_forward=1 -> net.ipv4.ip_forward=1

 
Enable “IP forward” to deal with captive portals:

sudo sh -c "echo 1 > /proc/sys/net/ipv4/ip_forward"

 
Go up to the table of contents

• • •

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 installing all necessary packages (see here). If you like to stay with the older version, you can skip this subsection. Otherwise, this subsection will install a newer stable version of Tor (0.4.0.x), which is highly recommended.

    sudo nano /etc/apt/sources.list
    

     
    Add following lines:

    deb https://deb.torproject.org/torproject.org buster main
    deb-src https://deb.torproject.org/torproject.org buster main
    

     
    Execute following commands:

    gpg --keyserver keys.gnupg.net --recv A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89
    gpg --export A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 | sudo apt-key add -
    sudo apt-get update
    sudo apt-get install build-essential fakeroot devscripts
    sudo apt build-dep tor deb.torproject.org-keyring
    if [ -d debian-packages ] ; then rm -r debian-packages ; fi
    mkdir ~/debian-packages; cd ~/debian-packages
    apt source tor; cd tor-*
    debuild -rfakeroot -uc -us; cd ..
    sudo dpkg -i tor_*.deb
    
  •  

  • Second step: Configuring Tor
    sudo nano /etc/tor/torrc
    

     
    Replace the content of /etc/tor/torrc with:

    ## 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
    DNSPort 192.168.42.1:9053
    SocksPort 192.168.42.1:9050
    DisableDebuggerAttachment 0
    ControlPort 9051
    HashedControlPassword <hashpassword> 
    
    ## TorBox: This is the configuration for bridges to circumvent censorship
    #UseBridges 1
    #UpdateBridgesFromAuthority 1
    #ClientTransportPlugin obfs4 exec /usr/bin/obfs4proxy
    #Bridge obfs4 80.220.197.84:41043 6743F2AA0F9BD302AFD1AE41F83D5FE1C70159CE cert=0ITGWcBzMRj1dgzUxpcsW0lYbSWNzUZrAaq/syk++Yd6Znh0qLBhzsIAupUdrIPOsSxsFg iat-mode=0
    

     
    Use following command to generate :

    tor --hash-password <password>
    

    You have to copy the entire hash-string, including “16:”. Later, we have to copy that hash-string into the file ~/torbox/new_ident under the entry “PASSWORD=”””
     
    To create the necessary log-files, to start tor manually and to ensure the automatic start, whenever you boot your Raspberry Pi, use following commands:

    sudo mkdir /var/log/tor
    sudo touch /var/log/tor/notices.log
    sudo chown debian-tor /var/log/tor/notices.log
    sudo service tor start
    sudo update-rc.d tor enable
    
  •  

  • Third step: Configuring obfs4proxy
    sudo setcap 'cap_net_bind_service=+ep' /usr/bin/obfs4proxy
    

Go up to the table of contents

• • •

8. Configuring the Wireless Interface Connection Daemon

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 menu” (see below) will start it. Nevertheless, you should change or add following settings before you use it:

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

 
Change under “[Settings]” the already existing entries to:

wireless_interface = wlan1
wired_interface = eth0
dhcp_client = 1 

Regarding “dhcp_client”: wicd should always use dhclient!! Dhcpcd doesn’t work correctly under certain conditions.

sudo nano /etc/wicd/wired-settings.conf

 
Change under “[wired-default]” the already existing entries to:

dhcphostname = TorBox024

 
Go up to the table of contents

• • •

9. Installing the “TorBox Menu”

“TorBox Menu” gives a relatively user-friendly possibility to use and change the settings of your TorBox. The menu is automatically started, whenever an 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):

cd
wget http://www.torbox.ch/data/torbox024-rpi4-20190808.zip
sudo unzip torbox024-rpi4-20190808.zip
sudo mv torbox024-rpi4-20190808 torbox
sudo nano .profile

 
Add following lines to the end of “.profile”:

cd torbox
sleep 2
./menu

Optionally, in “~/torbox/etc/motd” you can find a logo, which you can copy into your “/etc/motd”.
To change the password of the tor control port (previously added as hash in the file “/etc/tor/torrc”), use following command:

sudo nano ~/torbox/new_ident

 
Change or add following line:

PASSWORD="<password>"

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

sudo nano /etc/rc.local

 
Change or add following lines (after the last “fi” and before “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

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

sudo update-rc.d ssh enable

 
Start “TorBox menu” manually and do a first-time configuration:

cd
cd torbox
./menu

Choose the preferred connection setup and change the default passwords as soon as possible (the associated entries are placed in the advanced menu). Check if your date are routed through the Tor network: https://check.torproject.org

 
Go up to the table of contents