Skip to content

IIAB Installation

Jump to bottom Edit New page
superbaantonio edited this page Feb 8, 2021 · 143 revisions

superba anterdaym anterdaym@gmail# SEE THE NEW
github.com/iiab/iiab/wiki/IIAB-Installation

THANKS! EVERYTHING BELOW IS DEPRECATED.




Installing Internet-in-a-Box (IIAB/XSCE)

Quick Links

Overview

Setting up a working IIAB/XSCE server requires actions grouped into roughly three areas:

  • Install the Software
  • Configure the Server - Enabling Services and Setting Parameters
  • Add Content

Expert Mode

This is for people who already know how to do everything in these instructions and enjoy doing them multiple times by missing the nuances that make this install different from things they have done before. If you are an expert, at least read about PARTITIONING as so many miss this part. Reading about networking will probably come in handy as well.

Install the Software

There are basically two ways to install IIAB/XSCE software:

  1. Do everything from scratch. (Note that IIAB/XSCE install on Raspbian is a combination of #1 and #2)

  2. Take a short cut by getting files from someone else who did everything from scratch or at least some of the steps.

    See our suggestions on how to create short cut image files for yourself or to help others.

The advantage of doing everything from scratch is that you will get exactly what you want and you will get the latest version of the software. The disadvantage is that it is more work.

The advantage of a short cut is that it will usually take less time and effort. The disadvantage is that there may not be files available for every platform and every configuration and the files may be out of date.

Do Everything from Scratch

Here is the complete list of the steps required. Some may already be done.

  1. Assemble your hardware with your chosen amount of RAM, storage, and network devices. See IIAB Platforms for the partitioning scheme and IIAB Networking overview.

    Please note that LVM partitioning will not work. You need to use the Standard partitioning scheme. (See above reference!)

  2. Install the OS (e.g. Debian 8.7+) using a minimal install (check the box to include ssh, but uncheck the boxes for Apache and everything else). Or, install the Raspbian OS (Pixel or Lite non-graphical version) onto a microSD for a Raspberry Pi 3. If installing onto XO laptops, use OLPC's latest OS (based on Fedora 18). See more at IIAB Platforms and in our FAQ. WARNING: OTHER LINUX DISTRIBUTIONS MAY NOT/YET WORK!

  3. Log into the machine locally or via ssh. Escalate to root using "sudo su -" or similar.

  4. Verify your internet connection by typing:

    ping yahoo.com

  5. On Debian (and Raspbian), doing everything from scratch involves a few simple steps:

         apt-get -y update
         apt-get -y dist-upgrade
         apt-get -y clean

         apt-get install -y git
         mkdir -p /opt/schoolserver
         cd /opt/schoolserver
         git clone https://github.com/xsce/xsce --branch release-6.2 --depth 1
         cd /opt/schoolserver/xsce

         # The following command will install the correct version of Ansible
         ./scripts/ansible

         cd /opt/schoolserver/iiab/vars
         wget http://download.iiab.io/6.3/rpi/local_vars.yml
         # Above assumes a virgin RPi system (wget WON'T overwrite existing files)

         # In general please examine local_vars.yml carefully (and modify as nec)
         # before running Ansible (below, which takes ~2.5 hours the first time!)

         # NOTE: you can change many/most settings after install too, using the
         # Admin Console (http://box/admin) as documented at: http://FAQ.IIAB.IO

         ./runansible
         # Try to rerun the above line if it fails!

For Debian, a basic version of the above ~10 commands can be automated as follows:

     apt-get install -y curl
     curl download.iiab.io/6.2/x86/debian-load.txt | sudo bash

On the Raspberry Pi, curl and git are already included within the Raspbian OS, so run:

     curl download.iiab.io/6.2/rpi/load.txt | sudo bash

If you want the very latest (master branch of Internet-in-a-Box) on Raspbian, and are happy to face pre-release issues (helping with testing ideally!) then then give this a shot on a Raspberry Pi 3:

     curl download.iiab.io/6.3/rpi/load-master.txt | sudo bash

Write to bugs @ iiab.io if you find bugs, Thanks!!

Beware "./runansible" takes about 2.5 hours to complete on a RPi3, the 1st time you run it. Subsequent runs (via Admin Console -> Configure -> Install Configured Options) generally take ~25 minutes.

Similarly, if you want to help test CentOS, consider this experimental recipe: http://download.iiab.io/6.2/x86/centos-load.txt

NOTE: After the above "curl " commands, a reboot is generally necessary before IIAB/XSCE becomes fully functional, e.g. to put host name change into effect, etc. In All Cases: browse the above URLs to inspect and learn from the automated steps of the installation process!

Please note that if you need to reinstall and it has been some time since you cloned IIAB/XSCE you should do the following:

     cd /opt/schoolserver/xsce
     git pull

Also recommended: On Debian or Raspbian, download and install the latest security/package revisions by running apt-get update followed by apt-get upgrade (or apt-get dist-upgrade for more complete kernel changes). In the past, rpi-update was required to update RPi firmware. On CentOS, run yum update and on more recent versions of Fedora run dnf upgrade.

Please note that if SELinux was enabled it will be disabled and the server will reboot at the end of the install. In that case the server may get a new IP address, usually one higher than the previous one. The server may also disconnect during the install in which case you will need to reconnect in order to continue.

You can see the log of the last install by typing:

     cat /opt/schoolserver/xsce/xsce-install.log

Proceed to Configure the Server.

Take a Short Cut

There is a growing list of downloadable files that have everything from the steps listed above to a particular configuration and even content.

In general the process of using one of these files is to download it to a separate computer and then write it to storage media for the target machine. What happens next depends on the specific file downloaded.

You will need tools to decompress these files and write them to storage. On Linux and MacOS these tools will already likely be there. On Windows you will need to download them.

Each set of images linked below has its own README file.

Tools

Naturally, while the everything-from-scratch steps are generic and apply to any platform, short cuts are for a specific platform.

Instructions for specific platforms follow. Please also see the README files accompanying each download.

Raspberry Pi 3

Raspberry Pi 2 should also work, but is slower, and lacks internal Wi-Fi.

The most recent images (based on Raspian Pixel Lite, or the full Raspbian Pixel including X Windows and desktop apps) can be downloaded from http://download.iiab.io/6.2/rpi

There is also a README with instructions.

You can also have a look at:

https://www.raspberrypi.org/documentation/installation/installing-images/

Please ignore everything down to WRITING AN IMAGE TO THE SD CARD (we support Raspbian but not NOOBS!)

Mini PC's like Intel NUC and Gigabyte BRIX

Note that most Intel NUCs (Next Unit of Computing) shipping since since 2015, including the 5th and 6th generation Intel NUC's, have a soldered-in Wi-Fi chip limited to 12 clients maximum. Its competitor the Gigabyte BRIX suffers from the same limitation out of the box (factory units arrive with an Intel Wi-Fi module) but thankfully this Wi-Fi module is removable! Specifically, the Gigabyte BRIX's Wi-Fi socket has been tested to accept less-constrained Wi-Fi cards, such as Atheros modules available for less than $10.

Consider a pre-built image that installs via Clonezilla when booted on the target machine, downloadable from http://download.iiab.io/6.2/x86.

The image (ending in .img) should be written to a USB stick using the same software as for Raspberry Pi and OLPC XO laptops.

Note that these images will write two partitions to a USB stick (thumb drive). The first partition contains the Clonezilla tool, which uses the data from the second partition to initialize your hard disk.

Finally, while these images have been developed on the Intel NUC, they may well work on other Intel machines too (do let us know!)

Installation on OLPC XO laptops is not currently supported on release-6.2, due to lack of time to test the following general strategy:

  • Install OLPC OS 13.2.8 or similar onto the XO laptop

  • In My Settings->Power turn off Automatic Power Management

  • Connect all the network interfaces and reboot

  • Install git and Ansible: (for dependencies)

       su -
   git clone https://github.com/ansible/ansible --branch stable-2.2 --recursive
   cd ansible
   python setup.py install

    Note: Ansible version 2.2 is required, but avoid version 2.2.1.0 which has issues. Version 2.2.0.0 is known to work! Verify the version number with:

       ansible --version

  • Clone the IIAB/XSCE git repo and cd into it:

       cd /opt
   mkdir -p schoolserver
   cd schoolserver
   git clone --branch release-6.2 --depth 1 https://github.com/xsce/xsce
   cd xsce

  • Verify all the network interfaces are visible and have the correct interface label:

       ip addr            (similar to legacy command "ifconfig")

  • Optionally, verify that all network interfaces are properly autodetected:

       bash roles/common/library/xsce_facts

  • From the xsce directory, run initial setup. The XO will automatically reboot early in the install and must be restarted ./runansible to complete the install process (increases size of /tmp so installs will complete successfully):

      ./runansible        (try to rerun this if it fails!)

Configure the Server

At this point you should be able to connect to http://box from a browser. In certain cases http://box.lan, http://schoolserver.lan, http://localhost or http://172.18.96.1 may instead be necessary.

To begin configuring the server, connect to its Admin Console at http://box/admin (username: xsce-admin password: g0adm1n -- note the numbers 0, 1). In general, all default/initial passwords are documented at "What are the default passwords?" within: http://schoolserver.org/faq

This permits selection of options, services, languages, etc to permit additional services, and educational resources to be enabled and selected for download.

Please click on the Help link to get detailed information on configuration options.

Server Security

The first time you sign into the Admin Console would be the best time to change the password. Select the Utilities menu option and the first item, change password. Fill in the form and click Change Password.

Configure Menu

Once the password has been set you should start with the Configure menu item. The overall process is:

  1. Select each sub-menu item and enter any desired parameters. Help is available for each screen and parameter.
  2. Click Save Configuration
  3. Click Install Configured Options
  4. Monitor the progress of the Configuration job in Utilities->Display Job Status.
  5. Note that after Display Job Status shows "Success", it may be necessary to reboot, to enable all the selected changes.

This job can take a substantial amount of time depending on the capacity of the platform involved and how much of the software was included in the initial image.

At this point you are ready to proceed to Add Content.

Supported Network Modes

Operator can select one of three modes of operation:

  • Appliance - No firewall, no dhpcd, no DNS, just a contributor to an already existing network.
  • Gateway - Does dhcpd (IP addresses), name lookup (DNS), firewall, local web page cache for faster retrieval the second time, content filtering to reduce porn (DansGuardian), and site "whitelists" if wanted.
  • LAN Controller (Local Area Network) - In this mode, the server configures clients with IP addresses (dhcpd - dynamic host configuration protocol), name resolution (defines "box" and "schoolserver" for all clients, etc).

Based upon selection of the above mode in the Admin Console, the IIAB/XSCE software will attempt to set up network connections. If "Appliance" mode is wanted, the network adapter will be set up. If "Gateway" is selected, and one of the adapters discovers that it is connected to a source of IP addresses, that adapter will be the internet, and the other the Wi-Fi connector. If "LAN Controller" is selected, any adapter found will be act as server to any clients that might ask to connect.

The IIAB/XSCE installation attempts to determine the network topology based on the number and types of connections it discovers. In general, it looks to see if there is a connection to a gateway and whether other wireless or wired connections are present.

Enable Services

Services on the IIAB/XSCE server can be enable by checking a box in the Configure->Enable Services menu item.

Add Content

Since IIAB/XSCE 6.0, many kinds of content (but not all) can be downloaded and installed through your Internet-in-a-Box server's Admin Console (http://box.lan/admin).

WARNING: some of these Content Packs are quite large and you should pay attention to the space available and space required displayed on each screen. Note that space calculations may not reflect multiple types of downloads happening simultaneously.

Add with Admin Console

To begin, log in to the Admin Console (http://box.lan/admin), take the Install Content menu item, and view relevant Help.

ZIM Files

ZIM files (ZIMs) are compressed and indexed (rapidly searchable) Content Packs prepared by http://kiwix.org. They include Wikipedia, Wiktionary, TED Talks, and many other educational/reference materials in multiple languages. Download and install these as follows:

  1. Within Admin Console -> Install Content, hit button Refresh Kiwix Catalog to update your list of available ZIMs with the very latest from Kiwix.org.

  2. Within Install Content, take menu option Get ZIM Files from Kiwix. Before making your selection of ZIM Content Packs, use buttons Select Languages -> More Languages to be sure you're viewing all relevant choices, in many more languages than just {English, Spanish, French, Portuguese, Arabic and Hindi}.

  3. Carefully finalize your selection of ZIM Content Packs, among the many choices. Avoid downloading/installing more than 10 at once!

  4. Hit button Install Selected ZIMs to begin downloading and installing them onto your server. This can take a very long time, during which time your server may appear unresponsive (within the first hour especially) while it's working!

  5. Monitor progress within Admin Console -> Utilities -> Display Job Status. Each ZIM spawns 3 jobs which (1) download, (2) unzip, then (3) move the pieces into position within /library/zims/content and /library/zims/index. In the past, after installing ZIMs, you also needed to run "xsce-make-kiwix-lib; systemctl restart kiwix-serve" — but this is no longer necessary as of IIAB/XSCE 6.2.

WARNING: there are certain situations (particularly if you've removed a ZIM from /library/zims, e.g. to clean house or when a malformed ZIM failed to install its index) where you need to run Admin Console -> Install Content -> Refresh ZIMs Installed List. This will fix the listing within the above "Get ZIM Files from Kiwix" downloader, so it correctly shows which ZIMs you truly have installed (and which others are truly downloadable!)

Khan Academy Lite

KA Lite is the most popular platform to experience Khan Academy videos, and a huge collection of associated exercises. Accounts may be created for students and teachers if you choose to use KA Lite's LMS functionality as well, to track your own progress (or others').

To download the Khan Academy videos of your choosing, in various languages, use KA Lite's downloader available in these places:

Username/password is Admin/changeme upon installation.

KA Lite's English exercises (about 800MB) MUST be downloaded and installed, even if you are not using English videos, particularly starting with KA Lite 0.17.0. Thankfully starting in April 2017, more polished IIAB/XSCE 6.2 install images will include this essential piece out-of-the-box.

Add Content Manually

RACHEL

Download RACHEL modules manually using rsync, to /library/www/html/modules

After a module has been downloaded successfully (rerun rsync if there are connectivity issues) local/offline users can access it with URL:

  http://box/modules/<module-name>

Copy KA Lite Videos

If KA Lite videos have been obtained from another install or on some storage medium they can be copied directly to KA Lite without going through the admin interface.

  1. Copy to /library/ka-lite/content/
  2. Issue the command systemctl restart kalite-serve to restart the server

OpenStreetMap

http://OpenStreetMap.org (OSM) is much like Google Maps, but more democratic — anybody can change it, much like Wikipedia only for maps.

Internet-in-a-Box enables OSM to be viewable, zoomable and searchable while offline.

Currently in 2017, 16 levels of zoom are possible, from level 0 to 15. This is about 110GB total, so you may need to mail order a physical drive from the volunteers at http://unleashkids.org if the levels posted to http://download.iiab.io/content are insufficient.

Either way, the following directories and their contents are needed:

  • /library/knowledge/modules/geonames_index
  • /library/knowledge/modules/openstreetmap

Implementers can reduce OSM's storage needs by eliminating high-zoom levels within directory openstreetmap, where each zoom level is contained within its own subdirectory.

Example 1: newer install images include layers 0 to 8 (140MB) fully working out-of-the-box, even prior to your customizing your own Internet-in-a-Box server.

Example 2: osm12.tar.gz from http://download.iiab.io/content includes layers 0 to 12 (8.2GB) showing many towns/rivers/parks worldwide, not just cities/countries/seas.

As you can see, each increasing zoom level requires exponentially ever larger amounts of storage!

ASIDE: there is a very dedicated group of people coming together to improve the quality, compactness, vividness, searchability (and UX) of OpenStreetMap for the entire developing world in 2017. Please do make contact with holt @ laptop.org if you too can help here.

Local Content

Schools/Clinics often have custom learning materials they want "permanently" shared with everyone on site. Such PDF's, DOC files, videos, images, audio recordings and HTML (etc!) can be copied to /library/www/html/local_content so that users can browse it, with a URL like http://box/usb or http://box.lan/usb

External USB/Drive Content

For spontaneous (ad hoc) access to materials and teacher content (handouts, lessons, etc) these can be placed on a USB stick or drive, within a folder named:

  • usb

...which will appear under URL http://box/usb when teachers' sticks/drives are plugged into the server's USB ports. Warning: some older phones/devices may require you to type in http://box.lan/usb or http://172.18.96.1/usb

For legacy support of the LibraryBox and PirateBox communities, teachers may also place shareable content in folder names {share, Share, Pirateshare/Share} on their USB sticks/drives.

Bonus: after the lesson, teachers should feel free to remove their USB sticks/drives without warning, as the IIAB server should unmount USB sticks/drives automagically.

See "Can teachers display their own content?" within the FAQ (Frequently Asked Questions) for more information.

Add a custom footer

antoniosuperba

Clone this wiki locally