IIAB/FAQ

From OLPC
< IIAB
Revision as of 14:14, 24 February 2017 by Holt (talk | contribs) (→‎What is local_vars.yml and how do I customize it?)
Jump to: navigation, 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 XS Community Edition (XSCE) help?

Bring the power of a free Digital Library of Alexandria into the hands of any school worldwide! Read about Internet-in-a-Box (rich open content often included with XSCE/IIAB) and build up your school's very own E-book library below.

A School Server brings your classroom/school laptops together, communicating & coordinating learning in ways that deeply empower kids, teachers and community.

XSCE/IIAB is built by professional volunteers, inspired by One Laptop per Child's famous laptops and their innovative Sugar Learning Platform -- but serving all!

To get a taste of longer-term possible roadmaps, please see Tony Anderson's suggested use cases, and one possible larger XSCE Vision.

Where is XSCE/IIAB used?

Since 2014/2015, XSCE/IIAB is used in more than 10 countries, from smaller communities to large-scale deployments.

Examples include several orphanages and schools in Haiti to a youth community in Malaysia, to villages in Northern India, to a girls science school in Rwanda, to rural communities and libraries across southwest Ghana -- and more broad Central American deployments like Nicaragua, Costa Rica and 6 schools in the Dominican Republic beginning late 2015.

Libraries and rural medical clinics are also avid users of XSCE/IIAB.

Of course, many contributors are using XSCE/IIAB for other personal/community purposes as well, helping refine our community product for diverse/larger impact.

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

Purchase a packed hard-drive full of the incredible Wikipedia + Maps + Literature + Khan Academy resources of http://internet-in-a-box.org.

This permits entirely new opportunities for semi-connected schools and offline libraries worldwide, for the 1st time ever starting in 2013.

We'd like educators' suggestions especially -- how should kids best take advantage of these crown jewels of learning? Perhaps starting with OLPC/Sugar's laptop browser in places like: 

http://box.lan/maps
http://box.lan/books
http://box.lan/library
http://box.lan/owncloud
http://box.lan/khanacademy

Coming Soon: In the near future (XSCE 6.x) we hope the Pathagar "E-book library" will begin to work much better with XSCE!

Can teachers display their own content?

Yes, teachers can spontaneously insert (and remove!) their own USB memory stick(s)/drive(s) anytime, using the school server hardware's USB port. Somewhat like an informal projector, the teacher's contents will then appear to students almost instantly, off of http://box.lan/usb

A priori, the teacher should create a folder called "usb" on their USB memory stick, placing audio/video materials, handouts, challenges or presentation(s) inside that folder.

The USB stick(s)/drive(s) content will then appear live to students, in places like: 

http://box.lan/usb/USB0
http://box.lan/usb/USB1

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

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

What hardware should I use?

XSCE/IIAB (Internet-in-a-Box) is free software that runs on many different hardware platforms. Some of the most popular examples include:

  • Deployment Managers: a paticularly tough, well-rounded, lower-power unit (great for developing world) is the Intel NUC many of us had had great luck with starting in 2014. We typically insist on NUC models that accept SATA (2.5 inch hard drives) and work with DC voltages up to 19V (low-end NUC models only work right near 12V). This is not a fan-less device, however it's proved extremely reliable to date.
  • The NUC's competitor (Gigabyte BRIX) allows internal Wi-Fi to scale beyond the NUC's limit of 12 connections maximum. In order to make this happen, insert an appropriate Atheros Wi-Fi module (typically < $10). Such mods are generally not possible with Intel NUC's since 2015 (5th generation) as the Wi-Fi module is soldered in.
  • Some are very hopeful that ARM CPUs like TrimSlice / Utilite and Cubox by SolidRun will catch up with Intel NUC in overall stability/reliability. Check back as many more global deployments' experiences accumulate, and rugged low-end hardware hopefully emerges eventually, or ask a question at http://iiab.io !

What OS should I use?

Smaller deployments often prefer the cutting-edge features provided by a recent version of the Fedora Operating System, similar to OLPC OS 13.2.7. We generally recommend Fedora 22 or higher.

Larger deployments to step back from the bleeding edge, prefering the decade-long support provided by CentOS 7 (security updates until 30 June 2024) to avoid the rapid annual turnover of Fedora.

