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). You’ll want to get to know the sudo iiab-hotspot-off and sudo iiab-hotspot-on commands in the common customizations section below.

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 as learning about common customizations:

Three Network Modes

IIAB supports three possible network modes:

Know Your Topology (and IP Addresses)

IIAB’s WAN side IP address is normally assigned by whatever DHCP device manages your building’s network (though it’s possible to set a fixed IP address). Of course there is no WAN side (and WAN side IP address) if your IIAB is set up in LAN Controller mode!

IIAB’s LAN side (regardless whether in Gateway or LAN Controller mode) is a bridge (br0) to provide a constant virtual interface for dnsmasq’s DHCP server that requires a static IP address, without knowing network hardware interface names in advance. These hardware interface names were once known as “slaves” (e.g. wlan0, bnet0, eth1, enx0c37961e7ce1) and allow “student” devices (that connect to the LAN side of IIAB) to function as DHCP clients for IP/routing/DNS purposes.

Remember, as some are confused by this, that IIAB’s LAN side always has IP address 10.10.10.10 (also known as box.lan, or simply box). This IP address is not visible on the WAN side — it’s only visible on the LAN side. This IP address is used by all of the bridge’s interfaces (whether wireless or wired) and is often useful when testing browsers (e.g. http://10.10.10.10, http://box.lan, http://box).

How is the Bridge (br0) Created?

IIAB’s LAN side bridge (br0) is created and configured in one of 3 ways:

  1. Until October 2023, Raspberry Pi OS used dhcpcd to create br0. See rpi_debian.yml and related templates.
  2. On many OS’s (with systemd-networkd) systemd creates br0. See sysd-netd-debian.yml and related templates.
  3. On OS’s with NetworkManager (e.g. Raspberry Pi OS Bookworm, released 2023-10-11) br0 is in fact created by systemd. See NM-debian.yml and related templates.

Bluetooth

[ This can be made to work, but is not mainline as of April 2023. ]

NetworkManager

Raspberry Pi OS adopted NetworkManager (technical docs) as its new default (moving away from dhcpcd) on 2023-10-11.

As this is further refined in 2023/2024, please see How is the Bridge (br0) Created?, Netplan and DNS — while reviewing ongoing progress for Raspberry Pi OS at #3657, PR #3658 and PR #3659.

Common Customizations

1. Wi-Fi Country Code

IIAB tries to set the legally-mandated Wi-Fi country code (regulatory domain) automatically, based on your OS settings, if your IIAB has an internal Wi-Fi hotspot.

You can also change the Wi-Fi country code after IIAB’s installed, if necessary. To do this: 1. Set host_country_code: XX in /etc/iiab/local_vars.yml (where XX is your actual country code / regulatory domain). 2. Run sudo iiab-network — FYI if wifi_up_down: True is set (to attempt AP+STA mode, as briefly explained around Line 94 of /etc/iiab/local_vars.yml)) then your IIAB will also attempt to generate a new unique BSSID/MAC address, for internal Wi-Fi interface ap0. The newly synthesized MAC address will always start with “02”. - FYI if wifi_up_down: True, then IIAB always uses ap0 as the name of the downstream Wi-Fi interface (when cloning the hardware Wi-Fi interface name, that’s used to connect to Wi-Fi upstream). - FYI if wifi_up_down: False, then the name of your IIAB’s Wi-Fi interface will typically be wlan0 (or whatever’s established by the OS). 3. WARNING: OS settings may supersede your host_country_code setting in some circumstances — see PR #3537 for more detail.

🍒 GURU TIPS 🍒

2. AP+STA Mode

In addition to IIAB’s learning hotspot, you can simultaneously 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 even if it does work, bandwidth/stability may suffer!

If for example your IIAB is a Raspberry Pi (and wifi_up_down: True was set and enacted, as briefly explained around Line 94 of /etc/iiab/local_vars.yml) 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.

🍒 GURU TIPS 🍒

3. Exclude an Interface from br0

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_device: 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 bridge -d link. Background at: #531

4. Raspberry Pi Wi-Fi Firmware

IIAB provides you WiFi firmware alternatives for most Raspberry Pi’s, which can allow you to expand the number of Wi-Fi client (student) devices. If you change this in /etc/iiab/local_vars.yml after installing IIAB, you also need to run cd /opt/iiab/iiab then sudo ./runrole --reinstall firmware

