IIAB/FAQ

From OLPC
Jump to navigation Jump to search

This IIAB XSCE content does not reflect the opinion of OLPC. These pages were created by members of a volunteer community supporting OLPC and deployments.

How does Internet-in-a-Box (IIAB) help?

Bring the power of a free Digital Library of Alexandria into the hands of any school worldwide! Internet-in-a-Box (IIAB) is also used in medical clinics and libraries, as can be seen in this Dominican Republic video.

Whether costing $50 or $500, an Internet-in-a-Box "knowledge hotspot" brings your classroom/school laptops together, communicating & coordinating learning in ways that deeply empower kids, teachers and community.

Internet-in-a-Box arose from One Laptop Per Child's original school server (2007-2012) and our global grassroots community, together adding quality content and learning apps shared by the best educational systems worldwide. Today this allows everyone to build up their local community's very own 21st century digital library, as this FAQ document now outlines, to help you make that happen!

Please do consider creating your own Internet-in-a-Box [1] [2] by reviewing some live demo examples and looking over our growing collection of HOW-TO videos.

We are proud that IIAB is built by a global network of professional volunteers, inspired by One Laptop per Child's famous laptops and their innovative Sugar Learning Platform — but now with a wider vision of serving all, both in schools and beyond!

See: Where can I see live demos of Internet-in-a-Box?
See: Is a quick installation possible?

Where is Internet-in-a-Box used?

Internet-in-a-Box (IIAB) was originally called the OLPC School Server Community Edition (XSCE) and is in use in more than twenty countries, from smaller communities to large-scale institutional deployments.

Examples include orphanages and schools in Haiti, to schools across southern Mexico, to rural communities and libraries across southwest Ghana, to remote schools in Myanmar/Burma and Cambodia, to villages across India, to a girls science school in Rwanda, to community centers in Kenya, to a youth community in rural Malaysia, to South Africa townships -- as well as broad Central American deployments like Nicaragua, Costa Rica, and the Dominican Republic.

Libraries and rural medical clinics are also avid users of IIAB, in places like Guatemala, the Dominican Republic and this growing list.

Many contributors are also using IIAB for more personal/grassroots and home library purposes too, helping refine our community product for increasingly diverse and larger impacts!

See: Where can I see live demos of Internet-in-a-Box?
See: Is a quick installation possible?

What can I do with E-books and Internet-in-a-Box?

The first step is to add content gems to your Internet-in-a-Box (IIAB).

Learn how to download high-quality free content, like Wikipedia ZIM files.

Or add content from your own USB disk or USB flash drive. Sharing or purchasing a hard-drive packed full of incredible Wikipedia + Maps + Literature + Khan Academy learning resources is also possible. Contact http://unleashkids.org volunteers should this be necessary.

Either way, this opens up entirely new opportunities for semi-connected schools and offline libraries worldwide, unleashing the best of Internet learning without costs or distractions. Medical clinics, museums and progressive prisons are also taking advantage, as well as individual educators and parents taking charge by building their own "Library of Alexandria" community hotspots.

How can kids best take advantage of these crown jewels of learning? After you've added content, you can offer your students direct access to different kind of content, using links like: 

 http://box            Your Internet-in-a-Box Library!
 http://box/usb        Content from USB sticks/drives, that teachers can insert anytime
 http://box:8008       KA Lite (Khan Academy videos & exercises, with its own content downloader)
 http://box:8080       Calibre E-Book Library: see FAQ, calibredb manual, calibre-server manual (see Calibre-Web below)
 http://box/maps       OpenStreetMap: for box/modules/en-osm-omt-min or box/modules/en-worldmap/map.html or box/iiab/static/map.html
 http://box/docs       FUTURE synonym for http://box/nextcloud ?
 http://box/wiki       DokuWiki: collaborate on documents
 http://box/elgg       Elgg social network for e-learning
 http://box/info       IT support docs & eventually vids, offlined for all
 http://box/kiwix      Kiwix: amazing content & videos, contained in searchable ZIM files
                         WARNING: use http://box:3000/kiwix/ to avoid the Apache proxy e.g. for enhanced privacy #852
 http://box/books      Calibre-Web E-Book Library, an alternative to Calibre (above) with a modern interface: #816
 http://box/moodle     Moodle 3.5.x LTS (learning management system)
 http://box/lokole     Lokole is an Email service that works offline for rural communities, students and teachers.
 http://box/kolibri    Kolibri is like KA Lite; will allow educators to customize+remix Content Packs; also works: http://box:8009
 http://box/nodered    Node-RED visual programming for electronics projects (IoT)
 http://box/wordpress  WordPress 5.0 (blogging & community publishing)
 http://box/mediawiki  MediaWiki 1.31.x LTS (Wikipedia's own wiki software for document collaboration)
 http://box/nextcloud  Nextcloud 15 (students can store their files/photos on Internet-in-a-Box, like Dropbox and Google Drive)
 http://box/runestone  Runestone Interactive Textbooks (proposed, example)
 http://box/sugarizer  Sugar Learning Platform originally from One Laptop Per Child

Common network ports are listed in our high-level networking summary. Internet-in-a-Box administrators can also benefit from these web tools: 

 http://box:9091                Transmission BitTorrent downloader, for KA Lite content provisioning etc
 http://box/admin               Admin Console to install content & configure IIAB. Also try http://box.lan/admin and http://172.18.96.1/admin
 http://box/munin               Network/Infra monitoring
 http://box/awstats/awstats.pl  Usage statistics

We could use help making several of these URL's more bulletproof across different networking environments! Please get in touch if you have Apache or NGINX expertise and can help here: #923

See: Can teachers display their own content?<br See: Is a quick installation possible?
See: What services (IIAB apps) are suggested during installation?
See: Where can I see live demos of Internet-in-a-Box?
See: How do I customize my Internet-in-a-Box home page?
See: What are the default passwords?
See: How do I add ZIM files, like Wikipedia?

Can teachers display their own content?

Yes, teachers can spontaneously insert (and remove!) their own USB memory sticks and USB drives anytime. Somewhat like an informal projector, the teacher's content appears for students almost instantly at: 

http://box/usb

Instructions:

  1. We recommend teachers use USB memory sticks/drives formatted with the FAT32 filesystem. Linux filesystems like ext4 can also work. Automount support for newer/larger exFAT-formatted sticks and NTFS-formatted portable disks was added in February 2018.
  2. Teachers insert their USB sticks/drives into any of the Internet-in-a-Box's USB ports, Done!
  3. This Teacher Content is available (live) to students within seconds. WARNING: Some browsers and non-standard phones/devices cannot access http://box/usb, and so require that students type in http://box.lan/usb or http://172.18.96.1/usb

Warnings:

  1. USB memory sticks/drives may need to be removed and re-inserted into your Internet-in-a-Box before Teacher Content appears e.g. if stick was inserted just prior to a cold boot: #329
  2. Traditionally, the teacher needed to create a folder called "usb" on their USB memory stick, placing audio/video materials, handouts, challenges or presentation(s) inside that folder. However this "usb" folder is No Longer Required as of May 2018 / IIAB 6.5 (by default!) If however you prefer the old approach, edit your /etc/iiab/local_vars.yml so that it contains iiab_usb_lib_show_all: False and then run cd /opt/iiab/iiab; sudo ./runrole usb-lib

CLARIFICATION: it's OK to insert multiple USB sticks/drives at the same time. If so, content from each USB stick/drive is visible within http://box/usb, e.g. in sub-folders that will be obvious, like the following: 

http://box/USB0
http://box/USB1

Or possibly: 

http://box/usb/USB0
http://box/usb/USB1

See the Install Doc. Finally, if you have a screen attached to your server, and occasionally see an error as follows, it is safe to ignore: 

Unable to mount 2.0 GB Volume
Device /dev/sdb1 us already mounted at '/media/usb0'.

See: What can I do with E-books and Internet-in-a-Box?
See: How do I customize my Internet-in-a-Box home page?
See: How do I add ZIM files, like Wikipedia?
See: KA Lite Administration: What tips & tricks exist?
See: WordPress & Moodle Administration: What tips & tricks exist?
See: Can I permanently attach an external USB drive, to add more content?

Can I buy my own Internet-in-a-Box?

You can order a basic medical version of Internet-in-a-Box from the Wiki Project Med Foundation who will ship from Canada to almost any location worldwide, if you help provide feedback to improve the product for all.

A South Asia edition is also available in India.

See: Is a quick installation possible?
See: Where can I see live demos of Internet-in-a-Box?
See: How do I back up, shrink & copy IIAB microSD cards?
See: How can I donate to Internet-in-a-Box?

What hardware should I use?

Internet-in-a-Box (IIAB) is free and open source software that runs on many GNU/Linux platforms:

  • Raspberry Pi 3 or 3 B+ ($35 + parts) and the Raspberry Pi Zero W ($3.14-to-$10 + parts): It continues to astonish us how powerful these tiny "RPi" computers really are, able to serve 32 students simultaneously, with their powerful built-in Wi-Fi. We strongly recommend the RPi 3 B+, for DIY implementers building their 1st digital library to serve a classroom. For smaller kiosk scenarios serving just a few people (Internet-in-a-Box is used in rural medical clinics and similar) definitely consider the RPi Zero W, preparing its IIAB microSD in advance using an RPi 3 or RPi 3 B+.
  • Refurbished "Windows" Laptops: Quality donated laptops can sometimes work extremely well to install Internet-in-a-Box, becoming a "Knowledge Hotspot" or server for an entire developing world classroom or small school. If the laptop's internal Wi-Fi works as an access point, this allows for a hassle-free self-contained unit, as is greatly preferred by most developing world schools (to control operational costs, spaghetti wiring, theft of router, etc). Conversely if the laptop's internal Wi-Fi cannot be used as an access point, an external Wi-Fi router can be made to work if truly necessary. In any case, make sure the laptop has a reasonably new battery, acting as a de facto UPS (critically important in developing world schools where electricity comes and goes). Naturally: laptops with large hard disks and multiple GB of memory are preferred — definitely check that the laptop runs Linux well, preferably with a BIOS that permits it to run while the screen is closed.
  • Intel NUC: Avoid classic/desktop PCs whenever possible, as they consume far too much electricity. However: tough, well-rounded, low-power Mini PCs (such as the Intel NUC) world extremely well, and have proven very effective as school servers in the developing world since 2014. We typically insist on NUC models that accept SATA (2.5 inch hard drives, HDD or SSD) and work with DC voltages up to 19V. WARNINGS:
    • The internal Wi-Fi in most Intel NUC computers is regrettably blocked from connecting to more than 12 Wi-Fi client devices. Compare this to the Raspberry Pi 3, 3 B+ and Zero W — whose internal Wi-Fi supports 32 simultaneous Wi-Fi client devices!
    • Low-end NUC models only work right near 12V, and so are not reliable using lead-acid batteries that you find in most solar installations. Read the spec carefully, for the exact model you're considering!
    • Finally: the NUC is not a fan-less device, but nevertheless has proved very reliable across diverse climates.
  • Other Mini PC competitors: MSI units have proven very solid, and Zotac perhaps less so. Definitely consider Gigabyte BRIX (e.g. GB-BSI3H-6100) which is almost an exact clone of the NUC. As a bonus, the BRIX allows internal Wi-Fi to scale beyond the Intel NUC's annoying limitation of 12 connections maximum. To make this happen, insert an appropriate Atheros Wi-Fi module (typically < $10) into the BRIX. George Hunt can answer questions around which Atheros Wi-Fi modules have been tested to work, as of February 2017. Recap: scaling up internal Wi-Fi is sadly not possible with Intel NUCs since 2015 (5th generation NUCs and onwards) as Intel's Wi-Fi module is unfortunately soldered in.
  • ARM Mini PCs: CPUs like TrimSlice / Utilite and Cubox by SolidRun might one day catch up, providing much-needed community momentum and packaging. To date however we have been disappointed with their firmware, and the availability of Linux kernels/drivers working with internal SATA / internal Wi-Fi (e.g. AP mode), to truly make teachers' lives easier. But check back as many more global deployments' experiences accumulate, and rugged low-end hardware increasingly emerges, on OrangePi or similar?
  • One Laptop Per Child: We do NOT recommend the original XO-1 laptop as a server (256MB RAM is insufficient). However several have successfully deployed the very rugged XO-1.5, XO-1.75 (ARM) and XO-4 (ARM) as school servers in Haiti and Malaysia etc. Thanks to George Hunt's amazing work here over the years.