Both above are free and open software systems supported by enterprise Linux corp Red Hat, Inc founded in 1993. Read a bit more about XSCE 6.0's out-of-the-box OS choices here.

Other OS/distribution support for this global community project would be most welcome in future!

Is a quick installation possible?

Yes, a number of XSCE/IIAB 6.x Pre-installed Images are available and more are in the works.

Please see the new Install Instructions, especially the "short cuts" section, for a list of what is available, where to get it, and general instructions on installing. Visual shortcuts to some of the more common images can also be found at the top-right of http://schoolserver.org

Images for each platform are accompanied by a README page with additional instructions.

Advanced/legacy users may also find useful tips in Tom Gilliard's 6.0 Installation Notes & Screenshots and Tony Anderson's XSCE 6.0 Install Recipe. Be sure to turn off UEFI in your PC/server's BIOS if possible! Jerry Vonau is working on a routine that may allow UEFI support out-of-the-box in future. Legacy/complete XSCE 5.1 installation instructions are here.

Finally, to get down to real business (education!) there are a variety of ways to add content to your XSCE/IIAB Internet-in-a-Box server. Please see Adding Content.

After installation, please explore learning materials within your own server's http://box.lan -- and also get to know the Admin Console at http://box.lan/admin which permits you to (1) configure your school server and (2) download new content. Example screenshots: (very stale from 2015, but that's the idea!)

We're hopeful that more offline installers will appear for many of the most common hardware platforms, like Raspberry Pi 3, in the near-future. George Hunt and others have worked extremely hard on these, and greatly appreciate all your "fieldback" !

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

This is a very hard question depending on the growth path of your electrical needs, maintenance options within the country in question, price, theft, etc. Some experienced deployment voices provide concrete examples, typically involving a standard 12-volt deep-cycle battery. Please don't wait to get your feet wet today however! That means investing in the hard work of research, getting this right for your own community:

http://wiki.laptop.org/go/XO_Solar
http://lists.laptop.org/listinfo/power
http://wiki.laptop.org/go/Battery_and_power
http://schoolserver.wordpress.com/training/power-when-its-not-always-available/

Thanks for taking solar engineering seriously, as we do wherever possible! Engineers definitely 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.

How do I change the wireless network name?

The wireless network name is how people connect to your school server when they are using a Wi-Fi device. This name is also known as an SSID.

How to change 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 router.
  • If it's under direct OS control, then the school server is the wireless access point. George Hunt's command "xs-hotspot-on <SSID>" solves this on XO-1.5 and similar. Conversely "xs-hotspot-off" to turn the internal hotspot off entirely. You might also open your server's Admin Console http://box.lan/admin by logging in as xsce-admin per usual, then change the SSID (wireless name) there, under Configure -> Internal WiFi AP -> Internal Wifi 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 XSCE! If you still insist on editing this file despite the danger, consider "systemctl restart hostapd.service" to avoid rebooting.

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

http://box.lan will 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 using http://box.lan/admin -> Configure -> Network Parameters -> Host Name, if you click "Save Configuration" then "Install Configured Options" (waiting patiently for that to complete under http://box.lan/admin -> Utilities -> Display Job Status; which often takes ~25min on a Raspberry Pi 3!)

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/XSCE/xsce/blob/8649c1ae73631ce9d9d10ab358eb5571c9e48742/roles/network/templates/named/school.external.zone.db
https://github.com/XSCE/xsce/blob/8649c1ae73631ce9d9d10ab358eb5571c9e48742/roles/network/templates/named/school.internal.zone.db
https://github.com/XSCE/xsce/blob/8649c1ae73631ce9d9d10ab358eb5571c9e48742/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

Any other networking tips?

See local_vars.yml below.

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 "./runansible" from directory /opt/schoolserver/xsce when your Internet connection is live.

A high-level networking summary is here: https://github.com/XSCE/xsce/wiki/IIAB-Networking-Overview

More advanced networking insights will 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 at http://IIAB.io and on mailing list server-devel@lists.laptop.org !

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

Put variables for your installation(s) to override defaults here. As is explained within the IIAB Architecture doc, we recommend you do NOT modify default_vars.yml.

An example /opt/schoolserver/xsce/vars/local_vars.yml is posted for comparison.

Also, a couple practical mods are posted at the bottom of the IIAB Networking document.

Where security tips exist?

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

How do I customize my school server's start page?

