I want to build it from scratch! (pre-v.0.23)

Manual Version 0.5.1 (02.12.2018)

This manual is written for Raspbian “Stretch” Lite (based on Debian 9 “Stretch”) on a Raspberry Pi 3 (Model B or Model B+). We suppose that you already did the basic configurations with raspbi-config (localization, keyboard layout and so on), that your Raspbian installation is working properly, that it has access to the internet and a sufficient power supply (see also FAQ #16 “Under-voltage detected!” – What does it mean).

Table of contents
1. Prepping your system
2. Setting up a DHCP server
3. Setting up network interfaces
4. Configuring the TorBox AP
5. Configuring Network Address Translation (NAT)
6. Installing and configuring Tor
7. Configuring the Wireless Interface Connection Daemon
8. Installing the TorBox Menu
9. A remark to the “Tethering” option

• • •

1. Prepping your system

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 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 what was updated (firmware, kernel, driver …), you should probably reboot your Raspberry Pi before continue.

Following packages are necessary:

  • hostapd -> will provide a wireless access point (AP);
  • isc-dhcp-server -> will act as our DHCP server;
  • tor -> will give us access to the Tor network;
  • gvfs, gvfs-fuse, gvfs-backends, gvfs-bin, ipheth-utils, libimobiledevice-utils, usbmuxd -> will support tethering devices;
  • wicd, wicd-curses -> this is 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 -> analytical network tools;
  • termsaver, slurm, iftop, vnstat, links2 -> terminal screen saver and statistic tools (partially necessary for the TorBox menu);
  • debian-goodies -> other usefull tools.
  • dirmngr -> GNU privacy guard – network certificate management service
  • python3-setuptools -> Necessary tools for Python 3
  • ntpdate -> A client for setting system time

With following command, you are able to install all necessary packages:

sudo apt-get install hostapd isc-dhcp-server tor gvfs gvfs-fuse gvfs-backends\
gvfs-bin ipheth-utils libimobiledevice-utils usbmuxd wicd wicd-curses dnsmasq\
dnsutils tcpdump termsaver slurm iftop vnstat links2 debian-goodies\
dirmngr python3-setuptools ntpdate

 
Installing “nyx” – a command-line monitor for Tor:

sudo easy_install3 pip
sudo pip3 install nyx

 
Go up to the table of contents

• • •

2. Setting up a DHCP server

Set up your hostname (for example “TorBox” instead of “rasperypi”)

sudo nano /etc/hostname 
sudo nano /etc/hosts  

 
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;
}

 
Adjust the configuration file of the DHCP server (isc-dhcp-server):

sudo nano /etc/default/isc-dhcp-server

 
Change following line:

INTERFACESv4="" -> INTERFACESv4="wlan0 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:

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

• • •

3. Setting up network interfaces

Currently TorBox supports following connections:

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

By default, TorBox will provide an AP at wlan0. Nevertheless, 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. But there is no need to type in all the below-mentioned configuration — you will find all configuration files in the “TorBox Menu” file under /etc (see below under “8. Install the TorBox Menu“). If you have downloaded the TorBox Menu” and copied the files into /etc of your Raspberry Pi, you can skip the rest below.

First step: /etc/network/interfaces.wlan0 (for the WLAN0 configuration)

sudo nano /etc/network/interfaces.wlan0

 
Add 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 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.wlan0 /etc/network/interfaces
sudo ifdown wlan0
sudo ifup wlan0

 
Go up to the table of contents

• • •

4. Configuring the TorBox AP

This is the AP (on wlan0), which the client-devices will be connected to (you will find hostapd.conf in the “TorBox Menu” file under /etc/hostapd).

sudo nano /etc/hostapd/hostapd.conf

 
Change or add following lines:

interface=wlan0
driver=nl80211        
ssid=TorBox023
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
wpa_pairwise=TKIP
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 following commands:

sudo service hostapd start
sudo service isc-dhcp-server start

 
To automatically start it, whenever you boot your Raspberry Pi, use following commands:

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

 
Go up to the table of contents

• • •

5. Configuring Network Address Translation (NAT)

sudo nano /etc/sysctl.conf

 
Change following line:

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

 
We have to 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

• • •

6. 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.2.9.x). We did install it during the prepping of your system (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.3.3.x), which is highly recommended.

sudo nano /etc/apt/sources.list

 
Add following lines:

deb https://deb.torproject.org/torproject.org stretch main
deb-src https://deb.torproject.org/torproject.org stretch 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
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

 
Change or add following lines:

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
DisableDebuggerAttachment 0
ControlPort 9051
HashedControlPassword <hashpassword>   

 
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

 
Go up to the table of contents

• • •

7. 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
dhcp_client = 1 

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

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

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

dhcphostname = TorBox023

 
Go up to the table of contents

• • •

8. Installing the TorBox Menu

With the TorBox Menu, we will give you a relativ user-friendly possibility to use and change the settings of your TorBox. The menu will be automatically started, whenever someone connect TorBox with an SSH client on the TorBox’s IP address (192.168.42.1). It is based on shell scripts, which will set the correct packet filtering and NAT rules as well as starts other supporting tools. All scripts are located under “~/torbox”. They can be started manually with “sudo sh shellskript” which shouldn’t be necessary. To install the menu, use following commands:

cd
wget http://www.torbox.ch/data/torbox023-pre-20181202.zip
sudo unzip torbox023-pre-20181202.zip
sudo nano .profile

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

cd torbox
sleep 2
sh menu

Optionally, in “~/torbox/etc/motd” you will find a logo, which you could copy into your “/etc/motd”.
For changing the password for the tor controlport (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 have to edit “/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”):

sleep 10
ntpdate pool.ntp.org
service dnsmasq stop
iptables-restore < /etc/iptables.ipv4.nat
exit 0

 
We want to be sure that we will be able to log into the TorBox via SSH after the restart:

sudo update-rc.d ssh enable

 
Start the TorBox menu manually and do a first time configuration:

cd
cd torbox
sh menu

Select menu entry number 4 and press enter
Select menu entry number 9 and press enter
Select menu entry number 11 and press enter

Restart TorBox and login with your SSH client.
Finally, you should be able to connect https://check.torproject.org and it should use Tor.

 
Go up to the table of contents

• • •

9. A remark to the “Tethering” option

If you use tethering via USB your smartphone will probably charge its battery. This could be problematic: If the Raspberry Pi doesn’t receive enough power (indicated by a flashing red LED), you eventually will be unable to connect to the AP of an internet provider or will experience all sorts of other strange behaviors. A better solution may be to create a personal hotspot with your smartphone instead of using tethering. Anyway, if you are using the tethering option, you should remove other power consumption devices and make sure that your Raspberry Pi has the best power source as you can get. For example the RS Pro PB-10400 Power Bank, 5V / 10,4Ah worked well with us.

Using tethering is simple. For example in case of an iPhone: Unlock your iPhone, but let the personal hotspot disabled for the time beeing and connect it with your Raspberry Pi’s USB port. Choose to trust your iPhone (necessary!). Enable personal hotspot on your iPhone (USB only). Finally, in the TorBox menu, use entry number 8.