MEMORY: Some do fine with 512MB RAM (even in 2018!) serving static content from the RPi Zero W. Others do just fine serving dozens of simultaneous video streams from an RPi3 (or 3 B+) with 1GB RAM. Finally, certain others require 8GB or more within a Mini PC, when server-side loads become intensive. For example if you are running an LMS, experiencing a lot of OpenStreetMap traffic, or when fileserver-like capabilities are mandated for all students.

STORAGE: While there's increasing movement from hard disks to SSDs and MicroSDs every year, many others still swear by tried-and-true hard drives. Certainly rotating media are the clear winner when large-capacities are needed at a low price. In the end all storage technologies can fail, each in there own ways. So it's far more more important to start with the actual community's learning goals, engaging educators around their authentic content/interaction needs — and then narrow in on storage capacity/technologies later. Alternative: consider this earlier discussion of external USB hard disks and their possible risks.

HEAT/DIRT/DUST: Ensure your server is positioned with ample room around it for ventilation, away from direct sunlight. Dirt/dust will collect inside it almost regardless, and should certainly be removed from time to time.

Thank you for asking further hardware questions at http://lists.laptop.org/listinfo/server-devel !

See: What OS should I use?
See: Is a quick installation possible?
See: Can I create a Wi-Fi hotspot using an old laptop?

What OS should I use?

Our latest OS (Linux distribution) recommendations should always be posted within the IIAB Platforms document. Generally Raspbian on Raspberry Pi 3 (or 3 B+) is best for people getting their feet wet in 2019, regardless whether they prefer the full/graphical Raspbian with Desktop (includes many amazing desktop apps for learning, with the LXDE-pi desktop/windowing system) or Raspbian Lite (does not include a graphical desktop environment) for a more classic/headless server. WARNING: NOOBS IS NOT SUPPORTED, as its partitioning is very different!

In recent years, Security/Maintenance/TCO concerns have caused deployments to step back from the (bleeding) edge, preferring LTS(*) multi-year support updates that accompany stable OS's like Debian 9 "Stretch" (security updates until June 2022), Ubuntu 18.04 LTS (security updates until April 2023), or CentOS 7 (security updates until June 30, 2024).

(*) Many schools/libraries/clinics now believe LTS is necessary to avoid the rapid annual turnover of Fedora (inherited from OLPC in 2012, during the transition from XS to XSCE). Whereas in the past, deployments often preferred the cutting-edge features provided by a recent version of the Fedora OS, similar to OLPC OS 13.2.10.

Others like Reno McKenzie & Josh Dennis were experimenting successfully (some tweaks required!) with IIAB on the lean & mean http://DietPi.com in February/March 2017. Similarly Ubermix 4.1 was successfully tested in early 2019.

Finally, if there are situations where porting to a new OS/distro will tangibly help schools/libraries/clinics across an entire region, don't hesitate to reach out (on our server-devel mailing list, or contact holt @ laptop.org) as you assess the scope-of-work to complete such a job.

See: What hardware should I use?
See: Is a quick installation possible?
See: What are the best places for community support?

Is a quick installation possible?

If you're Ok with an Internet-in-a-Box that might be older, you can download a microSD card image for Raspberry Pi here.

Otherwise we recommend the very latest, first verifying that your hardware and Linux OS are appropriate:

  • If you're using a Raspberry Pi 3 or 3 B+, install the official Raspbian OS (do NOT use NOOBS!)
  • If you're using a PC or VM, install a minimal OS like Ubuntu 18.04 or Debian 9.

Then run the 1-line installer for Internet-in-a-Box (IIAB) 7.0 pre-releases, by typing in: 

  curl d.iiab.io/install.txt | sudo bash

This takes about 1, 2 or 3 hours to complete on Raspberry Pi — depending whether you choose MIN-sized (~6 server apps), MEDIUM-sized (~12 server apps) or BIG-sized (~20 server apps) as the installer begins. Use our comparison table below, to decide which is most suitable for your needs.

An Ethernet cable (connected to fast, live Internet) is strongly recommended during installation, as well as a modern microSD card (with fast write speeds), and a well-ventilated Raspberry Pi! We encourage you to watch the "ZERO to IIAB" installation video on our YouTube channel.

Other Linux OS's might be possible, but can require extensive babysitting to get right. Follow the "Do Everything from Scratch" instructions. When booting your PC, traditional MBR is preferred, but UEFI can also work (as set in your PC/server's BIOS) if your Linux distribution supports that.

Beware that partitioning is critical particularly with distros like CentOS that attempt to allocate all extra/surplus space to /home by default (this won't work, as gigabytes of content need to be placed in /library instead!) Avoid enabling LVM partitioning, especially if you'll later be needing Clonezilla to duplicate the disk.

Remember: you might need to run sudo iiab repeatedly to complete IIAB's software install, e.g. if your install or connectivity are interrupted for any reason before IIAB auto-reboots at the end, typically an hour or two later. (That final reboot indicates that IIAB's software installation is complete, such that you can begin installing content!)

If you get completely stuck, capture a screenshot (take a photo if copying & pasting is not possible) then get in touch so volunteers can help you work it out.

Once the IIAB software is installed, it's time to add content to your Internet-in-a-Box (IIAB) server, as outlined below, tailoring it to your community/library or clinic's precise needs!

See: Can I buy my own Internet-in-a-Box?
See: What hardware should I use?
See: What OS should I use?
See: What technical documentation exists?
See: What are the default passwords?
See: How do I customize my Internet-in-a-Box home page?
See: Can I create a Wi-Fi hotspot using an old laptop?
See: How do I back up, shrink & copy IIAB microSD cards?
See: What are the best places for community support?

What services (IIAB apps) are suggested during installation?

When installing Internet-in-a-Box (IIAB) using http://d.iiab.io/install.txt, you're given a choice of MIN-sized, MEDIUM-sized or BIG-sized — to get you started fast!

Which services (IIAB apps) are included in each of these 3? This summary table helps you choose among these ~30 educational apps, including several famous LMS's (Learning Management Systems).

Then, after choosing among these 3 sizes, IIAB's installer encourages you to further refine your choice (of IIAB apps, optionally if you so choose) by customizing your very own /etc/iiab/local_vars.yml

MIN MED BIG IIAB APP URL DOCS DESCRIPTION
X X X box/awstats/awstats.pl AWStats AWStats is an open source Web analytics reporting tool, suitable for analyzing data from Internet services such as web, streaming media, mail, and FTP servers. AWStats parses and analyzes server log files, producing HTML reports.
X X X box:8008 KA Lite Offline version of Khan Academy including thousands of videos and quizzes. Very popular in high schools. Supports English, Spanish, Portuguese, French, Hindi, Swahili. Kolibri (below) might replace KA Lite in future.
X X X box/kiwix Kiwix Kiwix is a free and open-source offline web engine created by Emmanuel Engelhart and Renaud Gaudin in 2007.
X X X box/munin Munin Munin graphs help monitor infra like CPU, disk and especially networking. Munin can help analyze resource trends and "what just happened to kill our performance?" problems.
X X X box/maps OpenStreetMap OpenStreetMap is like Google Maps but better, for schools especially, as it works offline and avoids all the advertising. Download detailed "vector maps" for an entire continent, or the entire world! Also: ask us about satellite imagery expected later in 2019.
X X X box/usb usb-lib Content from USB sticks/drives, that teachers can insert anytime.
X X X (none) vnStat vnStat command is a console-based network traffic monitor. It keeps a log of hourly, daily and monthly network traffic for the selected interface but is not a packet sniffer.
I I I (none) OpenVPN OpenVPN allows for remote administration (e.g. using ssh) of your Internet-in-a-Box server (IIAB) and remote diagnostics with the IIAB development community / team — installed (I) but not enabled.
X X box/books Calibre-Web Calibre-Web is a web app providing a clean interface for browsing, reading and downloading E-books using an existing Calibre database.
X X (none) Captive Portal Captive Portal attempts to help people who get frustrated typing in http://box.lan onto their phone, tablet or laptop — attempting to open their browser for them, to display Internet-in-a-Box automatically. #1182
X X box/elgg Elgg Elgg is a social networking engine used by offline schools to create a collaborative environment. Includes basic blogging, microblogging, file sharing, networking and groups.
X X box/nextcloud Nextcloud Nextcloud puts your data at your fingertips, under your control. Store your documents, calendar, contacts and photos on your local server.
X X box/sugarizer Sugarizer A taste of Sugar on any device, used every day by children around the world connected with the One Laptop per Child project.
X X box:9091 Transmission Transmission is a BitTorrent client (software) that helps you auto-download KA Lite (Khan Academy) videos and similar.
X X box/wordpress WordPress WordPress is most associated with blogging (personal journaling) but supports other types of web content including more traditional mailing lists and forums, media galleries, and diverse plugins.
X box:631 CUPS CUPS is a modular printing system for Unix-like computer operating systems which allows a computer to act as a print server.
X box/wiki DokuWiki DokuWiki is a wiki application licensed under GPLv2 and written in the PHP programming language. It works on plain text files and thus does not need a database.
X box/gitea Gitea Gitea is a lightweight self-hosted Git service similar to GitHub.com, and written in Go.
X box:4244 or box/archive Internet Archive The Internet Archive is famous for their Wayback Machine that keeps a copy of 362+ Billion web pages. Their Decentralized Web allows you to create an offline digital library as part of your IIAB, arising from https://dweb.archive.org
X box/kolibri Kolibri Kolibri (might replace KA Lite in future!) provides offline access to a wide range of quality, openly licensed educational content. Supports Kolibri Studio so online teachers can quickly remix & redistribute innovative lesson plans.
X box/lokole Lokole Lokole is an Email service that works offline for rural communities, students and teachers.
X box/mediawiki MediaWiki MediaWiki is the software that makes Wikipedia possible. It allows students to create community web pages together, with attached images, and includes excellent international language support.
X (none) Minetest Minetest is a Minecraft-inspired creative/explorational building blocks game. Supports both survival and creative modes along with multiplayer support, dynamic lighting, and an "infinite" map generator. You can customize it with different games/engines and mods.
X box:2812 ? Monit Monit is a process supervision tool. With Monit, system status can be viewed directly from the command line, or via the native HTTP web server.
X box/moodle Moodle Moodle is a learning platform designed to provide educators, administrators and learners with a single robust, secure and integrated system to create personalised learning environments. SLOW INSTALL
X (none) Mosquitto Mosquitto (uses the MQTT protocol) is a pub-sub broker for electronics projects and educational Internet of Things (IoT) experiments. It's designed for TCP/IP with remote locations where a "small code footprint" is required or bandwidth is limited. See also: Node-RED
X box/nodered Node-RED Node-RED enables electronics projects with a flow-based development tool for visual programming, developed originally by IBM for wiring together hardware devices, APIs and online services as part of the Internet of Things (IoT). See also: Mosquitto
I box/phpmyadmin ? phpMyAdmin phpMyAdmin is a free and open source administration tool for MySQL and MariaDB — installed (I) but not enabled in BIG.
I (none) Samba Samba is the standard Windows interoperability suite of programs for Linux and Unix — installed (I) but not enabled in BIG.
box:8080 Calibre Calibre E-Book Library can be a one-stop solution for all your e-book needs. Many prefer to use Calibre-Web (above) which adds a friendlier / more modern design, to the same back-end structure. SLOW INSTALL
(none) ejabberd ejabberd is a free and open source instant messaging server.
pbx.lan/freepbx PBX Full-featured PBX for rural telephony etc, that can integrate with GSM (mobile phone) networks. Based on Asterisk (Voice over IP, SIP telephone numbers) and FreePBX (web-based GUI to administer it). SLOW INSTALL
(none) Squid Squid is a proxy server that can be helpful for caching and bandwidth shaping, but can be challenging to configure.

