[THIS DOC’S CURRENTLY BEING REWRITTEN IN 2023! SUGGESTIONS APPRECIATED!]

Internet-in-a-Box (IIAB) Architecture

Anatomy 101: Critical Server Internals & Configuration Overview

Installing and configuring Internet-in-a-Box (IIAB) software, apps/services (and finally content) usually involves 3 steps:

1. Choice of OS (operating system) and disk layout, in keeping with IIAB’s partitioning requirements.

2. IIAB takes over after the OS is functioning on the target hardware. This step is usually done at a terminal console or via an ssh connection to the newly installed OS. (If requirements are in place, this step can be as simple as typing cd /opt/iiab/iiab then ./iiab-install).

   There is some automatic configuration built into IIAB, during this text mode phase. There will almost always be a network connection to the internet left over from the first step. If a second Ethernet or Wi-Fi adapter is discovered, “Gateway” mode will be chosen. If not, the mode selected will be “Appliance”. See the IIAB Networking doc which reviews IIAB’s three network modes.

   There is also the option of setting a large array of variables that govern the detailed installation process. In most cases, the supplied defaults will be sufficient. Any changes should be placed in /etc/iiab/local_vars.yml (see details of variable precedence below).

3. The Admin Console is the Graphical User Interface (when you log in to http://box/admin) for making most configuration changes. There is also a HELP menu system in the Admin Console itself, reproduced in full here:

   1. Overview
   2. Control
   3. Configuration
   4. Install Content
   5. Utilities

(In the past, most IIAB Apps/Services were installed during Step 2., to be enabled on demand later as needed, e.g. during Step 3. In more recent years, IIAB Apps/Services tend to be installed and enabled at the very same time, regardless whether during Step 2. of Step 3.)

Ansible Variables

See IIAB Variables for a more detailed explanation. Quick summary:

• /opt/iiab/iiab/vars/default_vars.yml (DO NOT CHANGE THIS)
• /etc/iiab/local_vars.yml (CUSTOMIZE IIAB HERE, TO OVERRIDE THE ABOVE — PREFERABLY DO THIS BEFORE BEGINNING YOUR IIAB INSTALL)

In general, each role has a <role name>_install and a <role name>_enabled variable. (All roles can be found in /opt/iiab/iiab/roles/).

In the past, IIAB installs set most _install variables to True, and most _enabled variables to False. In more recent years, both of a role’s variable are generally set to True at the very same time.

Variable Precedence

In order of execution, here’s the summary: (more detailed version)

1. Ansible explores hardware and OS, setting a large number of variables with prefix ansible_ (aside: Ansible’s special, magic and connection variables are similar).
2. Variable defaults can be set in each role, with the existence of a <role name>/defaults/main.yml file.
3. /opt/iiab/iiab/vars/default_vars.yml gives initial values for IIAB-wide settings, and also many role specific ones. Note: this file may be overwritten by later releases, and should not be modified by the end user.
4. Implementers should place changes in /etc/iiab/local_vars.yml using a text editor such as vi, nano, or emacs. It’s best to make all such changes prior to installing IIAB. Or if that’s not possible, remember to then enact your changes, e.g. by running cd /opt/iiab/iiab then sudo ./runrole <role>
   • Alternatively, the more important IIAB Apps/Services can be installed and enabled using IIAB’s Admin Console (http://box/admin), which will modify the appropriate variables within your /etc/iiab/local_vars.yml. Remember to enact those changes, using Configure > Install Configured Options then monitor/confirm progress within Utilities > Display Job Status (can take many minutes on a Raspberry Pi!)

Documentation

A growing collection of Internet-in-a-Box technical support docs (and eventually videos) are being made available for offline users as well, at http://box/info