Internet-in-a-Box (IIAB) Networking

Simple Option: Learning Hotspot Inside

If your Internet-in-a-Box (IIAB) device contains Wi-Fi hardware capable of AP mode (Access Point mode, e.g. to broadcast to many students) it’s likely already working as a Learning Hotspot for your community (i.e. if you installed IIAB software) and you should be all set! CONTEXT: This layout is by far the most popular — especially with Raspberry Pi’s and laptops — and also for example with Intel NUC Mini PC’s containing Wi-Fi hardware capable of supporting 12 WiFi client [student] devices. Optionally a few common customizations are possible, in which case you may want to get to know the sudo iiab-hotspot-off and sudo iiab-hotspot-on commands.

If however your IIAB device does not contain Wi-Fi hardware capable of AP mode, please read about the three network modes below. You’ll want to get to know the sudo iiab-network command (to finalize your networking configuration) as well learning about common customizations in general.

ADVANCED: You might also want to attach an external Wi-Fi Access Point or Wi-Fi router to your IIAB, e.g. to expand the number of Wi-Fi client [student] devices. CAVEAT: Field/Operations communities generally dislike such spaghetti wiring/power/installation/configuration/maintenance complexities as compared to KISS (e.g. underpaid teachers especially, who strongly prefer All-in-One self-contained Internet-in-a-Box devices, that are battle-tested!)

Three Network Modes

IIAB supports three possible network modes:

• Appliance - your IIAB server acts as any other computer on an already existing network, but exposes its IIAB content and apps/services to the network. Your IIAB can have a single network interface (we refer to this as the WAN, whether or not it can reach the Internet).
• Gateway - allows for creating a local area network, using dnsmasq, content filtering using a web-caching proxy (e.g. Squid) and traffic shaping. Your IIAB must have two or more network interfaces (WAN side and LAN side).
• LAN Controller - allows for creating a local area network, using dnsmasq. Your IIAB can have a single network interface (we refer to this as the LAN).

IIAB’s installer (or the sudo iiab-network command) first seeks out the WAN interface, defaulting to Appliance mode. It then tries to find other network interfaces for use with the LAN, and if found defaults to Gateway mode.

