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:
IIAB supports three possible network modes:
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).
IIAB’s LAN side bridge (br0) is created and configured in one of 3 ways:
br0. See rpi_debian.yml and related templates.br0. See sysd-netd-debian.yml and related templates.br0 is in fact created by systemd. See NM-debian.yml and related templates.[2022-11-23: JV will help fill this out.]
[2022-11-23: JV will help fill this out.]
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). - CONTEXT: IIAB always uses ap0 as the name of the Wi-Fi interface (when cloning the hardware interface name). Its newly synthesized MAC address will always start with “02”.
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 firmware
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 (and wifi_up_down: True was set and enacted, as briefly explained around Line 92 of /etc/iiab/local_vars.yml) you can try these 3 commands at the Linux command-line:
sudo iiab-hotspot-offsudo 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.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.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
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: wlan0This 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
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
Please see Jerry Vonau’s 2021-07-21 summary of 7 networking topology variables, that you can set in: /etc/iiab/local_vars.yml
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!)
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 🍒
Many Raspberry Pi’s support up to 32 simultaneous Wi-Fi client [student] devices (IIAB provides you WiFi firmware alternatives; if you change this after installing IIAB, you also need to run cd /opt/iiab/iiab then sudo ./runrole firmware).
IIAB intentionally does not support attaching Wi-Fi Access Points or Ethernet Routers to Raspberry Pi OS. The reason is that field implementers prefer hassle-free Internet using ad hoc Ethernet cables (e.g. from the Raspberry Pi IIAB to any nearby/live cablemodem). If you must attach a Wi-Fi device to your Raspberry Pi IIAB using an Ethernet cable, consider installing 64-bit Ubuntu Server instead of Raspberry Pi OS from the beginning, before you install IIAB.
If you’re expanding your IIAB’s LAN side via an Ethernet cable with Netplan in the mix, see also: PR #1634, PR #2380, #3330, #3385 (comment)
Netplan allows networking essentials to be pre-seeded 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.)
/etc/netplan examples within IIAB Platforms > Operating Systems./etc/netplan files takes precedence over all other networking files.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 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.
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!) |
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 databasesIf 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.
Please also read “Any other networking tips?” within FAQ.IIAB.IO