If you want to showcase your school or community logo/colors on the portal/start page (what people see at http://box.lan), you can customize /library/www/html/home/index.html, where most standard HTML tags should work. Please create a backup copy of your ongoing index.html beautifications regularly!

Coming soon in 2017, Dynamic Menuing will be an alternative approach for those wanting far less hand-coding, that (as a bonus) auto-adjusts all http://SERVERNAMES:PORTS live using browser-side Javascript, for maximum deployment flexibility. To enable this on your server, please read about Menu Definitions and HTML Fragments within this page: https://github.com/xsce/xsce/wiki/IIAB-Menuing

Likewise as many educators want quick customizations of their portal/menuing beyond the logo, some may consider experimental WYSIWYG tools like DokuWiki, WordPress, or Moodle. For example you might lay out your content in an indigenous language, linking to content gems truly relevant to locals. To try these approaches, visit your server's Admin Console at http://box.lan/admin -> Configure tab -> Server Portal -> Select Server Home Page. As of XSCE 6.2, your 4 choices here are:

  • /home
  • /xs-portal
  • /wordpress
  • /wiki

Of course enable WordPress or DokuWiki correspondingly, at the top of that page. Then click "Save Configuration", click "Install Configured Options" then monitor the result (takes about 25min on a Raspberry Pi 3) under "Utilities" tab -> "Display Job Status".

Finally, technical tips are contained in our older Portal README. But if you need further customization suggestions and tips, don't even hesitate to post to our http://iiab.io forums and/or write to: https://groups.google.com/group/unleashkids !

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.

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

Great question: the magicians behind http://internet-in-a-box.org anticipated this will be critical. In the same vein, Internet-in-a-Box improved its Wikipedia full-text-search in 2014/2015, which remains compatible with XSCE 0.4, 5.x and 6.0.

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

On the high end, XSCE/IIAB's Admin Console supports piecewise incremental content updates for those schools with extremely high/affordable bandwidth.

More typically, schools receive USB 3.0 hard drives and 128GB every semester or so, containing new maps/encyclopedia/books/video lessons flown/driven in from a partner.

Keep in touch as new options evolve! Make contact with http://unleashkids.org if you want to order a copy of the latest Internet-in-a-Box content from these volunteers' community effort.

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

Log into your school server's Admin Console (typically http://box.lan/admin) and click "About" in the top menu.

Compare the 40-character string "Commit ID" to "Latest commit" at https://github.com/XSCE/xsce/tree/release-6.2 to confirm you have XSCE 6.2 (should begin with 929ed54 if you're running 6.2 RC2 from early February 2017). In General: if the "Commit ID" matches "Latest commit" you have the latest, for that version ("release-6.2" in this case).

Note the letter 'g' sometime appears in front of the githash, for example g929ed54 which is normal!

Experts: check the "Version" field on your About screen, which should show "release-6.2" if you're running a pre-release from https://github.com/xsce/xsce/commits/master. Feel free also to monitor the latest commites at https://github.com/xsce/xsce/commits/release-6.2.

What technical documentation exists?

Core XSCE/IIAB 6.2 Docs are being migrated to https://github.com/xsce/xsce/wiki (IIAB/XSCE 6.2) in early 2017, and soon to https://github.com/iiab/iiab/wiki (for IIAB 6.3 and beyond!)

Start with February 2017's new Install Doc, focusing on the "short cuts" section!

Living Docs are ever-evolving for great reasons, as technical progress is rapid, so you may want to bookmark our http://IIAB.io community forums as well.

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

The earlier XSCE 5.1 + Internet-in-a-Box Install Doc for Intel NUC from 2015 can sometimes be very useful for 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 experience setting up 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!

How can I help?

Great you asked! Take a look at our quasiweekly Agenda/Minutes to see what others are working on, after getting to know http://iiab.io, and see if you can knock off a few volunteer microtasks.

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!

Please also suggest your own ideas on mailing list server-devel@lists.laptop.org, or contact Adam Holt (holt @ laptop.org), thanks!

Where can older versions of XSCE be found?

Older RPM builds from 2013, at your own risk, may be available from: http://xsce.activitycentral.com/repos/xsce/devel.

Or consider main repo definition: http://xsce.activitycentral.com/repos/xsce-devel.repo

How did XSCE's design evolve?

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

Original OLPC XS design and implementation is available here.

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

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