After installing TorBox either by using the image file and the corresponding start-up instruction or by running our installation script (EXPERIMENTAL!) or manually according to our detailed manual, TorBox can be accessed with an SSH-client either by the TorBox’s WLAN (password: CHANGE-IT) and/or by an Ethernet connection. To establish a connection between the SSH-client and TorBox, use 192.168.42.1 (username: pi / password: CHANGE-IT); with an Ethernet connection, use 192.168.43.1 (username: pi / password: CHANGE-IT). Afterward, the main menu automatically starts. The primary purpose of the main menu is to offer a simple way of changing connection modes. The main menu also offers access to additional sub-menus.
Starting with TorBox v.0.3.0, there is no separate wired/wireless mode anymore. By default, clients are served wireless. However, if a client is connected via ethernet cable to the TorBox, whether using the onboard or external ethernet adapter, then additionally the TorBox functionality is automagically enabled for that client, too.
In the following, we look at all menu entries one by one:
- Menu entry 1: Tor statistics: This menu entry starts Nyx, a very informative statistic tool. Besides showing the actual data transfer rate and the last log messages, you can also get a new identity or reset Tor. Press “h” to display a brief help window, “m” to activate a simple pull-down menu, and use twice “q” to quit the statistics.
Important: Nyx, which shows the Tor statistics, uses the control port of the local Tor installation. Unfortunately, it shows you only a black screen with a blinking cursor if Tor gets stuck in its boot process (possible due to network problems or censorship). In this case, take Menu entry 3 “Show the Tor log file – quick and dirty”. The screen updates automatically when a new entry is written to the log file. Press CTRL-C to leave the log.
- Menu entry 2: Enforce a new exit node with a new IP: The title of this menu entry is without doubt self-explanatory. By default, Tor changes all 10 minutes its circuit, which results in a change of the external IP address. With this menu entry, you force an immediate change. This can solve problems with unresponsive or slow circuits, or blocked IPs from known exit nodes. Notice: Even if the middle and exit nodes change, the entry guard remains the same. That’s intentional: a fast and stable relay remains as entry guard in your circuit for 2-3 months to protect against a known anonymity-breaking attack (for more information, see here). However, you have more reset possibilities in the “Go to the update and reset sub-menu…” (menu entry 12).
- Menu entry 3: Show the Tor log file – quick and dirty: As the name says, the Tor log file is displayed and automatically refreshed when new entries are added. This is useful when connection errors occur, and Nyx (Menu entry 1) cannot be started.
- Menu entries 4-8: With these menu entries, you can choose and change from where you get the Internet from.
Currently, TorBox supports the following connections (listed as in the main menu):
INTERNET CLIENT(S) Remarks -------------------------------------------------------------------------------------------- ETH0 WLAN0(+ETH1) Cable-Internet (onboard ethernet adapter) - STANDARD 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, USB dongle or Tethering (Android) (ppp0; usb0) PPP0 WLAN0(+ETH0) Cellular-Internet ETH1 WLAN0(+ETH0) USB ethernet adapter or Tethering (iOS)
Important: For menu entries 5 and 6 an additional USB-WiFi adapter is required in most cases.
Also important: You can only use one Internet connection. Especially if you don’t get the Internet via Ethernet cable (eth0), you have to remove it. Otherwise, TorBox thinks that you have a client on that cable, which is not the case and probably will block loading Tor (this is the case if the menu entry 3 shows you just a blank screen).
“Open access” or “captive portal”
All connection setting menu entries support “open access” or “captive portal”. “Open access” means that you already have entered a password to access the provided network, and you don’t have to fill out an additional login/authentication page. By contrast, “captive portal” are additional login pages, for which you have to register. If unsure, chose “captive portal”.
Important: TorBox is configured as a DHCP client, which means that the router has to give TorBox all necessary network information (usually, the router is configured like that). If that doesn’t work, check out this FAQ entry.
- Menu entry 9: Go to the countermeasure sub-menu…: This sub-menu deals with the circumvention of censorship by using bridges. It allows you to enable, disable or/and configure the bridge mode easily. Furthermore, it offers a measure against a disconnection if the connection is not used.
- Menu entry 10: Go to the configuration sub-menu…: This sub-menu gives you the ability to change some basic configurations like passwords, the name of the TorBox WLAN, its regulatory domain, the frequency, and the channel. Currently, two additional hardware accessories are supported, and the additional software can be installed from that sub-menu: Adafruit’s PiTFT displays and Sixfab Shields/HATs for cellular connections.
- Menu entry 11: Go to defend the open Internet…: This sub-menu offers you a simple way to set up a bridge relay. However, to do so, you need a public IP address, 24/7 Internet connectivity over a long time, and a bandwidth of at least 1 Mbps. By setting up an obfs4 bridge, you can help censored users connect to the open Internet through Tor.
- Menu entry 12: Go to the update and reset sub-menu…: This sub-menu helps you to update and, if necessary, to reset your TorBox. Solely chose in the displayed list what tasks you like to have to be performed.
- Menu entries 13 and 14: Reboot / Shutdown: These two menu entries are quite self-explanatory.
• • •
Pressing the ESC key exits the TorBox main menu, and you are taken to the command line. This gives you full access to your entire system. You can reload the menu with the command ./menu in ~/torbox. The menu is reloaded each time when you open a new console. If you like to avoid that, then use the following procedures:
cd sudo nano .profile
Remove the following lines at the end of .profile:
cd torbox sleep 2 ./menu
Important: Network transfers from the command line do not pass through Tor and are, therefore, by default, not secured or anonymized.
• • •
“TOR is working”
A little message (“TOR is working”) in the right corner of the main menu shows you immediately if you are connected with the Tor network (meaning https://check.torproject.org returns a positive result). Since a missing response does not automatically mean that there is no connection to the Tor network, no error message is displayed. In other words, if this message is missing, there may or may not be a connection problem.
Using the network manager (wicd)
Whenever you select a wireless network as your Internet source, the network manager is getting started, and the list with available wireless networks is refreshed three times — please be patient. Afterward, choose the specific wireless network with the up-/down-arrow-keys and press the right-arrow-key. Always activate “Use these settings for all networks sharing this essid” and “Automatically connect to this network”. If necessary, toggle “Use encryption” on, usually select “WPA 1/2 (Passphrase)” and write the password in the field below. Save with SHIFT-S. Back in the list with the available wireless networks, press SHIFT-P and choose “Automatic Reconnection” “Automatically reconnect on connection loss”. Save again with SHIFT-S.
After this procedure, check again, if the designated wireless network is still selected and press ENTER or SHIFT-C. Wait a minute or two. The connection was successful if you can read “Connected to…” in the left corner.
Important: Occasionally, the network manager has some problems with saved configuration. This may result in crashing when trying to change the configuration of a network (e.g., using the right-arrow-key) or not loading at all. In this case, go to the update and reset sub-menu, select entry 7 “Reset network manager (anti-crash)”, and press ok.
• • •
Problems and questions
- I can’t get tethering to work. What’s wrong with it? –> see here.
- I’m connected to TorBox with an ethernet cable, and all is working as expected. However, when I change my Internet to “Wireless network”, I’m not able to connect to the Internet anymore. –> see here.
- My client, which is connected to the TorBox, doesn’t receive an IP address. –> see here.
- My TorBox doesn’t receive an IP address from the network router. –> see here.
- My TorBox receives an IP address (192.168.42.* or 192.168.43.*) from the network router, but it doesn’t work. –> see here.
- Tor statistics don’t show up — the screen stays black. What can I do? –> see here.
- Which SSH client do you prefer? –> see here.
- Wicd (the network manager) doesn’t show me all wireless networks! It seems that the ones on the 5GHz band are missing. What can I do? –> see here.
- Wicd (the network manager) tries to connect a wireless network, but it sticks with “Validating authentication”, the program crashes and/or seems to have many bugs. What’s wrong? –> see here.