See: What can I do with E-books and Internet-in-a-Box?
See: Is a quick installation possible?
See: How do I customize my Internet-in-a-Box home page?
See: What is local_vars.yml and how do I customize it?
See: Can I upgrade or reinstall server apps?

What technical documentation exists?

Please look over our growing collection of HOW-TO videos (several available as .mp4 and .WebMD).

Implementers can review our IIAB Installation document, and IIAB's other Reference/Tech Docs.

Living Docs are ever-evolving as technical progress is rapid, so please also search this very document (FAQ.IIAB.IO) and consider monitoring the very latest GitHub code merges as well.

Developers please consider our IIAB Contributors Guide, first published in October 2017.

Offline operators should check our growing collection of Internet-in-a-Box technical support docs (and eventually videos!) being made available at http://box/info.

Some remote operators prefer to download the very latest tech support documentation every few months when their server is briefly online, by running "/usr/bin/iiab-refresh-wiki-docs" which is equivalent to roles/httpd/templates/refresh-wiki-docs.sh (based on the pandoc document converter).

Documentation for Older Versions:

Core IIAB/XSCE 6.2 Docs were migrated to https://github.com/xsce/xsce/wiki for IIAB/XSCE 6.2 in early 2017, and then to https://github.com/iiab/iiab/wiki in June 2017 for IIAB 6.3.

The earlier XSCE 5.1 + Internet-in-a-Box Install Doc for Intel NUC from 2015 can sometimes be very useful for larger hardware implementers.

Also see George Hunt's foundational collection of XSCE (School Server Community Edition) docs from 2012-2015 at http://schoolserver.wordpress.com

Finally, Anish Mangal hopes to formally write up his deployment recommendations / 8-part training materials based on his experiences setting up IIAB/XSCE in Northern India, while http://unleashkids.org with http://kidsoncomputers.org document the human experience around Haiti/Mexico deployments and beyond.

Please suggest improvements to this FAQ where you can, and check back to reread at a later date, Thank You!

See: How can I remotely manage my Internet-in-a-Box?
See: What are the best places for community support?
See: How can I help?

What is Ansible and what version should I use?

Ansible is software that orchestrates the installation of Internet-in-a-Box (IIAB) and its component apps/services.

Read the latest version/installation recommendations near Line 4 of scripts/ansible (Ansible version 2.7.x is recommended as of March 2019, but note this recommendation is upgraded frequently as Ansible evolves!)

You may need to upgrade Ansible, particularly if you're updating an older version of IIAB.

If so, be sure you're online, then follow these Raspbian/Ubuntu/Debian instructions as root or using sudo:

  1. Run "ansible --version" to see what version of Ansible you might already have installed — make sure you don't have an old/troublesome version of Ansible installed!
  2. Remove all prior versions of Ansible using "apt purge ansible" and if necessary "pip uninstall ansible" — depending how Ansible was originally installed, if necessary see #564
  3. Remove any and all lines containing "ansible" from /etc/apt/sources.list and the files in /etc/apt/sources.list.d/
  4. Run the above-mentioned script, by typing "cd /opt/iiab/iiab" then "scripts/ansible"
  5. Run "ansible --version" and/or "apt -a list ansible" to verify — sometimes you need to log out and log back in, if Ansible just moved from /usr/local/bin to /usr/bin or vice versa

CLARIF: None of the above should be required if you're doing a fresh install on a clean OS, using the 1-liner IIAB installer from: http://download.iiab.io (which installs Ansible for you!)

PRO TIP: for those wanting to run a single Ansible playbook or role, run ./runrole <ROLE NAME> (prior to Ansible 2.5 arriving in March 2018, this was known as ./runtags).

See: Is a quick installation possible?
See: What technical documentation exists?

My Android device says "Connected, no Internet" and won't browse http://box

The message "Connected, no Internet" is normal.

