Internet-in-a-Box (IIAB) uses Ansible playbooks to install IIAB software and any IIAB apps you choose. A sequence of operations and a set of conventions define variables of differing scope[*] to organize your IIAB installation(s).

[*] Though most IIAB/Ansible variables are global variables, as a practical matter.

When Ansible starts it gathers a long list of 'facts' about the host on which installation will take place. It also permits a local_facts script to gather any additional facts, helpful to installing IIAB and IIAB apps.

Ansible explores hardware and OS, setting a large number of variables with prefix ansible_ (aside: Ansible's special, magic and connection variables are similar).

Two var files are most important:

• /opt/iiab/iiab/vars/default_vars.yml holds default values for a large number of global IIAB variables, that help with installation.
• /etc/iiab/local_vars.yml allows IIAB implementers to override default_vars.yml, and set any other vars that might be necessary.

Several suggested local_vars.yml files are available to choose from, to help you get oriented. IIAB's 1-line installer will even help you copy one of these to /etc/iiab/local_vars.yml whereupon you're invited to customize and edit .

Changes should NOT be made to default_vars.yml (changes will be overwritten during any subsequent pull from the Git repository).

After Ansible has gathered its facts and loaded the variables files, it starts running roles in the order given in the top-level playbook.

For IIAB the first role is 0-init. It runs /etc/ansible/facts.d/local_facts.fact [*] to establish about a dozen variables that will be broadly useful, when installing or configuring IIAB and any needed IIAB apps.

[*] Copied from /opt/iiab/iiab/scripts/local_facts.fact to /etc/ansible/facts.d/ by iiab-install.

Each Ansible role can declare variables within its defaults/main.yml. These variables have the lowest level of precedence — essentially only taking effect when no value was set anywhere else.

Our convention is to define variables in this file to softcode parameters and to make sure the variable will not be undefined if used elsewhere. These may be thought of as role-specific constants (and are particular useful during software development and QA!)

Almost every role has 2 global variables <role name>_install and <role name>_enabled, that specify whether the role should be installed / enabled (or disabled!)

NOTE: IIAB does NOT currently support uninstalling of roles a.k.a. apps or services.

NOTE: If an IIAB app has been successfully installed, that will be recorded within /etc/iiab/iiab_state.yml — do NOT manually edit that file!

Hostname and Domain variables default to:

• iiab_hostname: box
• iiab_domain: lan

Hostname defaults to box but in the past was schoolserver because that's what OLPC XO laptops expected.

You can change these variables in /etc/iiab/local_vars.yml (preferably prior to installing IIAB) and also after IIAB is installed, e.g. using IIAB's Admin Console.

Here are the main IIAB playbooks in /opt/iiab/iiab:

• iiab-stages.yml - run by ./iiab-install (the only one that front-loads roles/0-init/defaults/main.yml, as of July 2022!)
• run-one-role.yml - run by ./runrole to manually run any role, or any one stage (0-to-9)
• iiab-network.yml - run by ./iiab-network runs roles/network
• iiab-from-console.yml - run by Admin Console’s “Install Configured Options” using config_vars.yml [No longer used as of July 2022?]
• [Admin Console might generate others on-the-fly, then throw them away]

Customize this file so that iiab-install (and others) correctly install IIAB and install/enable/disable your chosen IIAB apps:

• local_vars.yml

Please do NOT touch other files in /etc/iiab but feel free to take a look — here are a few examples:

• iiab.env - essential variables during installation; holds STAGE (counter) for iiab-install's 9 steps in iiab-stages.yml
• iiab.env.py, iiab.env.pyc - Python code/class to read iiab.env (basically exports WWWROOT == /library/www/html for iiab-refresh-wiki-docs, iiab-make-kiwix-lib)
• iiab.ini - tracks what’s been installed, in sequence, with dates (this state is recorded by iiab-install and runrole)
• config_vars.yml - null file must be “{}”, further populated by Admin Console’s “Save Configuration” button. Used by iiab.yml & iiab-from-console.yml with vars/default_vars.yml & /etc/iiab/local_vars.yml
• uuid - used by OpenVPN, for future analytics "fieldback", currently not used on RPi Zero W (#271)

• kiwix_catalog.json - downloaded from Kiwix.org when you click “Refresh Kiwix Catalog” in Admin Console

In order of execution:

• Get Ansible facts including local facts
• Load any vars particular to roles
• Load roles/0-init/defaults/main.yml (iiab-stages.yml uses this one, BUT run-one-role.yml and iiab-from-console.yml do not)
• Load default_vars.yml
• Load OS-dependent variables i.e. /opt/iiab/iiab/vars/{{ ansible_local.local_facts.os_ver }}.yml
• Load local_vars.yml
• Load iiab_state.yml (explained above)
• Load config_vars.yml (might still be used by Admin Console's iiab-cmdsrv3.py around line 3672) [obsolete as of July 2022]
• Run computed_vars.yml (part of 0-init) [appears obsolete as of 2019?]

If you want to understand the "22 levels" of variable precedence at a deeper level, please see Ansible's official doc.

• IIAB Architecture
• Technical Contributors Guide