5. Static IP Address

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

6. Common Network Variables

These 2 lines are important defaults in /etc/iiab/local_vars.yml originating from mid-2017: * ports_externally_visible: 3       (read below 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)

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

7. Other Network Variables

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

8. Can I Opt Out of Networking?

Sometimes when installing IIAB on a VM (Virtual Machine) or VPS (Virtual Private Server), you might prefer to avoid running IIAB’s network role.

One way to do this is to add network_enabled: False to /etc/iiab/local_vars.yml to skip the network configuration step, while still installing all the prerequisites should you later need to run: sudo iiab-network

One can also skip installing these prerequisites entirely, by adding network_install: False to /etc/iiab/local_vars.yml

(Either way, remember that it’s ALWAYS a good idea to customize /etc/iiab/local_vars.yml PRIOR to installing IIAB!)

9. Optionally, Attach a Wi-Fi Access Point or Ethernet Router (LAN Side)

Schools tell us they are very unhappy with the Wi-Fi limit built into many Intel NUC Mini PC’s, that prevents 12+ simultaneous Wi-Fi client [student] devices from connecting. So what options do they have?

Attaching external Wi-Fi Access Points, Routers or Switches using an Ethernet cable is one way to expand this number — e.g. in a community library where a large number of laptops, tablets and/or smartphones are in use. The Access Points, Routers or Switches will become part of the LAN side bridge (br0) of your IIAB.

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), Wi-Fi Router(s) and/or Switches 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.

🍒 GURU TIPS 🍒

10. Netplan

Netplan allows pre-configuring of network interfaces during Ubuntu installation — and every subsequent boot. (Netplan was originally designed for the cloud, was mainlined by Ubuntu 18.04 in 2018, and made authoritative starting with Ubuntu 20.04 in 2020. Netplan should generally work with Linux Mint too.)

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

🍒 GURU TIPS 🍒

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 [was, up until Raspberry Pi OS Bullseye] started by the dhcpcd service [however since Raspberry Pi OS Bookworm was released 2023-10-11, wpa-supplicant appears to instead now be started by NetworkManager] (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.

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

Protocol Port Service
TCP 22 sshd
TCP 80 nginx (was apache2)
TCP 83, 5060, 5160, 5161, 10000-20000 pbx (Asterisk & FreePBX)
UDP 137, 138 samba
TCP 139, 445 samba
TCP 631 cups (printing)
TCP 873 xinetd (xs-rsync, for legacy XOs) [DEPRECATED]
UDP 1194 openvpn outgoing and not in iptables
TCP 1705 openvpn outgoing handle announcements
TCP 1880 nodered
TCP 1883 mosquitto
TCP 3000 kiwix-serve
TCP 3128, 3129 squid
TCP 3130 squid / dansguardian [DEPRECATED]
TCP 4244 internetarchive
TCP 4369, 5222, 5223, 5280, 47893 ejabberd OR ejabberd-xs [DEPRECATED]
UDP 5353 avahi, mDNS, bonjour
UDP 5959-5970 remoteit (outbound traffic)
TCP 8000 jupyterhub
TCP 8006 kalite-serve-fr
TCP 8007 kalite-serve-es
TCP 8008 kalite-serve (English & others)
TCP 8009 kolibri
TCP 8010 calibre-serve (if avoiding idmgr/8080)
TCP 8080 calibre-serve OR idmgr (for legacy XOs)
TCP 1935, 8081 cham video streaming server (nginx,rtmp) [PROPOSED]
TCP 8083 calibre-web
TCP 8089 sugarizer
TCP 8090 apache2 (NGINX proxying to legacy svcs) [DEPRECATED]
TCP 9090 captiveportal
TCP 9091, 51413 transmission (BitTorrent downloader)
TCP 10000-10499, 12080 (main), 12443 azuracast
TCP 27017 (formerly 27018) mongodb (if used by Sugarizer)
UDP 30000 minetest (Minecraft, but open source!)

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, run iptables-save (which is more reliable than looking at /etc/iptables/rules.v4). 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 further above).

And if you really want to get rid of all iptables firewall rules, running iptables -F is the most important of 3 commands.

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