Finally, you need to make some adjustments to be able to use LAN Controller mode, so that all available network interfaces live under the LAN a.k.a. bridge (August 2022 tips at #3330, for Ubuntu especially).

Know Your Topology (and IP Addresses)

IIAB’s WAN side IP address is normally assigned by whatever DHCP device manages your network (though it’s possible to set a fixed IP address).

IIAB’s LAN (regardless whether in Gateway or LAN Controller mode) is a bridge containing one or more network interfaces, and always has the IP address 10.10.10.10. Remember, as some are confused by this, that 10.10.10.10 (AKA box.lan, or simply box) is not visible on the WAN side — but only on the LAN side — and is used by all of the bridge’s interfaces, whether wireless or wired.

Optionally, Attach a Wi-Fi Access Point or Router

Many Raspberry Pi’s support up to 32 simultaneous Wi-Fi client [student] devices (IIAB provides you WiFi firmware alternatives; if you change this, please then run cd /opt/iiab/iiab then sudo ./runrole firmware). Mini PC’s however (e.g. Intel NUC) can often handle no more than 12 Wi-Fi client [student] devices.

As such, attaching an external Wi-Fi Access Point or Router is one way to expand the number of Wi-Fi client [student] devices — e.g. in a community library where a large number of laptops, tablets and smartphones are all in use.

In Most Cases: It’s best to disable the DHCP service within your Wi-Fi Access Point or Wi-Fi Router, instead allowing IIAB’s own DHCP service (dnsmasq) to assign 10.x.x.x IP addresses to each Wi-Fi client [student] device. Do this within your Wi-Fi device’s own control panel (read the manufacturer’s instructions if necessary!)

In Other Cases: Some choose to leave the Wi-Fi device’s DHCP service enabled. If so, just be careful to think through carefully whether (1) your IIAB will assign a DHCP IP address to your Wi-Fi device (recommended!) or (2) the other way around, i.e. your Wi-Fi device will assign a DHCP IP address to your IIAB (not recommended or supported!)

FINALLY: Before running sudo iiab-network to finalize your network configuration, you need to connect your Wi-Fi Access Point(s) and/or Wi-Fi Router(s) to your IIAB, per the final “in-field” layout, and ensure they’re all turned on! EXAMPLE: If you’re going to use a wired Ethernet on the LAN side (i.e. as a “slave” interface within bridge br0, for wired and/or wireless client [student] devices) connect all cables and turn everything on, before running sudo iiab-network. ADDITIONAL WARNING: if your wired Ethernet LAN is not connected during boot, you may experience a 2-minute delay similar to PR #1634.

List of Ports / Services

Many of the port numbers below can be changed when installing IIAB. If you need to do this, look over the default ports in default_vars.yml, and then override those that are necessary within /etc/iiab/local_vars.yml

Firewall (iptables)

On the LAN side, all ports except for databases ports are generally open.

On the WAN side, “campus access” to 10+ common IIAB services like Kiwix (3000), KA Lite (8008) and Calibre (8010 or 8080) is enabled by default. Override this default by uncommenting just one of the following lines in /etc/iiab/local_vars.yml:

#ports_externally_visible: 0 # none
#ports_externally_visible: 1 # ssh only
#ports_externally_visible: 2 # ssh + http-or-https (for Admin Console's box.lan/admin too)
ports_externally_visible: 3  # ssh + http-or-https + common IIAB services  <--  DEFAULT
#ports_externally_visible: 4 # ssh + http-or-https + common IIAB services + Samba
#ports_externally_visible: 5 # all but databases

If your IIAB is already installed, run sudo iiab-network to put this firewall change into effect.

If necessary, you can further customize your iptables firewall by modifying /opt/iiab/iiab/roles/network/templates/gateway/iiab-gen-iptables (part of Ansible’s network role, this is the template for the /usr/bin/iiab-gen-iptables command). As above, you’d then need to run sudo iiab-network to put your firewall changes into effect.

To see your current firewall rules, look at file /etc/iptables/rules.v4 and use commands like iptables -L -n — also running iptables -L -v -t nat and lsmod can be useful, e.g. if verifying that ‘MASQUERADING’ is on (for IIAB’s gateway behavior, summarized below).

And if you really want to get rid of all iptables firewall rules, you can run these 3 commands.

April 2021 FYI: With iptables v1.8.5+ (nftables) evolving, PR #2728 introduced several improvements. For example, two commands now allow you to quickly enable or disable Internet for student/client devices: (IIAB’s gateway behavior)

• sudo iiab-internet-on
• sudo iiab-internet-off

WARNING: The change will persist (as part of iptables’ firewall rule set) through IIAB reboots until (1) the opposite command is run, or until (2) an Ansible command like sudo iiab-network is run, using the iiab-gateway-enabled variable’s value.

RECAP: If you want this changed more permanently (so Ansible doesn’t wipe out your setting) change variable iiab-gateway-enabled in /etc/iiab/local_vars.yml and then run: sudo iiab-network

DNS

DNS (name resolution) for LAN side clients is provided by dnsmasq.

However some Linux distributions do not function well with dnsmasq’s default service (several of these ship with systemd unit files that have a timing problem). As a result, IIAB instead uses its own iiab-dnsmasq service — to start dnsmasq at the correct time during boot. And IIAB disables the OS’s stock dnsmasq unit file across all distros, to be safe.

Finally, after your IIAB install is complete, you can monitor dnsmasq as follows:

systemctl status dnsmasq

CLARIFICATIONS

IN APPLIANCE MODE:

(1a) dnsmasq provides a caching name server, just for the IIAB box itself (on Raspberry Pi OS only).

(1b) Ubuntu 18.04+ systemd-resolved runs on 127.0.0.53 providing DNS lookups (as seen in /etc/resolv.conf).

OUTSIDE OF APPLIANCE MODE:

(2a) dnsmasq provides both DHCP and DNS server functionality for the LAN side clients. On Raspberry Pi OS, dnsmasq provides DNS lookups for the box itself.

(2b) Ubuntu 18.04+ systemd-resolved runs on 127.0.0.53 providing DNS lookups (as seen in /etc/resolv.conf). But all LAN side clients use dnsmasq.

3. On Raspberry Pi OS, note that (a) systemd service wpa_supplicant is started by the dhcpcd service (b) your building’s Wi-Fi SSID and password can be put into /etc/wpa_supplicant/wpa_supplicant.conf by running the sudo raspi-config command.

Common Customizations

1. You can change the legally-mandated Wi-Fi country code after IIAB’s installed if necessary (e.g. if your IIAB has an internal Wi-Fi hotspot). To do this:

• Set host_country_code: XX in /etc/iiab/local_vars.yml
• Run sudo iiab-network

FYI as a bonus this also generates a new unique BSSID/MAC address for your internal Wi-Fi’s ap0 interface (i.e. when wifi_up_down: True is set, to attempt AP+STA mode, as briefly explained around Line 92 of /etc/iiab/local_vars.yml).

2. In addition to IIAB’s learning hotspot, you can also connect your IIAB to the Internet — using the very same Wi-Fi hardware inside your IIAB — if it supports AP+STA mode. WARNING: Not all Wi-Fi firmware supports this, and bandwidth/security may suffer! But if your IIAB is a Raspberry Pi, you can try these 3 commands at the Linux command-line:

1. After IIAB’s software is fully installed, run sudo iiab-hotspot-off
2. Connect your IIAB to the building’s Wi-Fi Internet — e.g. by running sudo raspi-config on Raspberry Pi OS, to enter the building’s 2.4 GHz SSID and its password (do not use 5.0 GHz!) Or do the same thing using IIAB’s Admin Console (box.lan/admin) > Control > Wifi Control. Or if you must, use the graphical widget in the top-right of your Linux OS’s desktop.
3. Run sudo iiab-hotspot-on then Reboot, to verify that “student” Wi-Fi devices can once again connect to your IIAB! Note: “student” Wi-Fi devices (i.e. your IIAB’s Wi-Fi client devices) are blocked from accessing the Internet by default.

3. If you want to hard-code a Fixed IP Address on the WAN side of your IIAB, see “How do I set a static IP address?” at FAQ.IIAB.IO

4. If your Internet-in-a-Box (IIAB) contains multiple Wi-Fi interfaces, put the following into /etc/iiab/local_vars.yml to ask IIAB not to create a LAN side access point on the (for example) wlan0 interface:

   reserved_device: wlan0

This is used to exclude the listed device during network detection, and for calculation of br0’s (i.e. LAN side) member/slave devices. See also: #2610, PR #2682, PR #3334.

Context: IIAB code defaults to the highest numbered when setting up a Wi-Fi hotspot, e.g. IIAB would normally use wlan1 anyway, if it found both {wlan0, wlan1}. So in this case reserved_wifi: wlan0 just avoids ambiguity, explicitly confirming that wlan0 should remain unused by IIAB.

You’d typically do this to force wlan0 onto the WAN side (e.g. for possible Internet access, or other purposes) of your IIAB. Guaranteeing that your wlan1 becomes the “learning hotspot” Wi-Fi access point on the LAN side — i.e. under the bridge (br0) — as shown by running brctl show (or try bridge -d link). Background at: #531

5. These 2 lines are important defaults in /etc/iiab/local_vars.yml originating from mid-2017:

• ports_externally_visible: 3       (read above to modify your firewall settings for different kinds of campuses/SOHO/families)
• iiab_gateway_enabled: False       (blocks LAN side users from reaching the Internet, while permitting them access to IIAB/local content)

6. Please see Jerry Vonau’s 2021-07-21 summary of 7 networking topology variables, that you can set in: /etc/iiab/local_vars.yml

To (re)configure networking after IIAB is installed, run:

sudo iiab-network

Or if necessary:

cd /opt/iiab/iiab
sudo ./runrole --reinstall network

Please also read “Any other networking tips?” within FAQ.IIAB.IO

DOC REFINEMENT IDEAS: (JV/AH 2022-10-24 DRAFT)

• Simplify high-level explanations
  • Scope & audience
  • Paint the landscape, as simply as possible
  • Outline NetworkManager, systemd, netplan configuration tips from IIAB-Platforms.html — which other key concepts ?
  • Mention past/future trends on Raspberry Pi & mainline OS’s
  • Can I opt out of networking? (What does this mean? Answer:) Attempts to install outside the usual basic network layout, where one would have to resort to comment out the network role or #3004
• Define bridge / br0 (virtual device, once known as a “master” device)
  • Explain how it helps
  • Placekeeper for fixed IP address: example? Answer: To provide a constant virtual interface to attach dnsmasq’s dhcp server that requires a static ip address to function correctly without knowing the all of the possible hardware interface names that once were known as “slaves” (eg wlan0, bnet0 eth1, enx0c37961e7ce1) that could become part of the LAN segment of the network layout to allow other machines which connect to the LAN to function as dhcp clients for ip/routing/dns purposes.
  • How do I add another device(s) to the bridge? (e.g. an Ethernet device or Wi-Fi device, once known as “slave” devices)
• Refine AP+STA mode (dual Wi-Fi) explanations
• Explanatory notes from other tickets
  • Link to and/or incorporate key insights
  • e.g. important links from #3264 ETC
  • For the “Common Customizations” section especially?
• Contextualize or mention associated mini-docs like:
  • https://github.com/iiab/iiab/tree/master/roles/network#readme
  • FAQ.IIAB.IO -> 18 How do I provide Wi-Fi (wireless) to all my kids?
  • FAQ.IIAB.IO -> 19 Can I create a Wi-Fi hotspot using an old laptop?
  • FAQ.IIAB.IO -> 20 How do I change the wireless network name?
  • FAQ.IIAB.IO -> 21 Can I name my server something other than http://BOX.LAN ?
  • FAQ.IIAB.IO -> 22 How do I set a static IP address?
  • FAQ.IIAB.IO -> 23 Any other networking tips?
• Delineate advanced (lesser supported) networking options
  • Make 100% clear these are AT YOUR OWN RISK
  • Provide tips to lead people in the right direction
• Delineate UNSUPPORTED options!