Just beware Android may block you from using Wi-Fi to access Internet-in-a-Box content (preventing your browser from displaying http://box) unless you follow these instructions:

  1. Connect your Android device to the correct Wi-Fi for Internet-in-a-Box.
  2. Recent versions of Android will generally beep within about 1 minute, announcing "Wi-Fi has no Internet access" and "Tap for options".
  3. Tap for more options (you may first need to use your finger to find this notification, pulling it down from the top of your Android screen).
  4. When it asks "This network has no Internet access. Stay connected?" be sure to tap "Yes" !
  5. If you were unable to tap in time, and http://box is still not working in your browser, try to "Forget network" (within Android's Settings -> Wi-Fi networks) then start over, proceeding from Step 1. above.

See: Captive Portal Administration: What tips & tricks exist?

What are the default passwords?

For KA Lite, Calibre, Calibre-Web, Nextcloud, MediaWiki, Moodle, Elgg, Transmission, etc the administrative user is Admin (don't forget the capital A) and the default/initial password is: changeme — WordPress as well, often uses this same account.

An example is Calibre-Web's "teacher" account (Admin/changeme) which can add/remove and convert E-Books, and also change their metadata, at http://box/books. Whereas Calibre itself (if installed, typically at http://box:8080) uses these 7 "student" accounts, to read or download E-Books: box/box, h/h, ht/ht, m/m, mx/mx, p/p or pe/pe (as of Internet-in-a-Box 7.0). If you have access to the Linux command-line, you can change Calibre's accounts by running: calibre-server --manage-users --userdb /library/calibre/users.sqlite

For IIAB's own Admin Console[*] at http://box/admin, http://box.lan/admin or http://172.18.96.1/admin, the username is iiab-admin and the default/initial password is: g0adm1n (note the numbers 0, 1). GNU/Linux administrators can also use this to login over ssh.

Change iiab-admin's password before connecting your server to the Internet. You can do this within http://box.lan/admin -> Utilities menu — or at the command line, if you type "passwd iiab-admin".

If your OS is Raspbian: also change the password for user "pi" from "raspberry" before connecting to the Internet. At the command line, type "passwd pi". Starting with IIAB/XSCE 6.2's standardized images (as of April 2017) we removed the passwords for user "root" (and where possible for user "pi" too, within headless images), by setting their password fields to * (the asterisk character) within /etc/shadow. This prevents direct ssh access to such accounts.

Still, both users "iiab-admin" and "pi" (if they exist) have root (sudoer) powers. As such, advanced operators generally log in as iiab-admin and then escalate to root using "sudo su -".

[*] While the Admin Console can change iiab-admin's password instantly, it's important to understand that many Admin Console changes (within its Configure menu especially) require you click "Save Configuration" then "Install Configured Options" and then wait for this to complete. Monitor for Status "SUCCEEDED" under Utilities menu -> Display Job Status (takes about 20 min on a Raspberry Pi 3 or 3 B+, depending what changes you've requested!)

Finally, certain install-time passwords are listed in /etc/iiab/local_vars.yml which overrides passwords listed in default_vars.yml. If you change any of these install-time passwords (by modifying local_vars.yml) don't forget to then run Ansible, e.g. using "Install Configured Options" above!

Admin Console: Please note that "systemctl restart iiab-cmdsrv.service" is sometimes necessary when http://box.lan/admin shows red errors upon login.

Warning: KA Lite's Admin password cannot be changed in a browser, so you need to run "kalite manage changepassword Admin" (http://box:8008 can only change KA Lite's user passwords). Help is available if you type "kalite manage help changepassword".

See: What can I do with E-books and Internet-in-a-Box?
See: What technical documentation exists?
See: What is local_vars.yml and how do I customize it?
See: What security tips exist?
See: How can I remotely manage my Internet-in-a-Box?
See: KA Lite Administration: What tips & tricks exist?
See: What are the best places for community support?

Where can I see live demos of Internet-in-a-Box?

Please see these live demo examples as used by medical clinics in 2018, hosted by the Wikimedia Foundation (Wikipedia).

Many more examples from schools in Peru, Mexico, Ghana, Nigeria and other places around the world, will be posted in 2019. Please contact us if you:

  1. Want to see diverse snapshots firsthand, to inform your own Internet-in-a-Box design?
  2. Have community examples that should be showcased right here, to assist others?

See: Can I buy my own Internet-in-a-Box?
See: Is a quick installation possible?
See: How do I customize my Internet-in-a-Box home page?

How do I customize my Internet-in-a-Box home page?

Please watch the videos on Internet-in-a-Box's YouTube channel (several available as .mp4 and .webm) to get moving downloading and arranging content on your Internet-in-a-Box (IIAB).

Your IIAB home page is usually reachable at http://box, http://box.lan or http://172.18.96.1 from any nearby smartphone, tablet or laptop/computer.

You can build a beautiful IIAB home page for your community by following these steps:

  1. Add content to your IIAB, by downloading the Content Packs you need using the Admin Console (http://box/admin or http://box.lan/admin) with default password above:
    1. Click the Install Content tab, then explore Get ZIM Files from Kiwix and Get OER2Go(RACHEL) Modules on the left.
    2. If instead you want to load content from a USB drive, click Manage Content on the left.
    3. Multi-gigabyte Content Packs can take hours to download, unpack & install! Consider limiting yourself to 10-or-fewer Content Packs at a time, to avoid thrashing! Monitor the progress under Utilities tab -> Display Job Status — until all are marked as "SUCCEEDED" in the Status column.
  2. Rearrange / re-order your menu items (the Content Packs and IIAB Apps on your IIAB home page) including those that were added just above:
    1. Easy Way - use the drag-and-drop interface within Admin Console (http://box.lan/admin) -> Content Menus tab -> Edit Content Menus -> Content Item List. You may need the "Load Menu", "Save Menu" and "Select Languages" buttons.
    2. Or Manually - rearrange the order of menu items by editing the menu_items_1 array in /library/www/html/home/menu.json.
  3. If you need to change the description or logo for any particular menu item:
    1. Change its description by editing the menu item's .json and/or .html files within /library/www/html/js-menu/menu-files/menu-defs (e.g. to change the description of Practical Action, edit en-practical_action.json and/or en-practical_action.html).
    2. Change its logo by placing a new logo file in /library/www/html/js-menu/menu-files/images, making sure that logo_url is set to the correct logo filename (in its above-mentioned .json file).
  4. Finally, to showcase your school logo or community colors broadly on your Internet-in-a-Box home page, you can customize /library/www/html/home/index.html and the CSS files in /library/www/html/js-menu/menu-files/css. WARNING: editing the index.html page and css files can easily have unintended consequences. For this type of customization, you should consider using WordPress (summarized just below).

Notice: clearing the browser's cache (e.g. Ctrl-Shift-Delete) is sometimes necessary after making any of the above changes!

If you get completely stuck, capture a screenshot (take a photo if copying & pasting is not possible) then get in touch so volunteers can help you work it out.

How This All Works: Dynamic Menuing was originally introduced by IIAB/XSCE 6.1, to reduce front-end hand-coding of HTML, by auto-adjusting all http://SERVERNAMES:PORTS links on-the-fly (using browser-side Javascript). More advanced usages are also now possible, if you read about Menu Item Definitions and HTML Fragments — taking note of the latest 2019 additions.

Alternatives: Some prefer a completely different front-end for their Internet-in-a-Box home page, e.g. WordPress (with this possible IIAB plugin), or DokuWiki, or even Moodle etc. Several of these can be enabled in your IIAB's Admin Console (http://box/admin or http://box.lan/admin) -> Configure tab -> Server Portal -> Select Server Home Page — where your choices include:

  • /home
  • /wordpress
  • /wiki

If you do this, don't forget to enable "Check to Enable WordPress" or "Check to Enable DokuWiki" at the top of that page — then on the left click "Save Configuration", followed by Install Configured Options — finally monitoring the result (typically takes 15-25min on a Raspberry Pi 3 or 3 B+) under the Utilities tab -> Display Job Status.

See: What can I do with E-books and Internet-in-a-Box?
See: Can teachers display their own content?
See: Is a quick installation possible?
See: What services (IIAB apps) are suggested during installation?
See: What are the default passwords?
See: Where can I see live demos of Internet-in-a-Box?
See: How do I add ZIM files, like Wikipedia?
See: KA Lite Administration: What tips & tricks exist?
See: WordPress & Moodle Administration: What tips & tricks exist?
See: Can I permanently attach an external USB drive, to add more content?
See: How do I back up, shrink & copy IIAB microSD cards?

How do I provide Solar Power to my school, library, clinic or orphanage?

This is a very hard question depending on the growth path of your electrical needs, local supply chains, electricians' norms within the country in question — and of course maintenance, price, theft patterns, etc.

In places like Haiti this typically revolves around a bank of 12-volt deep-cycle batteries like the Trojan T-105. But don't hesitate to get your feet wet researching and designing a right-sized solar nanogrid suitable for your own community.

In 2019, please see this India solar discussion: eka-foundation/home#24

Tips from earlier years can also still be useful:

Thanks for taking solar engineering seriously — engineers especially should subscribe to Richard Smith's "power" discussion list if you can!

How do I provide Wi-Fi (wireless) to all my kids?

If you want a self-contained (single-unit) knowledge hotspot, consider Wi-Fi capability physically inside your server (despite its limited radio power?) If so, run "iw list" to determine if it is capable of Access Point (AP) mode, enabled by hostapd. Of course you may need to run "yum install iw" first, so the iw command is available on your server.

If you want higher-powered Wi-Fi equipment and antenna(e) fully external to the server itself, consider approaches from http://villagetelco.org where possible, detailed below. More experimentally, Anish Mangal has experimented successfully with cantenna(e) in India, between classrooms and schools.

Within classrooms, many deployments use the $20 TP-LINK TL-WR841N as these Wi-Fi Routers have proved generally reliable over the years.

We recommend deployments double the classroom capacity of these WR841 routers (to almost 40 simultaneous connections) by trying Terry Gillett's SECN-XSCE firmware here: (based on OpenWrt, but far simpler) 

 http://download.villagetelco.org/firmware/secn/unstable/tp-link/SECN-4/XSCE/

April 2016's RC3 firmware release is increasingly stable: strongly consider it or more recent. It should be followed shortly by a stable/official release we hope. There is firmware for all recent versions of WR841 hardware (v8, v9, v10 and v11) so be sure to select the correct one.

When flashing a TP-LINK with original factory firmware, install using a firmware file labelled "factory" from the RC1 or RC2 folders. Otherwise, use a firmware file labelled "sysupgrade" to upgrade from one OpenWrt-based version to another.

There is also a wiki page outlining how to use PoE (Power over Ethernet) and how to daisy-chain multiple such routers together: 

 http://wiki.villagetelco.org/Power_over_Ethernet_for_MP02_and_TP-Link_Routers

Most important: take advantage of community support, where volunteers are eager to help on the server-devel@lists.laptop.org and xsce-devel@googlegroups.com mailing lists. There's always tons to learn from the latest Wi-Fi fieldwork success stories.

Also consider IRC channel #schoolserver on http://webchat.freednode.net for live chat, and unleashkids@googlegroups.com, which is a great place to ask educators about various schools' filtering recommendations, across different age groups and cultures, whether your school is online or off!

Finally, don't hesitate to blog or write up your own specific recommendations, no matter how large or small your school. This vital engineering shop-talk upholds more schools, libraries and orphanages than we can count (building our community repertoire of Wi-Fi wisdom, often far from the Internet, creating "knowledge hotspots" in every sense) in turn allowing kids to take advantage of amazing free Digital Libraries like http://internet-in-a-box.org and Pathagar e-books.

See: Can I create a Wi-Fi hotspot using an old laptop?
See: Any other networking tips?

Can I create a Wi-Fi hotspot using an old laptop?

Yes, it is possible to create a Wi-Fi hotspot (using hostapd) on some laptops and netbooks, e.g. those with Qualcomm Atheros chipsets. Older Atheros chipsets have good support in GNU/Linux (https://wiki.debian.org/ath9k).

February 2019 Testing Confirms: IIAB 6.7's hostapd Wi-Fi hotspot works with the Qualcomm Atheros AR9285 PCI-Express Wireless device found in an Acer Aspire One.

See: What hardware should I use?
See: Any other networking tips?

How do I change the wireless network name?

The wireless network name (also known as SSID) is what most people use to connect to Internet-in-a-Box using their Wi-Fi devices.

How to rename it depends on whether your wireless access point is fully-external (such as a wireless router) or rather under direct OS control (e.g. internal, or a tiny USB-connected wireless adapter) :

  • If it's fully-external, change its SSID (wireless name) using the documentation that came with the Wi-Fi router.
  • If it's under direct OS control, then the Internet-in-a-Box (IIAB) is also the wireless access point:
    • Edit this line in /etc/iiab/local_vars.yml :
      host_ssid: "Internet in a Box" (quotation marks are OPTIONAL)
      Then run as root: (or sudo)
      cd /opt/iiab/iiab && ./iiab-network
    • You might also log into your server's Admin Console (http://box/admin or http://box.lan/admin) then change the SSID (wireless name) there, under Configure -> Internal Wi-Fi AP -> Internal Wi-Fi Access Point Name. This setting will not take effect until you click on Configure menu -> Install Configured Options (red button), and wait many minutes for all new settings to take effect (monitor status under Utilities menu -> Display Job Status).
    • WARNING: do not edit /etc/hostapd/hostapd.conf directly, unless you want these custom settings trashed upon updating your Internet-in-a-Box! If you must edit this file despite the danger, consider "systemctl restart hostapd.service" to avoid rebooting.
    • Finally you can run iiab-hotspot-on and iiab-hotspot-off which are found in /usr/bin — these are especially useful after you've used a Raspberry Pi's internal Wi-Fi to download IIAB and content. Earlier: George Hunt's command "xs-hotspot-on <SSID>" likewise turned on the internal hotspot for XO-1.5 laptops. Conversely, "xs-hotspot-off" turned that off.

See: What are the default passwords?
See: Any other networking tips?
See: What is local_vars.yml and how do I customize it?

Can I name my server something other than http://BOX.LAN ?

http://box.lan should work in ~99% of all cases, and http://box should work in ~90% of cases; there is no need to change these.

If however a custom name is desired, this can be implemented within each school/library/clinic by editing /etc/iiab/local_vars.yml — and then run "cd /opt/iiab/iiab" followed by "./iiab-network"

Or: log into Admin Console (http://box/admin or http://box.lan/admin) -> Configure menu -> Network Parameters -> Host Name, if you click "Save Configuration" then "Install Configured Options" (waiting patiently for that to complete under Utilities menu -> Display Job Status; which takes ~25min on a Raspberry Pi 3 or 3 B+!)

Many different names have been used in the past, such as http://schoolserver.lan and http://school.lan -- anything that resolves locally to http://172.18.96.1 should be sufficient with standard networking. For the record, some of these older names are listed within the following links:

https://github.com/iiab/iiab/blob/master/roles/network/templates/named/school.external.zone.db
https://github.com/iiab/iiab/blob/master/roles/network/templates/named/school.internal.zone.db
https://github.com/iiab/iiab/blob/master/roles/network/templates/named/school.local.zone.db

Advanced implementers may want to change these 4 zone files too, all within the very same /var/named-xs directory:

school.internal.zone.16.in-addr.db
school.internal.zone.32.in-addr.db
school.internal.zone.48.in-addr.db
school.internal.zone.in-addr.db

See: What are the default passwords?
See: Any other networking tips?
See: What is local_vars.yml and how do I customize it?

How do I set a static IP Address?

To set a static IP address such as 192.168.1.99, put lines like the following in /etc/iiab/local_vars.yml then run the './iiab-network' command (or './runrole network') in /opt/iiab/iiab : 

 wan_ip: 192.168.1.99
 wan_netmask: 255.255.255.0
 wan_gateway: 192.168.1.1
 wan_nameserver: 192.168.1.1

This should generate settings in /etc/dhcpcd.conf as follows: (if your OS is Raspbian or Debian) 

 interface eth0
 static ip_address=192.168.1.99/24
 static routers=192.168.1.1
 domain_name_servers=192.168.1.1

Or on Ubuntu 18.04, netplan stores these settings in /etc/netplan/01-iiab-config.yaml as follows: 

 network:
   version: 2
   renderer: networkd
   ethernets:
     enp0s3:
       addresses:
       - 192.168.1.99/24
       gateway4: 192.168.1.1
       nameservers:
         addresses: [192.168.1.1]
         search: [lan]

If IIAB is already installed, also consider IIAB's Admin Console (http://box/admin or http://box.lan/admin) -> Configure tab -> Network Parameters -> Check to use a static WAN IP Address instead of DHCP -> (enter your) Static WAN IP Address -> Save Configuration -> Install Configured Options.

See: What are the default passwords?
See: Any other networking tips?
See: What is local_vars.yml and how do I customize it?

Any other networking tips?

Please look over:

  • The network README outlines the 'network' Ansible role (Ansible playbook) that runs towards the end of IIAB's installation, after all other IIAB apps/services have been installed. You should run it ("cd /opt/iiab/iiab" followed by "./iiab-network" or "./runrole network") after all your Ethernet and Wi-Fi network interfaces are plugged in and turned on properly (or unplugged properly!) according the your final deployment topology.

PRO TIP: If you use a USB-to-Ethernet dongle (for upstream Internet, generally) use a permanent marker on the server's correct USB port, so that it's not accidentally moved to another USB port!

Also, do not swap the dongle for another, as each dongle has a fixed/unique MAC address. Worst case if your dongle is lost or broken, you will later (after the new dongle is inserted) need to rerun "./iiab-install --reinstall" (formerly "./runansible") from directory /opt/iiab/iiab when your Internet connection is live.

FYI Wi-Fi as upstream is only available on Ubuntu 18.04 desktop using the GUI configuration applet — whereas systemd doesn't do Wi-Fi out of the box on Ubuntu 18.04 Server, and would need additional steps.

More advanced networking insights follow from the stock instructions for setting up upstream and downsteam routers attached to Intel NUC hardware, just as an example.

NOTE: Some prefer Gigabyte BRIX (a drop-in replacement Mini PC, instead of the Intel NUC) as an Atheros internal Wi-Fi module can be inserted, to scale beyond Intel's soldered-in limit of 12 Wi-Fi connections maximum.

Classrooms within 100 meters of your school server can easily be connected using standard Ethernet wiring, or using Wi-Fi repeaters. Outdoor wiring is possible (preferably fiber optic cables below ground) but check with experts to avoid problems with lightning. Beyond 100 meters, a more deliberate tree and branch solution may be needed.

Please ask questions about your specific school's networking/wiring challenges on mailing list server-devel@lists.laptop.org !

2018 SIMULTANEOUS AP (ACCESS POINT) & WIFI-AS-CLIENT PROPOSALS: https://github.com/georgejhunt/iiab/wiki/Using-WiFi-during-IIAB-Installation-on-the-Pi-3-and-W outlines the basic RPi implementer recipe for George Hunt's Pull Request #697 similar to Jerry Vonau's Pull Request #748.

See: How do I provide Wi-Fi (wireless) to all my kids?
See: Can I create a Wi-Fi hotspot using an old laptop?
See: How do I change the wireless network name?
See: Can I name my server something other than http://BOX.LAN ?
See: How do I set a static IP Address?
See: Captive Portal Administration: What tips & tricks exist?

What is local_vars.yml and how do I customize it?

You can modify variables within /etc/iiab/local_vars.yml for all your Internet-in-a-Box installation(s), to override defaults, if use of the Admin Console (http://box/admin or http://box.lan/admin) is not immediately possible.

Do NOT modify /opt/iiab/iiab/bars/default_vars.yml, as explained in the IIAB Architecture and IIAB Variables docs.

Three example local_vars.yml files are posted for comparison. Also, a couple very practical networking variables are posted at the bottom of the IIAB Networking document.

Implementers should place changes in local_vars.yml using a text editor such as vi, nano, or emacs. Remember to enact all variable changes by running "cd /opt/iiab/iiab" followed by "./iiab-install --reinstall" (formerly "./runansible") — note this can take ~15 min to ~2 hours on a Raspberry Pi 3 or 3 B+.

Or, the essential 1+6 "post-install" roles then "network" role of Ansible's 1+9 overall stages can be run from Admin Console (log in to http://box/admin or http://box.lan/admin) -> Configure menu -> Install Configured Options button. Then monitor the progress (typically ~20 min on Raspberry Pi 3 or 3 B+) within Utilities menu -> Display Job Status. PRO TIP: monitor live progress using "tail -f /tmp/job-<JOB NUMBER>"

PRO TIP: Those who prefer the command-line can consider these options:

  • Use './iiab-install' for regular installs, or to continue an install.
  • Use './iiab-install --reinstall' to force running all Stages 0-9.
  • Use './iiab-install --debug' to run Stage 0, followed by Stages 3-9.
  • Use './runrole <ROLE NAME>' (formerly ./runtags) to run a single Stage or Tag or Role. Run './runrole' to see your options.
  • Use './iiab-network' to run the network role.

PRO TIP: if you've accidentally made changes that prevent "cd /opt/iiab/iiab; git pull" from merging the latest from GitHub's repo cleanly onto your local machine, consider cloning a fresh copy of repo "iiab". To do this, you'd typically run "cd /opt/iiab; mv iiab iiab.old; git clone https://github.com/iiab/iiab". Then if your /etc/iiab/local_vars.yml is correct, you'd typically run "cd /opt/iiab/iiab; ./iiab-install --reinstall".

See: What are the default passwords?
See: What are the best places for community support?

Is a "Rapid Power Off" button possible for low-electricity environments?

Yes. Small medical clinics and electricity-starved remote libraries typically require this, given that Raspberry Pi computers do not have a physical Power Off button, and it's asking way too much for non-technical operators to power off using the Admin Console.

Set "apache_allow_sudo: True" in local_vars.yml and then run "cd /opt/iiab/iiab" then "./iiab-install --reinstall" (formerly "./runansible") which runs for about 20min on a Raspberry Pi 3 (or 3 B+). [This variable was renamed from allow_apache_sudo on 2018-09-23, as part of #1165]

To power off, any user can then click a URL like: http://box/js-menu/menu-files/services/power_off.php (formerly http://box/common/services/power_off.php)

(Whereas most schools do not want this, for obvious reasons — a mischievous student could shut down the Internet-in-a-Box at any time! This is the reason most schools prefer "apache_allow_sudo: False".)

The "Power Off" button can be customized in IIAB's Admin Console (http://box/admin or http://box.lan/admin) -> Content Menus -> Load Menu -> change the settings in "Properties of Current Menu" -> Save Menu. More detail on the Content Menus help page and #1689.

Earlier Known Issue in IIAB 6.3: You also needed to run "cp /opt/iiab/iiab/roles/httpd/files/html/services/power_off.php /library/www/html/common/services" to enable the "Rapid Power Off" button.

See: What is local_vars.yml and how do I customize it?

How do I get Internet-in-a-Box updates every few months or semester?

Great question, keeping in mind the near-impossibility of downloading large Content Packs to remote locations in the developing world. Certainly, Internet-in-a-Box improved its Wikipedia full-text-search in 2014/2015 (which remains compatible with XSCE 0.4, 5.x and IIAB/XSCE 6.x) and some remote upgrades are occasionally possible.

And yet an honest calculation of terabyte download costs and frustrations explains why drop-shipped hard drives' "content catalogs" are more economic and efficient than overweight/monolithic download torrents.

Please watch the HOW-TO videos on Internet-in-a-Box's YouTube channel (several available as .mp4 and .WebMD) to get up to speed with downloading & installing content to your IIAB!

On the high end, IIAB's Admin Console (http://box/admin or http://box.lan/admin -> Install Content) supports piecewise incremental content updates for those schools with extremely high/affordable bandwidth. As of early 2017, note that Content Packs must be manually removed, when space is needed (e.g. after that content is no longer in use). An exception is KA Lite, whose administrative interface (log in as "Admin" to http://box:8008) supports deletion of lessons/videos, as well as downloading new ones.

As a practical matter, remote schools may receive updates via hard drive or USB memory stick every semester or so, flown/driven in by a partner, bringing new maps/encyclopedias/E-books and video lessons.

Keep in touch as new options evolve! Make contact with http://unleashkids.org to keep up with other communities' offline content collections and recommendations.

See: What are the default passwords?
See: How do I add ZIM files, like Wikipedia?
See: Can I permanently attach an external USB drive, to add more content?

How do I know what version of IIAB I'm running?

Look in /etc/iiab/iiab.env for the line(s) that begin with "iiab_base_ver =". This is followed by a number like "7.0" showing the version level (even if you're running a pre-release of that version!) Context: iiab_base_ver is sourced from the top of /etc/iiab/iiab/vars/default_vars.yml during IIAB (re-)installation.

You can also log into your Internet-in-a-Box server's Admin Console (http://box/admin or http://box.lan/admin) and click "About" in the top-right. Look at both fields "Version" and "Commit ID".

The "Version" field should show something more definitive like "release-6.7" — or something else if you're running an earlier pre-release from https://github.com/iiab/iiab/commits (= https://github.com/iiab/iiab/commits/master)

Compare the 40-character string "Commit ID" to the "Latest commit" from those at https://github.com/iiab/iiab/releases (such as https://github.com/iiab/iiab/tree/release-6.7) to reconfirm you have IIAB 6.7 (e.g. it should begin with 60b62d7 if you're running the official IIAB 6.7 from February 21, 2019.

Caution: the letter 'g' was confusingly sometimes added in front of 7-character githash (abbreviated from the full 40-character SHA-1 githash as above) within "install image" filenames, in places like http://download.iiab.io/6.2/rpi/ and http://download.iiab.io/6.2/x86/

See: Is a quick installation possible?
See: What are the default passwords?

Can I upgrade or reinstall server apps?

Yes, at your own risk you can individually delete the following files or directories, to attempt an upgrade or reinstall of these common server apps, which will happen the next time you run "cd /opt/iiab/iiab" then "./iiab-install --reinstall" :

  • /opt/nextcloud/version.php (Nextcloud version stored therein; reinstalls are easiest if you "sudo mysql" then "DROP DATABASE nextcloud;" and delete the entire /opt/nextcloud)
  • /opt/iiab/kiwix/bin/kiwix-serve (Kiwix version corresponds to timestamps shown by "ls -l /opt/iiab/kiwix/bin")
  • /opt/iiab/moodle/config-dist.php (Moodle version stored in /opt/iiab/moodle/version.php — major upgrades may require deleting /opt/iiab/moodle and /library/moodle, dropping the database using "dropdb -U postgres moodle" — and if nec upgrade PostgreSQL below)
  • /library/pgsql-iiab/pg_hba.conf (PostgreSQL version shown by "psql -V" client or "[PATH]/bin/postgres -V" server; major upgrades might require deleting or upgrading data directory /library/pgsql-iiab)
  • /library/ka-lite/database/data.sqlite then "systemctl restart kalite-serve", then you may need to re-register and delete/re-download KA Lite's English "content pack" at http://box:8008/update/languages/ (KA Lite version stored in /library/ka-lite/httpsrv/static/docs/index.html ; major upgrades also require deleting /usr/local/kalite)
  • /library/dokuwiki-<version>/VERSION if reinstall required (DokuWiki version shown by "ls -l /library/dokuwiki")
  • /usr/local/osm (sometimes needed to force a fresh install of OSM / OpenStreetMap)
  • /usr/bin/calibre AND move old .deb's from /opt/iiab/downloads if on RPi (Calibre version shown by "calibre-server --version")
  • /library/calibre-web/metadata.db deletion forces default settings, and restores a minimal metadata.db (1. version is implied by "cd /usr/local/calibre-web; git log" when compared to the githashes shown at https://github.com/janeczku/calibre-web/releases 2. Calibre-Web will let you check from the command-line in future, per #1624 3. Check the admin section of http://box/books, on the bottom: the current version number is listed, as long as you are on the stable update channel, which is the default)
  • [deletion of /library/mediawiki-ACTUAL.VERSION.NUMBER/LocalSettings.php no longer required, BUT database schema changes on almost every upgrade. So: automatic installation of latest (during "./iiab-install --reinstall" or "./runrole mediawiki") generally requires you first drop or update mysql "iiab_mediawiki"; for database/schema upgrades read about update.php in MediaWiki Manual's Upgrading FAQ] (MediaWiki version stored in /etc/apache2/sites-available/mediawiki.conf pointing to /library/mediawiki-ACTUAL.VERSION.NUMBER, as installed per /opt/iiab/iiab/roles/mediawiki/defaults/main.yml; finally feel free to delete older dirs of the form /library/mediawiki-OLD.VERSION.NUMBER after upgrading)
  • [deletion of /library/wordpress no longer required, online-upgrade is automatic/mandatory during "./iiab-install --reinstall"] note that WordPress increasingly upgrades itself, when used online (WordPress version stored in /library/wordpress/wp-includes/version.php; major upgrades may also require you to drop mysql database "iiab_wp")
  • [no file deletion required, online-upgrade is automatic/mandatory during "./iiab-install --reinstall"] (Lokole version shown by "grep ^Version /library/lokole/venv/lib/python3.*/site-packages/opwen_email_client-*/PKG-INFO"; if you need to force a fresh install, first wipe using "rm -rf /library/lokole /etc/apache2/sites-available/lokole.conf /etc/apache2/sites-enabled/lokole.conf")
  • [no file deletion of /opt/elgg-ACTUAL.ELGG.VERSION/index.php required, online-upgrade is automatic/mandatory during "./iiab-install --reinstall"] (Elgg version shown by "ls -l /opt/elgg")
  • [no file deletion required, online-upgrade is automatic/mandatory during "./iiab-install --reinstall"] (Kolibri version shown by "/usr/local/kolibri/bin/kolibri --version")
  • [no file deletion required, online-upgrade or offline-reinstall is automatic/mandatory during "./iiab-install --reinstall"] (phpMyAdmin version shown by "ls -l /opt/phpmyadmin")
  • [no file deletion required, though in the past /library/www/html/sugarizer/index.html had to be moved] (Sugarizer version now shown by "ls -ld /opt/iiab/sugarizer*" or in the past, "ls -l /library/www/html/sugarizer"; major upgrades might require deleting MongoDB's entire /library/dbdata)
  • [no file deletion required, online-upgrade is automatic/mandatory during "./iiab-install --reinstall"] (Gitea version is shown by "ls -l /library/gitea/gitea" and in the bottom-left of http://box/gitea)
  • /usr/libexec/iiab-startup.sh (delete this if you want to upgrade to IIAB's latest e.g. /opt/iiab/iiab/roles/2-common/templates/iiab-startup.sh)

WARNING #1: Data loss of kids', teachers' and users' personal materials is always possible, ALWAYS back up any relevant databases first!

WARNING #2: Beware you will likely lose settings that you've set within Internet-in-a-Box's Admin Console (http://box/admin or http://box.lan/admin).

WARNING #3: Testing is ongoing to make sure this works sufficiently in typical situations like these 2 below, ensuring that a wholesale revert to default settings is at least plausible:

  1. When intermittently online, an operator may want an online upgrade of a server app to the very latest available version.
  2. When completely offline, an operator might want an offline reinstall of a server app using its original zipfile-or-similar installer that resides within /opt/iiab/downloads

See: What services (IIAB apps) are suggested during installation?
See: What are the default passwords?
See: KA Lite Administration: What tips & tricks exist?
See: How do I back up, shrink & copy IIAB microSD cards?

What security tips exist?

Some install images include ssh keys which permit developers to log into your machine, to enable remote support during Beta programs and similar. You can disable this feature by running terminal command "rm -f /root/.ssh/authorized_keys" — whereas in the past this was "rm -r /home/iiab-admin/.ssh/authorized_keys".

Whether running your server online or offline, please see IIAB/Security and help us contribute to this evolving knowledge & repertoire of 21st century hygiene, thanks to professional volunteers from many backgrounds.

See: What are the default passwords?
See: How can I remotely manage my Internet-in-a-Box?
See: Is campuswide access possible for all server apps?
See: What are the best places for community support?

How can I remotely manage my Internet-in-a-Box?

Beginners typically prefer TeamViewer (see paragraphs further below!)

Large-scale implementers should consider rolling their own OpenVPN for all remote administration needs, or using a "freemium" service (free, or pay for more features) like https://ngrok.com or remot3.it (formerly known as Weaved). Dynamic DNS services like No-IP (https://noip.com) are also possible, if you want to roll your own. #318 #1124

Small-scale implementers should consider free services like https://serveo.net and https://ngrok.com to expose your server to the Internet, permitting maintenance via ssh and http. Or ask us about IIAB's own XSCENET, which is a minimal remote management solution (with a much more basic remote console, enabling ssh and http among a trusted group). Contact holt @ laptop.org for details. If you are using XSCENET, the "iiab-remote-on" command is generally equivalent to "systemctl enable openvpn@xscenet; systemctl start openvpn@xscenet" and the "iiab-remote-off" command is generally equivalent to "systemctl disable openvpn@xscenet; systemctl stop openvpn@xscenet". If you do not yet have these commands, you can implement them as aliases within /root/.bashrc

NOTE: Developers' ssh keys traditionally used to come included with install images, to enable remote support during Beta programs and similar. Read "What security tips exist?" if you want instructions to remove these keys.

Beginners and those with a graphical desktop environment (like X Windows) on their Internet-in-a-Box often take advantage of TeamViewer for full visual/remote support. This can be priceless when mentoring/learning at a distance, thanks to TeamViewer's screen-sharing, keyboard-sharing and mouse-sharing, to onboard new operators who are not yet able to navigate GNU/Linux and its command line tools. In a graphical desktop environment, simply install TeamViewer, which by default randomizes TeamViewer's password (needed for remote access) every time TeamViewer is launched, preserving local operator control.

You can also enable TeamViewer's fully "unattended access" by setting a "permanent" password for remote access within: Settings/Extras/Options -> Security -> Password.

Raspberry Pi: If you're using the Raspbian OS on RPi (either the "Lite" server edition, or the "With Desktop" edition including a graphical desktop environment) then you want the minimal "TeamViewer Host" (e.g. https://download.teamviewer.com/download/linux/teamviewer-host_armhf.deb was version 14.2.8352 as of 2019-05-11). It works as a single-click install (or "apt install ./teamviewer-host_armhf.deb", or "dpkg -i teamviewer-host_armhf.deb; apt-get -f install") and is more robust than the 2016 version (unattended access is now far more reliable!) It also now includes seamless ongoing upgrades via apt.

Bonus: headless installation/configuration is also now supported (e.g. on Raspbian Lite) with "teamviewer info" "teamviewer passwd <ACTUAL-PASSWORD>" and "teamviewer help" per https://community.teamviewer.com/t5/Knowledge-Base/How-to-install-TeamViewer-Host-for-Linux/ta-p/6318 In future, it might even be possible to install directly with "apt install teamviewer-host" ?

Here is a way to automate the installation of TeamViewer and a few other basic tools on a fresh OS, prior to installing IIAB 7.0/master, on OS's like Raspbian, Ubuntu or Debian: http://download.iiab.io/7.0/prep+teamviewer.txt

Ubuntu/Debian Warning: If you insist on installing the Calibre E-Book Reader via .debs (instead of the Python way via /opt/iiab/downloads/calibre-installer.py) you'll likely damage your installation of TeamViewer, which as of January 2018 (TeamViewer 13) required Qt 5.5.1 and did not yet support Qt 5.9.1.

Admin Console: Please note that "systemctl restart iiab-cmdsrv.service" is sometimes necessary when http://box.lan/admin shows red errors upon login.

See: What are the default passwords?
See: What security tips exist?
See: What are the best places for community support?

How do I view usage statistics?

To help teachers view which ZIM files are most popular:

  1. Ensure "./iiab-install [--reinstall]" or "./runrole kiwix" was already run (installing IIAB 6.5+ takes care of this) with the following in local_vars.yml
    • kiwix_install: True
    • kiwix_enabled: True
  2. Visit http://box/awstats/awstats.pl to view stats

Noting: [warning some of the instructions below are stale as of 2019]

  • IIAB menuing (links on main page at http://box) can be reverted to the untabulated links (on port 3000) if nec, using https://github.com/iiab/iiab-menu/blob/master/config.json
  • If updating from a much earlier IIAB remove that file (“rm /library/www/html/iiab-menu/config.json”) then update to the latest IIAB menus by running ("cd /opt/iiab/iiab-menu; git pull; ./cp-menus")
  • N.B. there can be an unintended consequence in that the url for Android APKs will be set back to the default if you have overridden it.
  • Underlying code is at: PR #585
  • Please help us improve this community analytics approach if you can: #1268

How do I add ZIM files, like Wikipedia?

Please read "How do I customize my Internet-in-a-Box home page?" and see the HOW-TO videos on Internet-in-a-Box's YouTube channel (several available as .mp4 and .webm) to get up to speed with downloading & installing content to your IIAB!

1. Definitely consider Internet-in-a-Box's Admin Console (http://box/admin or http://box.lan/admin) -> Install Content as an alternative to the command-line!

Likewise if you have content on hand (like ZIM files or OER2Go/RACHEL modules) on a portable USB disk or USB flash drive, insert this USB drive into your Internet-in-a-Box (IIAB) and then use http://box.lan/admin -> Install Content -> Manage Content to copy (install) the content you need, onto your IIAB.

PLEASE NOTE: The USB drive must have the same layout as the server, i.e. zims are in library/zims/content and OER2Go modules are in library/www/html/modules and the usb must be mounted in /media/usb(0-7), which is where usbmount puts them automatically.

Also, the first time a usb is accessed a catalog is created which may take enough time that you see GET-EXTDEV-INFO Failed and reported No response from CMDSRV in 30000 milliseconds". Please simply try again in a minute to let the catalog finish building.

This copying of content is two-way in that you can also copy zims and OER2Go/RACHEL modules to the usb drive in order to take them to another installation.

2. Or...if you really prefer the command-line...download the ZIM file you want (e.g. from http://download.kiwix.org/zim/) to /library/zims/content — for example: 

 cd /library/zims/content/
 sudo wget https://download.kiwix.org/zim/wikipedia/wikipedia_km_all_novid_2019-03.zim

Then run /usr/bin/iiab-make-kiwix-lib to rebuild the Kiwix index: 

 sudo iiab-make-kiwix-lib

Finally, test that your new ZIM file is browsable at http://box/kiwix and that its search features (on the top-right of the page) are working!

LEGACY ZIM FILES CLARIFICATION: Most all ZIM files generated since mid-2018 contain an internal search index. There are a few rare exceptions however. In some cases title search works but full text search is impossible, because no such index was ever built. In yet other cases (some older/legacy ZIM files, typically from http://download.kiwix.org/portable) the ZIM comes with associated index files that must be placed in /library/zim/index — see also: https://github.com/iiab/iiab/blob/master/roles/kiwix/README.rst

See: What can I do with E-books and Internet-in-a-Box?
See: Can teachers display their own content?
See: What are the default passwords?
See: How do I customize my Internet-in-a-Box home page?
See: Can I upgrade or reinstall server apps?
See: Can I permanently attach an external USB drive, to add more content?

KA Lite Administration: What tips & tricks exist?

Khan Academy videos and exercises are extremely popular thanks to KA Lite, which stores these famous videos (.mp4) and thumbnails (.png) within /library/ka-lite/content, and can be customized in different ways. Note this folder also contains 3 critical subfolders, after you've installed KA Lite's mandatory English content pack as part of a new install: (IIAB's 1-line installer does this for you!)

  • assessment (836 MB on a new install)
  • locale (16 KB on a new install)
  • srt (subtitles, 105MB on a new install)

To change KA Lite's Admin and user-level passwords, see "What are the default passwords?" above.

For starters, log into http://box:8008 as the Admin user, and learn how to install language packs and then download/delete videos in different languages.

Instead of the above, many prefer torrenting the compressed KA Lite videos (available in 7 common languages) as their storage footprint is more than 3X smaller!

Traditionally Windows users use BitTorrent client software like Tixati, and Linux users use command-line BitTorrent tools like aria2 (trying --force-sequential or "aria2c -Z URL1.torrent URL2.torrent" to download several). Or, a visual interface to BitTorrent can now be used as part of your Internet-in-a-Box:

A. Internet-in-a-Box can now kickstart the BitTorrent download(s) for you, if you set "transmission_install" and "transmission_enabled" to True in /etc/iiab/local_vars.yml and pick the KA Lite language(s) you need. Install and launch Transmission by running "cd /opt/iiab/iiab" then "./runrole transmission" then "./iiab-network".

B. Monitor your BitTorrent download(s) at http://box:9091 using Admin/changeme until download is confirmed complete (can take hours if not days!)

C. Carefully move all videos/thumbnails from /library/transmission into /library/ka-lite/content (DO NOT OVERWRITE SUBFOLDERS assessment, locale, srt !)

D. Log in to KA Lite at http://box:8008/updates/videos/ using Admin/changeme then click "Scan content folder for videos" (can take many minutes!)

Separately, you can run "/opt/iiab/iiab-factory/content/khan/ka-scan" to remove obsolete videos, which will be moved to /library/ka-videos/obsolete to help you free up space!

More advanced administrators can take a look at the scripts in /opt/iiab/iiab-factory/content/khan and /opt/iiab/iiab-factory/box/generic contributed by Tim Moody.

In general, you can restart the KA Lite service using "systemctl restart kalite-serve" if attempting such changes under the hood. Three common such examples follow:

Mandatory English Pack taking too long to download? Mysteriously, KA Lite's mandatory 1GB (929,916,955 byte) English Pack can take hours to download over certain ISP's and network environments, when installing it using the official command "kalite manage retrievecontentpack download en". Speedier 3-Step Alternative If So: (1) Download en.zip manually (using another ISP if necessary) from http://pantry.learningequality.org/downloads/ka-lite/0.17/content/contentpacks/en.zip using wget or any browser. (2) Install it by running "kalite manage retrievecontentpack local en en.zip" (it's no longer necessary to type in "export KALITE_HOME=/library/ka-lite", as /usr/bin/kalite is now a bash wrapper to "venv" that does that automatically). Brief Help is available if you enter "kalite manage help retrievecontentpack". (3) Run "du -hs /library/ka-lite/content/" to verify that 940MB or more has successfully been installed there (and log in as Admin to http://box:8008 -> Manage -> Language to be 100% sure!)

Multilingual? Consider running 2 or 3 instances of KA Lite on the same Internet-in-a-Box server, e.g. we sometimes put English on port 8008, Spanish on port 8007, and French on port 8006. Examine the mk-other-kalite script if you too want *direct* access to Spanish videos in /library/ka-lite-es, or *direct* access to French videos in /library/ka-lite-fr, etc. Typically implementers run "mk-other-kalite es 8007" or "mk-other-kalite fr 8008" (make sure your mk-other-kalite is up-to-date, including Tim Moody's patch for venv from May 2018!)

If you do this, make sure your IIAB's firewall (iptables) has the ports open that you need for "campus-wide" (WAN side) access to these materials. Make any changes you need to the ports_externally_visible: variable in /etc/iiab/local_vars.yml and consider these 2 older examples: open ports below 8008, open up port 4244.

Monolingual in Spanish or French or similar? Fool /opt/iiab/iiab-menu/config.json (live at /library/www/html/iiab-menu/config.json) by changing the line with "es-kalitePort" from 8007 to 8008 — or change the line with "fr-kalitePort" from 8006 to 8008 (this works to get rid of English, even if "en-kalite-Port" remains 8008).

More Documentation? Please see the original KA Lite README.

Similar for Calibre: Modify this same config.json file (live at /library/www/html/iiab-menu/config.json) to change calibrePort (e.g. from port 8010 to 8080) within IIAB's dynamic menuing system.

What about Kolibri, also from Learning Equality? Please see these #841 for several emerging designs to integrate Kolibri within IIAB.

See: What are the default passwords?

How do I add zoomable maps for my region?

As of August 2018, OpenStreetMap (OSM) regional map packs became almost 10X smaller, offering far more detail — and are easier to install — thanks to regularly published vector-based tilesets (instead of the older bitmap tiles). Online samples are viewable for the San Jose in the Bay Area (includes this 109MB regional dataset) or choose Central America & the Caribbean (includes this 1.1-1.8 GB regional dataset).

Other regions can quickly be installed by following the full instructions & explanation in our README.

ADVANCED: learn how to combine multiple .mbtiles files (vector map files, highlighting different regions) into a single .mbtiles file, using append2region.

SIMPLE ALTERNATIVE: Consider downloading the 10-layer http://oer2go.org/viewmod/en-worldmap-10 (10.7GB) to /library/www/html/modules in a pinch, if you're running our of time, as the download is all you need to make basic maps happen. The Catch: this download can take hours, as it includes a huge number of small files.

INVITATION: If you can help ongoing efforts to polish maps for children in offline schools in all countries, directly contributing to beautifying OpenStreetMap thereby bringing Earth to life for all, Thank You! Read more at (#877) and please do get in touch to learn more!

WordPress & Moodle Administration: What tips & tricks exist?

How do I set the WordPress URL (like http://box/wordpress) so it works for everyone?

  • Make sure the very first login to WordPress uses the URL that your community wants to use long-term (e.g. http://box.lan/wordpress on the LAN-side of IIAB, or a campus-wide URL on the WAN-side of IIAB). WordPress will "permanently" hard-code the URL from then onwards.

How do I optimize WordPress and Moodle for high-traffic usage?

  • Then run as root: "cd /opt/iiab/iiab && ./runrole httpd && reboot"
  • Of course, make sure your Internet-in-a-Box has enough RAM and disk! Background: #1147

Optionally you might further customize the 5 settings {upload_max_filesize, post_max_size, memory_limit, max_execution_time, max_input_time} in /etc/php/7.x/apache2/php.ini (reboot if so!) This can also be done prior to install, almost halfway down /opt/iiab/iiab/roles/httpd/tasks/main.yml

How do I copy a complete installation of WordPress to another Internet-in-a-Box?

How do I integrate IIAB Apps and Content Packs (and custom menuing!) into a larger WordPress site?

Please see Joshua Kanani's WordPress plugin instructions. Thank you for providing feedback in support of this emerging effort!

See: What is local_vars.yml and how do I customize it?
See: Can I upgrade or reinstall server apps?
See: Is campuswide access possible for all server apps?

Elgg Administration: What tips & tricks exist?

You may want to set a campus-wide URL for your Elgg social network (other than the http://box/elgg default) such as http://hogwarts/elgg or http://10.10.10.10/elgg.

If so, please see the table `elgg_sites_entity` as documented in roles/elgg/templates/elggdb.sql.j2

It (might) also be possible to have more than one Elgg URL, each with a different hostname and/or IP address. However this (might) possibly cause the creation of distinct Elgg sites, each with different content.

More Documentation? Please see the original Elgg README.

See: What are the default passwords?
See: Can I upgrade or reinstall server apps?

Captive Portal Administration: What tips & tricks exist?

When installed on Raspbian, Internet-in-a-Box (IIAB) offers the option of a basic Captive Portal since IIAB 6.7, so new users don't have to type in URL's (like http://box, http://box.lan or http://172.18.96.1) into their browser.

This is similar to pages that appear automatically when you connect to Wi-Fi in airports/hotels/restaurants. It helps provide immediate access to those who have trouble typing in URL's, or live in countries that do not use Latin-based languages in their URL's.

CAUTION: if you are using IIAB 6.7, please check a few Known Issues.

Note that some schools prefer to disable Captive Portal entirely, which can be done as follows:

  • Edit /etc/iiab/local_vars.yml so it contains captive_portal_enabled: False
  • cd /opt/iiab/iiab
  • ./runrole captive-portal

Or in a pinch you can disable Captive Portal right away, by running:

  • rm /etc/dnsmasq.d/capture
  • systemctl restart dnsmasq
  • a2dissite 001-captive-portal     # removes symbolic link /etc/apache2/sites-enabled/001-captive-portal.conf
  • systemctl reload apache2

As new phones and devices appear, different browsers on different versions of Android, Windows, iOS and Linux will require usability (UX) refinements and we'd love your help!

If you face Captive Portal issues, please send us screenshots (or photos of any error messages!) by clicking "New issue" in the top-right of: https://github.com/iiab/iiab/issues — don't forget to include the make/model of your client device along with the specific version of its OS!

Finally if you're someone who can improve IIAB's Captive Portal functionality directly, please look over checklist #1182 and explore its Ansible & Python code here.

See: My Android device says "Connected, no Internet" and won't browse http://box
See: Any other networking tips?
See: What is local_vars.yml and how do I customize it?

How can I try XO laptop services?

Starting with IIAB 6.5+, you can test XO laptop services by uncommenting lines under "5-XO-SERVICES" within /etc/iiab/local_vars.yml

Finally, run "cd /opt/iiab/iiab" then "./iiab-install --reinstall" (formerly "./runansible") being patient until it finishes.

See: What is local_vars.yml and how do I customize it?

Can my XO-based server boot with a unique startup sound?

Yes, when using an XO as a server, it is easy to mistake it for a child's laptop, when it has been detached from storage and networking components.

Here are instructions for adding a unique startup sound.

Is campuswide access possible for all server apps?

No: several of these server apps fail when accessed over the WAN side of an Internet-in-a-Box, but work well over the LAN side or internal-WiFi of an Internet-in-a-Box.

Still: WordPress, Nextcloud, Moodle and others can be modified using an evolving arsenal of tricks that we hope you too can help refine!

The challenge is to get the most urgently needed campuswide LMS-like apps working well enough for campus-like environments (rather than perfectly in all situations, unfortunately not possible given modern cybersecurity threats!)

ASIDE: efforts are ongoing to make snappy/mnemonic URL's (like http://box/books) in support of teachers' and medical clinics' desires to rapidly onramp information literacy among new users.

See: What security tips exist?

Is there a file like AUTOEXEC.BAT to run jobs on boot?

Many Linux OS's offer /etc/rc.local — Internet-in-a-Box (IIAB) recommends /usr/libexec/iiab-startup.sh if you're concerned that local operators might overwrite rc.local

/usr/libexec/iiab-startup.sh is put in place by iiab-startup.yml at the end of Stage 2 during IIAB's installation.

Can I permanently attach an external USB drive, to add more content?

If your Internet-in-a-Box (IIAB) internal storage is full, here's a way to place additional content on an external USB drive or USB memory stick.

Format the USB drive with the ext4 filesystem: 

 mkfs.ext4 /dev/sdX

Before running the above, change 'X' so that it corresponds to your actual USB drive. You can uncover this (its device name) by running commands like "lsblk" or "blkid" with "df -h".

Label the USB drive (e.g. "IIAB-LIBRARY-EXT" in this case) again filling in 'X' before you run: 

 e2label /dev/sdX IIAB-LIBRARY-EXT

Put this line (using the same label as above) into your IIAB's /etc/fstab 

 LABEL=IIAB-LIBRARY-EXT  /library-ext  ext4  defaults,nofail  0  0

Create the needed mount point on IIAB, by running: 

 mkdir /library-ext

After you've tested that your USB drive automounts correctly on boot, create the symbolic link(s) you need — so that IIAB can find any Content Packs you've placed on the external USB drive.

Example command: (if for example you placed all your OER2Go/RACHEL modules onto the external USB drive, so they appear as /library-ext/www/html/modules/ when mounted) 

 ln -s /library-ext/www/html/modules/ /library/www/html/modules

CLARIF 1: This example assumes you're copying Content Packs onto the external USB drive so they'll appear under /library-ext using the very same layout of sub-folders that IIAB uses for content within /library on its internal drive.

CLARIF 2: If this USB drive is plugged into another Linux computer, the above example folder might automount differently, e.g. appearing as /media/usb/www/html/modules

CLARIF 3: When copying large Content Packs, we strongly recommend the rsync -av command, so that files are not lost and the copy process can continue if interrupted — while preserving ownership and timestamps.

See: Can teachers display their own content?
See: How do I customize my Internet-in-a-Box home page?
See: How do I add ZIM files, like Wikipedia?

How do I back up, shrink & copy IIAB microSD cards?

Privacy Practices for removing student/teacher personal data and protecting medical confidentiality will emerge at #1516 and/or IIAB/Security.

IIAB communities around the world would love your help making a 1-to-2 minute "Offline YouTube" (friendly screencast) outlining the best approach(es) below — and how to use them — please if you can, do consider making any such very short video!

1. On Linux or macOS, we strongly recommend the built-in command dd.

  • If you are copying to a different brand/model of microSD card that happens to be a few bytes smaller, 'dd' alone will fail!
  • If so, you can solve this using the min-sd and cp-sd commands found here (min-sd is the underlying magic that shrinks or truncates microSD cards, without any data loss).

2. If you have access to the "Desktop" (graphical) version of Raspbian, click the Raspberry start icon (top-left of screen) -> Accessories -> SD Card Copier:

  • This works to copy to another brand/model of microSD card that happens to be a few bytes smaller!
  • Copy from the Raspberry Pi's internal microSD to an external microSD (placed in a microSD card reader/writer, that plugs into one of your Raspberry Pi's USB ports).
  • You can also copy one external microSD card to another, if you have 2 microSD card readers/writers.
  • Instructions:
    • Read the "SD card copier" section which is the third headlined section in "The latest update to Raspbian" (below sections "Bluetooth" and "Bluetooth audio") from May 13, 2016. Likewise you can read the equivalent text underlying its Help screen.
    • This approach ("piclone" is the underlying command) is a bit slower but far easier to understand than other methods, and can be a real lifesaver when hardware resources are scarce!

3.1 On Windows 10, consider a "Beta" pre-release of dotNet Disk Imager which promises to be a "dotNet equivalent to Win32 Disk Imager, but more lightweight and with more features." [2019-05-06, Tim Moody got this to work on Windows 10: "first time it stopped on the second partition after it asked me to format, like win32 imager...but it has a button to wipe the device and after I did that it completed"]

3.2 On Windows 7 or Windows 8 (must be prior to Windows 10!) consider the "Read" button in Win32 Disk Imager to back up an IIAB microSD to your Windows hard disk:

  • If you are copying to a different brand/model of microSD card that happens to be a few bytes smaller, this will fail! In which case try any of the alternate approaches listed above and below, or buy a larger microSD card.
  • Before you begin the copy, specify a proper path and filename in the "Image File" textfield on top. We recommend you choose a filename ending with ".img"
  • Copying from a microSD card will NOT work on Windows 10, which views the card as two drives, one of which Windows claims is not formatted (because it's Linux / ext4). It appears Win32 Disk Imager will however copy from microSD's on all versions of Windows up to and including Windows 8.1.

3.3 Please try our prototype IMAGER software to back up, shrink (truncate) and copy Internet-in-a-Box microSD cards:

  • IMAGER does more than just make backups and duplicate (similar to Etcher.io and Win32 Disk Imager) as it permits you to use other manufacturers' microSD cards even when they are marginally smaller!
  • CLARIF: this only works on Windows as of IMAGER version 0.2

4. Is it possible Clonezilla can do part of this job? Clonezilla is free software for disk cloning, disk imaging, data recovery, and deployment.

See: How do I customize my Internet-in-a-Box home page?
See: Can I upgrade or reinstall server apps?
See: What security tips exist?
See: Can I permanently attach an external USB drive, to add more content?

What are the best places for community support?

As our community forums are being rebuilt, please consider the "Discussion" page at Wikipedia's Internet-in-a-Box Meta-Wiki — don't hesitate to write to these 2 mailing lists:

Describe your issue in full (with context) so that others may help — including screenshots if possible, Thanks! The fastest response will arise if you post a "New issue" here:

Those who do not have GitHub accounts should consider creating one. While you can write to bugs @ iiab.io, we apologize that a response is NOT guaranteed.

Consider our Community/Design calls, that take place live most every Thursday, at 10AM NYC Time off of: http://MINUTES.IIAB.IO

Finally, please take inspiration from our earlier work for One Laptop Per Child's global grassroots communities, enabling nearby educational communities to connect on a local level, powerfully/directly helping each other: http://olpcMAP.net

CONTACT: if need to get in touch regarding strategic alliances or partnerships with Internet-in-a-Box, please email Adam Holt (holt @ laptop.org).

See: What are the default passwords?
See: How can I remotely manage my Internet-in-a-Box?
See: What are the default passwords?
See: How can I help?

How can I help?

Great you asked!

Take a look at our weekly Agenda/Minutes to see what others are working on.

Technical developers please see our IIAB Contributors Guide and look through the tasks in our upcoming milestones.

Implementers and IT people can help us improve this very (wiki i.e. editable) document (FAQ.IIAB.IO) as well as Wikipedia's Internet-in-a-Box Meta-Wiki.

Librarians, videographers and designers are needed to help us deepen our communications — please make contact directly if you're able to help! With apologies that our original list of volunteer microtasks is currently quite stale.

The voices and participation of in-field implementers and teachers are always welcome (over WhatsApp or Skype if necessary, even if your English is not perfect!) as you are the 1st-line actionists that literally make this all possible! "TLC's" a.k.a. Technology Learning Coordinators a.k.a. local heros are indeed the secret sauce that make everything possible~

Finally, everyone is encouraged to post ideas and suggestions to these 2 community mailing lists:

Serious digital librarians are also invited us to join our content engineering calls, that occur on certain Saturdays, building off our [1] Content Hackathon, refining "web scraping" techniques that make available entirely new (categories of) high-quality Content Packs.

This section below is years-old and needs a complete overhaul:

Take seriously the "Features Planned" section of our Features page helping schools globally getting their highest priorities implemented.

Schools greatly benefit from testing on diverse hardware if you can help! Online contribution are strongly welcome, with in-person human interaction at our quasi-quarterly face-to-face meetups advancing our education efforts faster yet.

Finally, organizing everyone's many ideas, use cases and docs is real work, and as such we very strongly welcome savvy communicators!

See: How can I remotely manage my Internet-in-a-Box?
See: What are the best places for community support?
See: How can I donate to Internet-in-a-Box?

How can I donate to Internet-in-a-Box?

Please write if you can assist specific efforts in Haiti, Mexico — or otherwise.

Thank you!

Where can older versions of IIAB/XSCE be found?

Since May 2017, IIAB code has been available at: https://github.com/iiab

Prior to May 2017, XSCE code was available at: https://github.com/xsce/xsce

Release History:

Older RPM builds from 2013 may be available from http://archive.org

See: What are the best places for community support?
See: How did IIAB/XSCE's design evolve?

How did IIAB/XSCE's design evolve?

Here's our brief-but-growing participatory design archive / lineage:

  • Our earliest work is based on One Laptop Per Child's original XS design and implementation which arose in January 2007 to be used in many countries, thanks to John Watlington and Daniel Drake.
  • Jerry Vonau greatly cleaned up XS(CE) networking, from approximately 2010 onwards, so that vital new hardware and networking topologies became possible.
  • After the XS Community Edition grassroots team came together during the middle of 2012, using the XSCE name selected by George Hunt, Sridhar Dhanapalan wrote the Design Document in September 2012.
  • Field implementer Tony Anderson expanded on these ideas laying out some Use Cases in October 2012, while many others contributed to a broadening roadmap of features.
  • Internet-in-a-Box (also built by volunteer professional, including Caltech and JPL software engineers) was founded separately by Braddock Gaskill in this same mid-2012 timeframe, in Southern California.
  • David Farning's Activity Central team supported several developers to work on XSCE during the 2013 and 2014 timeframe, including Anish Mangal, Anna Schoolfield and others!
  • German Ruiz at Fundación Zamora Terán expanded support for XSCE in Nicaragua, Columbia, Dominican Republic and Honduras (etc), as the natural successor to OLPC's original XS.
  • The XSCE project embraced the Internet-in-a-Box name and IIAB's underlying OpenStreetMap work increasingly from 2013 onwards, until formally adopting the Internet-in-a-Box name (IIAB) in early 2017.
  • Beginning in 2014, the XSCE project greatly increased its content collaboration with Internet-in-a-Box (hence our new name), with Kiwix.org, and with RACHEL (Remote Area Hotspot for Educational and Learning) -- in each case greatly assisted by Tim Moody.
  • George Hunt and Jerry Vonau made our critical transition to Raspberry Pi (and Ubuntu, and Debian) possible, with foundational OS/infra/networking work in 2016 permitting 2017's breakthrough into so many more communities. Enabling so many grassroots implementations that could never have afforded traditional PC-class servers and associated computer lab facilities/upkeep.

Community history is vital to all seeking to avoid reinventing mistakes of the past, thanks for Everyone's thoughtful input past & present!

Retrieved from "http://wiki.laptop.org/mediawiki/index.php?title=IIAB/FAQ&oldid=301885"