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
  • Know Your Topology (and IP Addresses)
  • How is the Bridge (br0) Created?
  • Bluetooth
• NetworkManager
  
• Common Customizations
     1. Wi-Fi Country Code
     2. AP+STA Mode
     3. Exclude an Interface from br0
     4. Raspberry Pi Wi-Fi Firmware
     5. Static IP Address
     6. Common Network Variables
     7. Other Network Variables
     8. Can I Opt Out of Networking?
     9. Optionally, Attach a Wi-Fi Access Point or Ethernet Router (LAN Side)
     10. Netplan
• DNS
• List of Ports / Services
  • Firewall (iptables)

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 this network. Your IIAB can have a single network interface (we refer to this as the WAN). This is the interface that you used to install IIAB.
• 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) once IIAB is fully installed and internet access in no longer required.
• Gateway - allows for creating a local area network, using dnsmasq, optionally caching content using a web-caching proxy (e.g. Squid). Your IIAB must have two or more network interfaces (WAN side and LAN side).

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:

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.

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

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.

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 🍒

• Run iw reg get to see the detected Wi-Fi country code and its legal frequencies.
• Run regdbdump /usr/lib/crda/regulatory.bin to see the RF (radio frequency) bands associated with each country code (about 1200 lines in total).

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 🍒

• Your IIAB cannot set up the downstream Wi-Fi interface (i.e. ap0, the machine's internal hotspot) until you've associated your IIAB's upstream Wi-Fi interface (e.g. wlan0 or similar) with a WiFi Access Point.
• ap0 must use the same frequency and channel as the upstream Wi-Fi. Run iw dev or iw wlan0 info or iw ap0 info to see that frequency and channel.
• Your IIAB will synthesize a MAC address for network interface ap0 — see also the Wi-Fi Country Code section just above.
• For more detail, see PR #3549, PR #3555 and PR iiab-admin-console#551.

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

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

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

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 (e.g. any recent version of Ubuntu), then see also: PR #1634, PR #2380, PR #3319, #3330, #3385 (comment)

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.)

• Supports systemd-networkd and/or NetworkManager.
• Please see IIAB's /etc/netplan examples within IIAB Platforms > Operating Systems.
  • During every boot (or running of sudo netplan apply), /etc/netplan/*.yaml files take precedence over pre-existing networking files (e.g. specifying what will end up in /run/systemd/network).
  • If you're expanding your IIAB's LAN side via an Ethernet cable with Netplan in the mix, see also: PR #1634, #2379 (comment), PR #2380, PR #3319, #3330, #3385 (comment), PR #3537
    • NOTE: br0 (i.e. IIAB's LAN-side bridge) doesn't get defined in /etc/netplan, but the underlying systemd files are still used (PR #3537).
• You can learn a lot from Ubuntu's Network Configuration doc, by looking over their Netplan examples, and reading their Netplan FAQ.
  • Netplan is officially coming to Ubuntu Desktop 23.10+ — see "The future of Netplan desktop integration" within 2023-07-18's "A declarative approach to Linux networking with Netplan".
  • Ubuntu Desktop 23.10 FYI: "The configuration file /etc/netplan/01-network-manager-all.yaml (which specifies Network Manager as the netplan renderer) has been moved to /lib/netplan/00-network-manager-all.yaml to reflect the fact that it should not be edited."

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.

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

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