FAQ: Difference between revisions

From Internet in a Box
No edit summary
 
(521 intermediate revisions by 4 users not shown)
Line 1: Line 1:
<!-- == Why would I want to use IIAB? ==
There are a number of reasons why you might want to use IIAB.  For example, you might want to access resources like Wikipedia, Stack Exchange and more offline, or you might want to create an offline version of the internet for use as a learning hotspot in a classroom or library.  Additionally, IIAB can be used to host your own services. -->
== How does Internet-in-a-Box (IIAB) help? ==
== 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!  Please listen to the [https://www.bbc.co.uk/programmes/w3cszv1s 23min BBC podcast "How to put the internet in a box"] from 2020-10-20.  See also a [https://youtu.be/HkeS_EAIpv4 great community example in North India] (3min) from 2021-02-14.  Internet-in-a-Box (IIAB) is also used in medical clinics and libraries, as can be seen in this [http://youtu.be/xI3Ed008Mxo Dominican Republic video].
Do you need the best of the Internet (Wikipedia, OpenStreetMap, Khan Academy, Stack Exchange, ETC) with local content ''and'' learning apps for all?


'''[https://internet-in-a-box.org Please see our internet-in-a-box.org web site!]'''
Customize an "Offline Internet" for your school, for your community — or for your very own family!


Whether costing $30 or $300, an Internet-in-a-Box "learning hotspot" <!--server--> brings your classroom/school laptops together, [http://wiki.laptop.org/go/IIAB#Our_Product communicating & coordinating learning] in ways that deeply empower [http://planet.laptop.org kids], [http://unleashkids.org teachers] and [https://meta.wikimedia.org/wiki/Internet-in-a-Box community].
Listen to the [https://www.bbc.co.uk/programmes/w3cszv1s 23min BBC podcast "How to put the internet in a box"] (2020-10-20) to learn how this works. See also a [https://youtu.be/HkeS_EAIpv4 great community example in North India] (3min) from 2021. Internet-in-a-Box (IIAB) is used in medical clinics as well, as can be seen in this [https://youtu.be/xI3Ed008Mxo Dominican Republic video].


Internet-in-a-Box arose from One Laptop Per Child's original [http://schoolserver.org school server] (2007-2012) and our [http://olpcMAP.net global grassroots community], together adding [https://internet-in-a-box.org/#quality-content 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!<!-- [[#What_can_I_do_with_E-books_and_Internet-in-a-Box.3F|below.]]-->


Please do consider [https://opensource.com/article/17/5/internet-in-a-box-raspberry-pi creating your own Internet-in-a-Box] [[http://people.sugarlabs.org/~icarito/newsletter_sugarlabs/ProofSLNewsP4.psf.pdf 1]] [[http://people.sugarlabs.org/~icarito/newsletter_sugarlabs/ProofSLNewsP5.psf.pdf 2]] by reviewing [[#Where_can_I_see_live_demos_of_Internet-in-a-Box.3F|live demo examples]] and looking over our <!--growing collection of--> [https://www.youtube.com/channel/UC0cBGCxr_WPBPa3IqPVEe3g HOW-TO videos].
'''[https://internet-in-a-box.org Please see our internet-in-a-box.org web site.]'''


We are proud that IIAB is built by a [https://internet-in-a-box.org/pages/contributing.html global network of professional volunteers], inspired by [http://one.laptop.org One Laptop per Child's] famous laptops and their innovative [http://sugarlabs.org Sugar Learning Platform] &mdash; but now with a [http://wiki.laptop.org/go/XS_Community_Edition/Vision wider vision] of serving all, both in schools and beyond!
Internet-in-a-Box brings the power of a free Digital Library of Alexandria to any community worldwide.


See: [[#Where_can_I_see_live_demos_of_Internet-in-a-Box.3F|Where can I see live demos of Internet-in-a-Box?]]<br>
''Whether costing $10 or $1000, an Internet-in-a-Box "learning hotspot" <!--server--> brings classroom/library devices to life, <!-- https://wiki.laptop.org/go/IIAB#Our_Product &mdash; communicating & coordinating learning --> in ways that very deeply empower <!-- http://planet.laptop.org --> learning <!-- https://unleashkids.org teachers --> and <!-- https://meta.wikimedia.org/wiki/Internet-in-a-Box --> community.''
See: [[#Is_a_quick_installation_possible.3F|Is a quick installation possible?]]
 
 
RECAP: To [https://opensource.com/article/17/5/internet-in-a-box-raspberry-pi create your own Internet-in-a-Box] [[https://people.sugarlabs.org/~icarito/newsletter_sugarlabs/ProofSLNewsP4.psf.pdf 1]] [[https://people.sugarlabs.org/~icarito/newsletter_sugarlabs/ProofSLNewsP5.psf.pdf 2]], look over a few [[#Where_can_I_see_live_demos_of_Internet-in-a-Box%3F|live demo examples]] and check out our '''[https://www.youtube.com/channel/UC0cBGCxr_WPBPa3IqPVEe3g growing collection of videos]'''.
 
Internet-in-a-Box arose from One Laptop Per Child's original <!-- http://schoolserver.org --> school server (2007-2012) and our [http://olpcMAP.net global grassroots community], adding in the [https://internet-in-a-box.org/#quality-content quality content and learning apps] shared by the best educational systems worldwide.
 
Now anyone can do this, building up your local community's very own 21st Century digital library, using free and open source software. <!-- ''let us help you make this happen!  <!-- as this FAQ document now outlines, to help you make that happen!<!-- [[#What_can_I_do_with_E-books_and_Internet-in-a-Box%3F|below.]]-->
 
 
READY, SET, INSTALL: Internet-in-a-Box (IIAB) is built by a [https://internet-in-a-box.org/contributing.html global network of professional volunteers], inspired by [https://en.wikipedia.org/wiki/One_Laptop_per_Child One Laptop Per Child's] famous laptops and their innovative [https://sugarlabs.org Sugar Learning Platform] &mdash; ''but now with a <!-- https://wiki.laptop.org/go/XS_Community_Edition/Vision --> much wider vision of serving all &mdash; both in schools and beyond.''
 
See: [[#Is_a_quick_installation_possible%3F|Is a quick installation possible?]]<br>
See: [[#What_services_.28IIAB_apps.29_are_suggested_during_installation%3F|What services (IIAB apps) are suggested during installation?]]<br>
See: [[#Where_can_I_see_live_demos_of_Internet-in-a-Box%3F|Where can I see live demos of Internet-in-a-Box?]]


== Where is Internet-in-a-Box used? ==
== 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.
Internet-in-a-Box (IIAB) <!-- was originally called the OLPC School Server Community Edition (XSCE) and --> is in use in dozens of countries, from smaller communities to large-scale institutional deployments.


Examples include [http://schoolserver.wordpress.com/2013/03/29/my-first-school-server-deployment/ orphanages] and schools in <!--[http://www.unleashkids.org/category/haiti/--> [http://olpcMAP.net Haiti], to schools across southern [http://kidsoncomputers.org Mexico], to rural communities and libraries across southwest [http://ghanatogether.blogspot.com/ Ghana], to remote schools in [https://100pilabs.school.blog/ Myanmar/Burma] and Cambodia, to villages across [https://medium.com/eka-foundation India]<!--[http://bhagmalpur.wordpress.com India]-->, to a girls science school in [http://www.rwandagirlsinitiative.org/ggast/ Rwanda], to community centers in [https://www.hyracbox.com/ Kenya], to a youth community in rural [http://olpcbasecamp.blogspot.com/ Malaysia], to [http://www.wakoma.co/ South Africa] townships -- as well as broad [https://github.com/germanrs/xsce Central American deployments] like [http://fundacionzt.org/ Nicaragua], Costa Rica, and the Dominican Republic.
Please see our regular global community updates at: [https://twitter.com/internet_in_box @internet_in_box]


Libraries and rural medical clinics are also avid users of IIAB, in places like [https://healthpolicy.fsi.stanford.edu/research/guatemala-children-crisis Guatemala], the [http://youtu.be/xI3Ed008Mxo Dominican Republic] and this '''[https://meta.wikimedia.org/wiki/Internet-in-a-Box#Uses_since_2012 growing list !]'''
Examples include [https://schoolserver.wordpress.com/2013/03/29/my-first-school-server-deployment/ orphanages] and schools in <!--[http://www.unleashkids.org/category/haiti/--> [http://olpcMAP.net Haiti], schools across southern [https://kidsoncomputers.org Mexico], rural communities and libraries across southwest [https://ghanatogether.blogspot.com/ Ghana], remote schools in [https://100pilabs.school.blog/ Myanmar/Burma] and Cambodia, villages across [https://medium.com/eka-foundation India]<!--[https://bhagmalpur.wordpress.com India]-->, a girls science school in [https://www.rwandagirlsinitiative.org/ggast/ Rwanda], community centers in [https://www.hyracbox.com/ Kenya], a youth community in rural [https://olpcbasecamp.blogspot.com/ Malaysia], to [https://www.wakoma.co/ South Africa] townships — as well as broad [https://github.com/germanrs/xsce Central American deployments] like [https://fundacionzt.org/ Nicaragua], Costa Rica, and the Dominican Republic.


Many [https://groups.google.com/group/unleashkids 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!
Libraries and rural medical clinics are also avid users of IIAB, in places like [https://healthpolicy.fsi.stanford.edu/research/guatemala-children-crisis Guatemala], the [https://youtu.be/xI3Ed008Mxo Dominican Republic].  <!-- and [https://meta.wikimedia.org/wiki/Internet-in-a-Box#Uses_since_2012 this list.] -->


See: [[#Where_can_I_see_live_demos_of_Internet-in-a-Box.3F|Where can I see live demos of Internet-in-a-Box?]]<br>
Many [https://internet-in-a-box.org/contributing.html 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: [[#Is_a_quick_installation_possible.3F|Is a quick installation possible?]]
 
See: [[#Where_can_I_see_live_demos_of_Internet-in-a-Box%3F|Where can I see live demos of Internet-in-a-Box?]]<br>
See: [[#Is_a_quick_installation_possible%3F|Is a quick installation possible?]]


== What can I do with E-books and Internet-in-a-Box? ==
== 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).
Unleash the best of Internet learning without costs or distractions.  Pack your Internet-in-a-Box (IIAB) full of incredible Wikipedia + Maps + Literature + Khan Academy + Video!


Learn how to [[#How_do_I_add_ZIM_files.2C_like_Wikipedia.3F|download high-quality free content, like Wikipedia ZIM files]].<!--is possible with a very fast Internet connection, follow the [https://github.com/iiab/iiab/wiki/IIAB-Installation#add-content "Add Content" instructions].-->
The first step is to add content gems to your IIAB.  Learn how to [[#How_do_I_add_ZIM_files.2C_like_Wikipedia%3F|download high-quality free content, like Wikipedia ZIM files]]. <!-- is possible with a very fast Internet connection, follow the [https://github.com/iiab/iiab/wiki/IIAB-Installation#add-content "Add Content" instructions]. -->
<!-- Or add content from your own USB disk or USB flash drive.  Sharing or purchasing a hard-drive packed full of incredible <i>Wikipedia + Maps + Literature + Khan Academy</i> learning resources is also possible.  Contact https://unleashkids.org volunteers should this be necessary.


Or add content from your own USB disk or USB flash drive.  Sharing or purchasing a hard-drive packed full of incredible <i>Wikipedia + Maps + Literature + Khan Academy</i> 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, -->


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.
Not just schools but also medical clinics, museums, and prisons are taking advantage as well as individual educators and parents taking charge by building their very own "Library of Alexandria" community learning 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:
How can kids best take advantage of these crown jewels of learning?  After you've added content, offer your students direct access via [[#What_services_.28IIAB_apps.29_are_suggested_during_installation%3F|IIAB Apps]] like:


   http://box            Your Internet-in-a-Box Library!
   http://box            Your Internet-in-a-Box Library!
   http://box/usb        Content from USB sticks/drives, that teachers can [[#Can_teachers_display_their_own_content.3F|insert anytime]]
   http://box/usb        Content from USB sticks/drives, that teachers can [[#Can_teachers_display_their_own_content%3F|insert anytime]]
   http://box:8008      [[#KA_Lite_Administration:_What_tips_.26_tricks_exist.3F|KA Lite]] (Khan Academy videos & exercises, with its own content downloader)
   http://box:8008      [[#KA_Lite_Administration%3A_What_tips_%26_tricks_exist%3F|KA Lite]] (Khan Academy videos & exercises, with its own content downloader)
   http://box:8080      [https://calibre-ebook.com/whats-new Calibre] E-Book Library: see [https://manual.calibre-ebook.com/faq.html FAQ], [https://manual.calibre-ebook.com/generated/en/calibredb.html calibredb manual], [https://manual.calibre-ebook.com/generated/en/calibre-server.html calibre-server manual] (see Calibre-Web below)
   http://box:8080      [https://calibre-ebook.com/whats-new Calibre] E-Book Library: see [https://manual.calibre-ebook.com/faq.html FAQ], [https://manual.calibre-ebook.com/generated/en/calibredb.html calibredb manual], [https://manual.calibre-ebook.com/generated/en/calibre-server.html calibre-server manual] (see Calibre-Web below)
   http://box/maps      [[#How_do_I_add_zoomable_maps_for_my_region.3F|OpenStreetMap and Satellite Photos]] for your Continent, or the entire World <!-- for [http://download.iiab.io/content/OSM/vector-tiles/ box/modules/en-osm-omt-min] or box/modules/en-worldmap/map.html or box/iiab/static/map.html -->
   http://box/maps      [[#How_do_I_add_zoomable_maps_for_my_region%3F|OpenStreetMap and Satellite Photos]] for your Continent, or the entire World <!-- for [http://download.iiab.io/content/OSM/vector-tiles/ 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/docs      FUTURE synonym for http://box/nextcloud ? -->
   http://box/wiki      MediaWiki 1.36+ (Wikipedia's own wiki software for document collaboration, used to use http://box/mediawiki)
   http://box/wiki      MediaWiki 1.40+ (Wikipedia's own wiki software for document collaboration, used to use http://box/mediawiki)
   http://box/elgg      [[#Elgg_Administration:_What_tips_.26_tricks_exist.3F|Elgg]] social network for e-learning
   <!-- http://box/elgg      [[#Elgg_Administration:_What_tips_.26_tricks_exist%3F|Elgg]] social network for e-learning -->
   http://box/info      IT support docs & eventually vids, offlined for all
   http://box/info      IT support docs & eventually vids, offlined for all
   http://box/kiwix      [[#How_do_I_add_ZIM_files.2C_like_Wikipedia.3F|Kiwix]]: amazing content & videos, contained in searchable ZIM files
   http://box/kiwix      [[#How_do_I_add_ZIM_files%2C_like_Wikipedia%3F|Kiwix]]: amazing content & videos, contained in searchable ZIM files
                           WARNING: use http://box:3000/kiwix/ to avoid the Apache/NGINX proxy e.g. for enhanced privacy [https://github.com/iiab/iiab/issues/852 #852]
                           WARNING: use http://box:3000/kiwix/ to avoid the Apache/NGINX proxy e.g. for enhanced privacy [https://github.com/iiab/iiab/issues/852 #852]
   http://box/books      [https://github.com/iiab/iiab/tree/master/roles/calibre-web#calibre-web-readme Calibre-Web] E-Book Library, an alternative to Calibre (above) with a modern interface: [https://github.com/iiab/iiab/issues/816 #816]
   http://box/books      [https://github.com/iiab/iiab/tree/master/roles/calibre-web#calibre-web-readme Calibre-Web] E-Book Library, an alternative to Calibre (above), with a modern web interface <!-- [https://github.com/iiab/iiab/issues/816 #816] -->
   http://box/moodle    Moodle 3.11+ (learning management system)
   http://box/moodle    Moodle 4.3+ (learning management system)
   http://box/lokole    [https://github.com/iiab/iiab/tree/master/roles/lokole#lokole-readme Lokole] is an Email service that works offline for rural communities, students and teachers.
   http://box/lokole    [https://github.com/iiab/iiab/tree/master/roles/lokole#lokole-readme Lokole] is an Email service that works offline for rural communities, students and teachers.
   http://box/kolibri    [https://github.com/iiab/iiab/tree/master/roles/kolibri#kolibri-readme Kolibri] 0.14.7+ is like KA Lite, to allow educators to customize+remix Content Packs. Unproxied equivalent: http://box:8009/kolibri
   http://box/kolibri    [https://github.com/iiab/iiab/tree/master/roles/kolibri#kolibri-readme Kolibri 0.15+] is like KA Lite, but much improved for educators. Unproxied equivalent: http://box:8009/kolibri
   http://box/nodered    [https://github.com/iiab/iiab/tree/master/roles/nodered#node-red-readme Node-RED] visual programming for electronics projects (IoT)
   http://box/nodered    [https://github.com/iiab/iiab/tree/master/roles/nodered#node-red-readme Node-RED] visual programming for electronics projects (IoT)
   http://box/wordpress  WordPress 5.8+ (blogging & community publishing)
   http://box/wordpress  WordPress 6.3+ (blogging & community publishing)
   http://box/mediawiki  Redirects to http://box/wiki (see above)
   http://box/mediawiki  Redirects to http://box/wiki (see above)
   http://box/nextcloud  Nextcloud 22+ (students can store their files/photos on Internet-in-a-Box, similar to Dropbox and Google Docs)
   http://box/nextcloud  Nextcloud 27+ (students can store their files/photos on Internet-in-a-Box, similar to Dropbox and Google Docs)
   http://box/runestone  Runestone Interactive Textbooks (proposed, [https://runestone.academy/runestone/books/published/thinkcspy/index.html example])
   <!-- http://box/runestone  Runestone Interactive Textbooks (proposed, [https://runestone.academy/ns/books/published/thinkcspy/index.html example]) -->
   http://box/sugarizer  Sugar Learning Platform originally from One Laptop Per Child
   http://box/sugarizer  Sugar Learning Platform originally from One Laptop Per Child


[https://github.com/iiab/iiab/wiki/IIAB-Networking#list-of-ports--services Common network ports] are listed in our [https://github.com/iiab/iiab/wiki/IIAB-Networking high-level networking summary].  Internet-in-a-Box administrators can also benefit from these web tools:
[https://github.com/iiab/iiab/wiki/IIAB-Networking#list-of-ports--services Common network ports] are listed in our [https://github.com/iiab/iiab/wiki/IIAB-Networking high-level networking summary].  Internet-in-a-Box administrators can also benefit from these web tools:


   http://box:9091      [https://github.com/iiab/iiab/tree/master/roles/transmission#transmission-readme Transmission] BitTorrent downloader, for KA Lite content provisioning etc
   http://box:9091      [https://github.com/iiab/iiab/tree/master/roles/transmission#transmission-readme Transmission 4] 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/admin      Admin Console to install content & configure IIAB. Also try http://box.lan/admin and http://10.10.10.10/admin
   http://box/munin      Network/Infra monitoring
   http://box/munin      Network/Infra monitoring
   http://box/awstats    Usage statistics
   http://box/awstats    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 [https://github.com/iiab/iiab/blob/master/roles/nginx/README.md NGINX] expertise and can help here: [https://github.com/iiab/iiab/issues/923 #923]
<!-- We could use help making several of these URL's more bulletproof across different networking environments!  Please get in touch if you have [https://github.com/iiab/iiab/blob/master/roles/nginx/README.md NGINX] expertise and can help here: [https://github.com/iiab/iiab/issues/923 #923] -->
<!--In future, we hope the [https://github.com/PathagarBooks Pathagar] [http://www.olpcsf.org/node/126 "E-book library"] will begin to work much better with IIAB!-->
<!-- In future, we hope the [https://github.com/PathagarBooks Pathagar] [http://www.olpcsf.org/node/126 "E-book library"] will begin to work much better with IIAB! -->


See: [[#Can_teachers_display_their_own_content.3F|Can teachers display their own content?]]<br>
See: [[#Can_teachers_display_their_own_content%3F|Can teachers display their own content?]]<br>
See: [[#Is_a_quick_installation_possible.3F|Is a quick installation possible?]]<br>
See: [[#Is_a_quick_installation_possible%3F|Is a quick installation possible?]]<br>
See: [[#What_services_.28IIAB_apps.29_are_suggested_during_installation.3F|What services (IIAB apps) are suggested during installation?]]<br>
See: [[#What_services_.28IIAB_apps.29_are_suggested_during_installation%3F|What services (IIAB apps) are suggested during installation?]]<br>
See: [[#Where_can_I_see_live_demos_of_Internet-in-a-Box.3F|Where can I see live demos of Internet-in-a-Box?]]<br>
See: [[#Where_can_I_see_live_demos_of_Internet-in-a-Box%3F|Where can I see live demos of Internet-in-a-Box?]]<br>
See: [[#How_do_I_customize_my_Internet-in-a-Box_home_page.3F|How do I customize my Internet-in-a-Box home page?]]<br>
See: [[#How_do_I_customize_my_Internet-in-a-Box_home_page%3F|How do I customize my Internet-in-a-Box home page?]]<br>
See: [[#What_are_the_default_passwords?|What are the default passwords?]]<br>
See: [[#What_are_the_default_passwords%3F|What are the default passwords?]]<br>
See: [[#How_do_I_add_ZIM_files.2C_like_Wikipedia.3F|How do I add ZIM files, like Wikipedia?]]
See: [[#How_do_I_add_ZIM_files.2C_like_Wikipedia%3F|How do I add ZIM files, like Wikipedia?]]


== Can teachers display their own content? ==
== Can teachers display their own content? ==
Line 93: Line 112:
# 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 [https://github.com/iiab/iiab/pull/654 exFAT-formatted sticks and NTFS-formatted portable disks] was added in February 2018.
# 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 [https://github.com/iiab/iiab/pull/654 exFAT-formatted sticks and NTFS-formatted portable disks] was added in February 2018.
# '''Teachers insert their USB sticks/drives into any of the Internet-in-a-Box's USB ports, Done!'''
# '''Teachers insert their USB sticks/drives into any of the Internet-in-a-Box's USB ports, Done!'''
# '''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'''
# '''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://10.10.10.10/usb'''


Warnings:
Warnings:
Line 100: Line 119:
# While generally not necessary (or realistic, for rural teachers etc, as mentioned on [https://github.com/iiab/iiab/issues/2277 #2277]) you can unmount drives by running: <code>systemctl stop usbmount@dev-sda*</code>
# While generally not necessary (or realistic, for rural teachers etc, as mentioned on [https://github.com/iiab/iiab/issues/2277 #2277]) you can unmount drives by running: <code>systemctl stop usbmount@dev-sda*</code>
# USB memory sticks/drives may need to be [https://github.com/iiab/iiab/issues/329#issuecomment-333330362 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: [https://github.com/iiab/iiab/issues/329 #329]
# USB memory sticks/drives may need to be [https://github.com/iiab/iiab/issues/329#issuecomment-333330362 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: [https://github.com/iiab/iiab/issues/329 #329]
# 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, please set <code>iiab_usb_lib_show_all: False</code> in [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|/etc/iiab/local_vars.yml]] prior to installing IIAB.
# 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, please set <code>iiab_usb_lib_show_all: False</code> in [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|/etc/iiab/local_vars.yml]] prior to installing IIAB.
# Note that all Linux users should be able to read and write to USB drives inserted into IIAB as of 2021-03-25 ([https://github.com/iiab/iiab/pull/2715 PR #2715]).  Kolibri requires this.  If however you prefer to block non-root users, please set <code>usb_lib_umask0000_for_kolibri: False</code> in [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|/etc/iiab/local_vars.yml]] prior to installing IIAB.
# Note that all Linux users should be able to read and write to USB drives inserted into IIAB as of 2021-03-25 ([https://github.com/iiab/iiab/pull/2715 PR #2715]).  Kolibri requires this.  If however you prefer to block non-root users, please set <code>usb_lib_umask0000_for_kolibri: False</code> in [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|/etc/iiab/local_vars.yml]] prior to installing IIAB.


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:
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:
Line 113: Line 132:
   http://box/usb/USB1
   http://box/usb/USB1


See the [https://github.com/iiab/iiab/wiki/IIAB-Installation#external-usbdrive-content Install Doc]. Finally, if you have a screen attached to your server, and occasionally see an error as follows, it is safe to ignore:
See the [https://github.com/iiab/iiab/wiki/IIAB-Installation#external-usbdrive-content Install Doc] for background details.
 
CLARIFICATION: If your Linux OS has a graphical desktop, it's common to see popup message warnings like:


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


On many Linux OS's you can make this popup go away using File Manager > Edit > Preferences > click in left column -- Volume Management > Uncheck "Mount removable media automatically when they are inserted."  [https://github.com/iiab/iiab/issues/86 #86]
It's safe to ignore these messages.  Or you can make these popup messages go away, typically by clicking through your graphical File Manager's preferences or OS settings, and unchecking the box for "Mount removable media automatically when they are inserted" or "Automatically mount removable media when inserted and on startup."  [https://github.com/iiab/iiab/issues/86 #86]


See: [[#What_can_I_do_with_E-books_and_Internet-in-a-Box?|What can I do with E-books and Internet-in-a-Box?]]<br>
See: [[#What_can_I_do_with_E-books_and_Internet-in-a-Box%3F|What can I do with E-books and Internet-in-a-Box?]]<br>
See: [[#How_do_I_customize_my_Internet-in-a-Box_home_page.3F|How do I customize my Internet-in-a-Box home page?]]<br>
See: [[#How_do_I_customize_my_Internet-in-a-Box_home_page%3F|How do I customize my Internet-in-a-Box home page?]]<br>
See: [[#How_do_I_add_ZIM_files.2C_like_Wikipedia.3F|How do I add ZIM files, like Wikipedia?]]<br>
See: [[#How_do_I_add_ZIM_files.2C_like_Wikipedia%3F|How do I add ZIM files, like Wikipedia?]]<br>
See: [[#KA_Lite_Administration:_What_tips_.26_tricks_exist.3F|KA Lite Administration: What tips & tricks exist?]]<br>
See: [[#KA_Lite_Administration:_What_tips_.26_tricks_exist%3F|KA Lite Administration: What tips & tricks exist?]]<br>
See: [[#WordPress_.26_Moodle_Administration:_What_tips_.26_tricks_exist.3F|WordPress & Moodle Administration: What tips & tricks exist?]]<br>
See: [[#WordPress_.26_Moodle_Administration:_What_tips_.26_tricks_exist%3F|WordPress & Moodle Administration: What tips & tricks exist?]]<br>
See: [[#Can_I_permanently_attach_an_external_USB_drive,_to_add_more_content?|Can I permanently attach an external USB drive, to add more content?]]
See: [[#Can_I_permanently_attach_an_external_USB_drive,_to_add_more_content%3F|Can I permanently attach an external USB drive, to add more content?]]


== Can I buy my own Internet-in-a-Box? ==
== Can I buy my own Internet-in-a-Box? ==
Line 133: Line 154:
A [http://med.iiab.me/s-asia South Asia edition] is also [https://www.thingbits.net/products/medical-and-health-internet-in-a-box-south-asia-edition available in India].
A [http://med.iiab.me/s-asia South Asia edition] is also [https://www.thingbits.net/products/medical-and-health-internet-in-a-box-south-asia-edition available in India].


See: [[#Is_a_quick_installation_possible.3F|Is a quick installation possible?]]<br>
See: [[#Is_a_quick_installation_possible%3F|Is a quick installation possible?]]<br>
See: [[#Where_can_I_see_live_demos_of_Internet-in-a-Box.3F|Where can I see live demos of Internet-in-a-Box?]]<br>
See: [[#Where_can_I_see_live_demos_of_Internet-in-a-Box%3F|Where can I see live demos of Internet-in-a-Box?]]<br>
See: [[#How_do_I_back_up.2C_shrink_.26_copy_IIAB_microSD_cards.3F|How do I back up, shrink & copy IIAB microSD cards?]]<br>
See: [[#How_do_I_back_up.2C_shrink_.26_copy_IIAB_microSD_cards%3F|How do I back up, shrink & copy IIAB microSD cards?]]<br>
See: [[#How_can_I_donate_to_Internet-in-a-Box.3F|How can I donate to Internet-in-a-Box?]]
See: [[#How_can_I_donate_to_Internet-in-a-Box%3F|How can I donate to Internet-in-a-Box?]]


== What hardware should I use? ==
== What hardware should I use? ==
Line 142: Line 163:
Internet-in-a-Box (IIAB) is free and open source software that runs on many GNU/Linux [https://github.com/iiab/iiab/wiki/IIAB-Platforms platforms]:
Internet-in-a-Box (IIAB) is free and open source software that runs on many GNU/Linux [https://github.com/iiab/iiab/wiki/IIAB-Platforms platforms]:


* '''The Raspberry Pi 4 ($35 + parts) and Raspberry Pi 400 ($70 computer in keyboard) are best for classrooms and similar.'''  Their internal WiFi hotspot supports up to 32 student WiFi client devices (but see [https://github.com/iiab/iiab/issues/823 #823] for the very latest driver info!)  The older Raspberry Pi 3 and 3 B+ ($35 + parts) are also possible, despite their 1GB RAM limitation. Finally the Raspberry Pi Zero W ($3.14-to-$10 + parts) can work well as a learning kiosk, despite its meager 512MB RAM (Internet-in-a-Box is used in rural medical clinics, and by families in their homes) noting that the microSD is typically provisioned with IIAB software and Content in an RPi 4 and then later placed inside the RPi Zero W.  (It continues to astonish us how powerful these tiny computers really are, the size of a cigarette lighter yet able to serve 32 students simultaneously, with their powerful built-in Wi-Fi!) RECAP: We strongly recommend the RPi 4 (2+ GB RAM) or RPi 400 (4GB RAM) during production, for DIY implementers building their 1st digital library!
* '''The Raspberry Pi 4 ($35+), Raspberry Pi 5 ($60+) and Raspberry Pi 400 ($70 computer-in-keyboard) are best for classrooms, in almost all cases!'''  Their internal Wi-Fi hotspot supports up to 32 student WiFi client devices (but see [https://github.com/iiab/iiab/issues/823#issuecomment-662285202 #823] for the very latest Wi-Fi firmware info!)  ''RECOMMENDATION: Buy any Raspberry Pi with at least 2 GB RAM, <!--for DIY implementers building their 1st--> especially if your Internet-in-a-Box will include [https://github.com/iiab/iiab/tree/master/roles/kolibri#kolibri-readme Kolibri], [https://docs.moodle.org/311/en/About_Moodle_FAQ Moodle] or [https://github.com/iiab/iiab/tree/master/roles/nextcloud#nextcloud-readme Nextcloud].''
** The older '''Raspberry Pi 3''' and '''3 B+''' ($35+) are also possible, despite their 1GB RAM limitation.
** Finally the '''Raspberry Pi Zero W''' ($10) and '''Raspberry Pi Zero 2 W''' ($15) work great as learning kiosks, despite their meager 512MB RAM (Internet-in-a-Box is used in rural medical clinics, and by families in their homes).  NOTE that your microSD card should be prepared with IIAB software and provisioned with Content in a more powerful Raspberry Pi — then later insert the microSD into your Zero (2) W.  (It continues to astonish us how powerful these tiny computers really are, the size of a cigarette lighter yet able to serve 32 students simultaneously, with their powerful built-in Wi-Fi!)


* '''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 [[#Can_I_create_a_Wi-Fi_hotspot_using_an_old_laptop.3F|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. <!--, making installation more complex than RPi and Mini PCs (whose internal Wi-Fi is generally capable of AP mode, saving the hassles of an external Wi-Fi router are not required in many situations!)  Still, the "spaghetti wiring" of an external router still be worth it, if--> In any case, make sure the laptop has a reasonably new battery, acting as a de facto [https://en.wikipedia.org/wiki/Uninterruptible_power_supply 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.
* '''Refurbished "PC" Laptops & Thin Clients:'''  When recycled / upcycled conscientiously, quality donated laptops and PC's can work extremely well as your Internet-in-a-Box, becoming a "Learning Hotspot" or server for an entire developing world classroom or small school.  If the [[#Can_I_create_a_Wi-Fi_hotspot_using_an_old_laptop%3F|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. <!--, making installation more complex than RPi and Mini PCs (whose internal Wi-Fi is generally capable of AP mode, saving the hassles of an external Wi-Fi router are not required in many situations!)  Still, the "spaghetti wiring" of an external router still be worth it, if--> In any case, make sure the laptop has a reasonably new battery, acting as a de facto [https://en.wikipedia.org/wiki/Uninterruptible_power_supply 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 64-bit 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:
* '''Mini PC's like the ASUS NUC (acquired from Intel in 2023):'''  Avoid classic/desktop PCs whenever possible, as they consume far too much electricity.  However: tough, well-rounded, low-power Mini PCs (such as the NUC) world extremely well, and have proven very effective as school servers in the developing world since 2014.  We prefer Mini PC's models that accept 2.5-inch SATA 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's mentioned above — whose internal Wi-Fi supports 32 simultaneous Wi-Fi client devices!
** The internal Wi-Fi in most NUC computers is regrettably blocked from connecting to more than 12 Wi-Fi client devices.  Compare this to the Raspberry Pi's mentioned above — whose internal Wi-Fi can support 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!
** 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.
** Finally: the NUC is not a fan-less device, but nevertheless has proved very reliable across diverse climates.


* '''Other Mini PC competitors:'''  [https://en.wikipedia.org/wiki/Micro-Star_International MSI] units have proven very solid, and Zotac perhaps less so.  Definitely consider [http://www.gigabyte.us/Mini-PcBarebone 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.  [https://schoolserver.wordpress.com/author/georgejhunt/ 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.''
* '''Other Mini PC competitors:'''  [https://en.wikipedia.org/wiki/Micro-Star_International MSI] units have proven very solid, and Zotac perhaps less so.  Consider also Beelink's NUC clones, and [http://www.gigabyte.us/Mini-PcBarebone Gigabyte BRIX] (e.g. GB-BSI3H-6100) which likewise is almost an exact clone of the NUC.  The BRIX allows internal Wi-Fi to scale beyond the NUC's annoying limitation of 12 connections maximum, if you insert an appropriate Atheros Wi-Fi module (typically < $10) into the BRIX.  [https://schoolserver.wordpress.com/author/georgejhunt/ 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 NUCs since 2015 (5th generation NUCs and onwards) as the NUC's Wi-Fi module is unfortunately soldered in.''
 
* '''ARM Mini PCs:'''  CPUs like [https://www.compulab.com/ TrimSlice / Utilite CompuLab] and [https://solid-run.com 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 lack of 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. -->
 


* '''ARM Mini PCs:''' CPUs like [http://trimslice.com TrimSlice / Utilite] and [http://solid-run.com 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?
MEMORY: Some do fine with 512MB RAM (even in 2023!) 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 2GB or 4GB from an RPi 4 &mdash; or 8GB or more within a Mini PC &mdash; when server-side loads become very intensive. For example if you are running an [https://en.wikipedia.org/wiki/Learning_management_system LMS], experiencing a lot of OpenStreetMap traffic, running a Wikipedia Treasure Hunt with multiple students running full-text searches of Wikipedia &mdash; or offering streaming & fileserver-like capabilities broadly to many students.


* '''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 WOthers do just fine serving dozens of simultaneous video streams from an RPi3 (or 3 B+) with 1GB RAMFinally, certain others require 2GB or 4GB from an RPi 4 &mdash; or 8GB or more within a Mini PC &mdash; when server-side loads become very intensiveFor example if you are running an [https://en.wikipedia.org/wiki/Learning_management_system LMS], experiencing a lot of OpenStreetMap traffic, running a Wikipedia Treasure Hunt with multiple students running full-text searches of Wikipedia &mdash; or offering streaming & fileserver-like capabilities broadly to many students.
STORAGE: While there's increasing movement from hard disks to SSDs and microSD cards every year, many others still swear by tried-and-true hard drivesCertainly rotating media are the clear winner when TB (or multi-terabyte) storage is needed at a low priceIn 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 &mdash; and then narrow in on storage capacity/technologies laterAlternative: consider this earlier discussion of [http://lists.laptop.org/pipermail/server-devel/2013-June/thread.html#6490 external USB hard disks and their possible risks].


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 TB (or multi-terabyte) storage is 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 &mdash; and then narrow in on storage capacity/technologies later.  Alternative: consider this earlier discussion of [http://lists.laptop.org/pipermail/server-devel/2013-June/thread.html#6490 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.''
''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://iiab.io--> http://lists.laptop.org/listinfo/server-devel !


See: [[#What_OS_should_I_use.3F|What OS should I use?]]<br>
Please ask further hardware questions <!-- at https://iiab.io http://lists.laptop.org/listinfo/server-devel or better yet --> on our [[#What_are_the_best_places_for_community_support%3F|community forums]] !
See: [[#Is_a_quick_installation_possible.3F|Is a quick installation possible?]]<br>
 
See: [[#Can_I_create_a_Wi-Fi_hotspot_using_an_old_laptop.3F|Can I create a Wi-Fi hotspot using an old laptop?]]<br>
See: [[#What_OS_should_I_use%3F|What OS should I use?]]<br>
See: [[#Can_I_install_IIAB_onto_a_USB_drive.3F|Can I install IIAB onto a USB drive?]]<br>
See: [[#Is_a_quick_installation_possible%3F|Is a quick installation possible?]]<br>
See: [[#Can_I_create_a_Wi-Fi_hotspot_using_an_old_laptop%3F|Can I create a Wi-Fi hotspot using an old laptop?]]<br>
See: [[#Can_I_install_IIAB_onto_a_USB_drive%3F|Can I install IIAB onto a USB drive?]]<br>
See: [[#What_are_the_best_places_for_community_support%3F|What are the best places for community support?]]


== What OS should I use? ==
== What OS should I use? ==


Our latest OS (Linux distribution) recommendations should always be posted in the [https://github.com/iiab/iiab/wiki/IIAB-Platforms IIAB Platforms] document.
''Check [https://github.com/iiab/iiab/wiki/IIAB-Platforms IIAB Platforms] for the latest Linux OS compatibility details!''
 
<br>


'''Generally the [https://www.raspberrypi.org/software/operating-systems/ 32-bit Raspberry Pi OS] on Raspberry Pi 4 or 400 is best for people getting their feet wet''' &mdash; regardless if you prefer the full/graphical Raspberry Pi OS "with desktop" (includes many amazing desktop apps for learning, with the LXDE-pi desktop/windowing system) &mdash; ''or,'' you might prefer the "Lite" version (which does not include a graphical desktop environment) for a more classic/headless server. '''WARNING: NOOBS IS NOT SUPPORTED, as its partitioning is very different!'''
1) '''[https://www.raspberrypi.com/software/operating-systems/ Raspberry Pi OS]''' on '''Raspberry Pi 4, 5 or 400''' is best if this is your first time &mdash; regardless if you prefer the full/graphical '''Raspberry Pi OS with desktop''' with its great desktop apps for students <!--for learning, with the LXDE-pi desktop/windowing system)--> &mdash; or consider '''Raspberry Pi OS Lite''' for a more lightweight [https://en.wikipedia.org/wiki/Headless_computer "headless"] server:  <!--(which does not include a graphical desktop environment).-->


As of November 2021, 64-bit OS's are ''NOT'' recommended for Raspberry Pi.  However, STRICTLY AT YOUR OWN RISK, here are some experimental options:
* Either way we recommend [https://github.com/iiab/iiab/wiki/IIAB-Platforms#raspios-12 '''64-bit Raspberry Pi OS (Bookworm)'''] (originally released 2023-10-11, [https://github.com/iiab/iiab/issues/3657 #3657]) which is about [https://www.phoronix.com/scan.php?page=article&item=raspberrypi-32bit-64bit&num=1 "48% faster"] (prior to 2022 we recommended 32-bit Raspberry Pi OS, but the [https://www.raspberrypi.com/news/raspberry-pi-os-64-bit/ 64-bit version has since matured]).
* [https://github.com/iiab/iiab/wiki/IIAB-Platforms#operating-systems 64-bit Raspberry Pi OS]
<!-- ** [https://github.com/iiab/iiab/wiki/IIAB-Platforms#raspios-12 Raspberry Pi OS 12 (Bookworm)] should be released in [https://www.raspberrypi.com/products/raspberry-pi-5/#your-questions-answered mid-October 2023], but those comfortable with Debian/Ubuntu and [https://en.wikipedia.org/wiki/APT_(software) apt] can already try it on an experimental basis! -->
<!--* [https://github.com/iiab/iiab/wiki/IIAB-Platforms#operating-systems 64-bit Ubuntu 20.04 LTS]-->
** The NOOBS OS is ''NOT'' supported.
* [https://github.com/iiab/iiab/wiki/IIAB-Platforms#operating-systems 64-bit Ubuntu 21.10 (Impish Indri)] ''(not LTS, Desktop version NOT SUPPORTED on Raspberry Pi 3 and 4, experimental pre-releases!)''
** [https://github.com/iiab/iiab/wiki/IIAB-Platforms#ubuntu-2310 Ubuntu 23.10] can work (originally released 2023-10-12, with [https://wiki.ubuntu.com/Releases#Current end-of-life July 2024]) if you don't mind its very short life span.


'''On PC-like hardware (and virtual machines, containers, etc) we ''DO'' recommend 64-bit OS's:''' (whether or not with [https://en.wikipedia.org/wiki/Long-term_support LTS multi-year support] !)
<br>
* [https://github.com/iiab/iiab/wiki/IIAB-Platforms#operating-systems Ubuntu 21.10 (Impish Indri)] ''(caution, not LTS! experimental pre-releases!)''
 
* [https://github.com/iiab/iiab/wiki/IIAB-Platforms#operating-systems Ubuntu 20.04 LTS] ([https://wiki.ubuntu.com/Releases security updates until April 2025, end-of-life April 2030])
2) '''On PC-like hardware (or virtual machines) pick a 64-bit OS from this list:''' (either with graphical desktop or [https://en.wikipedia.org/wiki/Headless_software "headless"], and whether-or-not with [https://en.wikipedia.org/wiki/Long-term_support LTS multi-year support])
* [https://github.com/iiab/iiab/wiki/IIAB-Platforms#operating-systems Debian 11 "Bullseye"] ([https://wiki.debian.org/LTS security updates until June 2026])
 
* [https://github.com/iiab/iiab/wiki/IIAB-Platforms#linuxmint-21 Linux Mint 21] ([https://www.linuxmint.com/download_all.php security updates until April 2027]) is easy to install with a friendly graphical desktop.
 
* [https://github.com/iiab/iiab/wiki/IIAB-Platforms#ubuntu-2204 Ubuntu 22.04 LTS] ([https://wiki.ubuntu.com/Releases security updates until April 2027, end-of-life April 2032]) is popular on servers. <!-- ''CAUTION: Kolibri, Moodle, PBX and Sugarizer are not yet compatible with Ubuntu 22.04 as of May 2022.'' [https://github.com/iiab/iiab/pull/3189 #3189] -->
** [https://github.com/iiab/iiab/wiki/IIAB-Platforms#ubuntu-2404 Ubuntu 24.04 LTS] pre-releases ([https://wiki.ubuntu.com/Releases#Future end-of-life June 2029]) work well, if you don't yet need Kolibri. [https://github.com/iiab/iiab/issues/3709#issuecomment-1962517952 #3709]
<!-- ** [https://github.com/iiab/iiab/wiki/IIAB-Platforms#ubuntu-2310 Ubuntu 23.10] can work (originally released 2023-10-12, with [https://wiki.ubuntu.com/Releases#Current end-of-life July 2024]) if you don't mind its very short life span. -->
<!-- * [https://github.com/iiab/iiab/wiki/IIAB-Platforms#operating-systems Ubuntu 20.04 LTS] ([https://wiki.ubuntu.com/Releases security updates until April 2025, end-of-life April 2030]) -->
 
* [https://github.com/iiab/iiab/wiki/IIAB-Platforms#debian-12 Debian 12 (Bookworm)] was released 2023-06-10 ([https://wiki.debian.org/LTS security updates until roughly July, 2026 to June, 2028]).  ''CAUTION: Debian Edu (Skolelinux) is [https://github.com/iiab/iiab/issues/2831 not supported].''
<!-- ** [https://github.com/iiab/iiab/wiki/IIAB-Platforms#debian-11 Debian 11 (Bullseye)] ([https://wiki.debian.org/LTS security updates until "roughly July, 2024 to June, 2026"]) is older, but useful if you require [https://github.com/iiab/iiab/tree/master/roles/pbx#readme Asterisk and FreePBX]. -->
<!--''(experimental pre-releases!)''-->
<!--''(experimental pre-releases!)''-->
<!--** [https://github.com/iiab/iiab/wiki/IIAB-Platforms#operating-systems Debian 10 "Buster"] ([https://wiki.debian.org/LTS security updates until June 2024])-->
<!--** [https://github.com/iiab/iiab/wiki/IIAB-Platforms#operating-systems Debian 10 "Buster"] ([https://wiki.debian.org/LTS security updates until June 2024])-->
* [https://github.com/iiab/iiab/wiki/IIAB-Platforms#operating-systems Linux Mint 20] ([https://www.linuxmint.com/download_all.php security updates until April 2025]) is easy to install and has a friendly graphical desktop for newcomers.<!--[https://www.centos.org/download/ CentOS 7] ([https://wiki.centos.org/FAQ/General#What_is_the_support_.27.27end_of_life.27.27_for_each_CentOS_release.3F--><!--http://en.wikipedia.org/wiki/CentOS#End-of-support_schedule--><!-- security updates until June 30, 2024]).--><!--[http://releases.ubuntu.com/16.04/ Ubuntu LTS (64-bit 16.04)] ([https://wiki.ubuntu.com/Releases security updates until April 2021]) which was newly supported as of [[../6.3|IIAB 6.3]].--><!--(*) 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 [[XS_Community_Edition/6.0#Supported_OS.27s|in the past]], deployments often preferred the cutting-edge features provided by a recent version of the [http://en.wikipedia.org/wiki/Fedora_%28operating_system%29 Fedora OS], similar to [[13.2.11|OLPC OS 13.2.11]].-->
<!--[https://www.centos.org/download/ CentOS 7] ([https://wiki.centos.org/FAQ/General#What_is_the_support_.27.27end_of_life.27.27_for_each_CentOS_release%3F--><!--https://en.wikipedia.org/wiki/CentOS#End-of-support_schedule--><!-- security updates until June 30, 2024]).--><!--[https://releases.ubuntu.com/16.04/ Ubuntu LTS (64-bit 16.04)] ([https://wiki.ubuntu.com/Releases security updates until April 2021]) which was newly supported as of [[../6.3|IIAB 6.3]].--><!--(*) 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 [[XS_Community_Edition/6.0#Supported_OS.27s|in the past]], deployments often preferred the cutting-edge features provided by a recent version of the [https://en.wikipedia.org/wiki/Fedora_%28operating_system%29 Fedora OS], similar to [[13.2.11|OLPC OS 13.2.11]].-->
 
<br>
 
Others like Reno McKenzie & Josh Dennis experimented successfully (tweaks required!) with IIAB on the lean & mean [https://DietPi.com DietPi.com] back in 2017.  Similarly, [https://wiki.ubermix.org/index.php?title=Ubermix_Changelog Ubermix 4.1] was successfully [https://github.com/iiab/iiab/wiki/IIAB-Platforms#ubermix-4 tested] in 2019.


Others like Reno McKenzie & Josh Dennis experimented successfully (tweaks required!) with IIAB on the lean & mean http://DietPi.com back in 2017.  Similarly [https://wiki.ubermix.org/index.php?title=Ubermix_Changelog Ubermix 4.1] was successfully [https://github.com/iiab/iiab/wiki/IIAB-Platforms#operatservicesing-systems tested] in 2019.
Please avoid Docker, as our [[#What_is_Ansible_and_what_version_should_I_use%3F|Ansible]] provisioning requires low-level access to the operating system.


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 [[#What_are_the_best_places_for_community_support.3F|mailing lists]], <!--on our http://iiab.io forums--> or contact holt @ unleashkids.org) as you assess the scope-of-work to complete such a job.
Finally, if there are situations where porting to a new OS/distribution will tangibly help schools/libraries/clinics across an entire region, please don't hesitate to [[#What_are_the_best_places_for_community_support%3F|reach out]] <!--(on our [[#What_are_the_best_places_for_community_support%3F|mailing lists]], <!--on our https://iiab.io forums--> <!--or contact holt @ unleashkids.org)--> as you assess the scope-of-work to complete such a job.


See: [[#What_hardware_should_I_use.3F|What hardware should I use?]]<br>
See: [[#What_hardware_should_I_use%3F|What hardware should I use?]]<br>
See: [[#Is_a_quick_installation_possible.3F|Is a quick installation possible?]]<br>
See: [[#Is_a_quick_installation_possible%3F|Is a quick installation possible?]]<br>
See: [[#What_are_the_best_places_for_community_support?|What are the best places for community support?]]
See: [[#What_are_the_best_places_for_community_support%3F|What are the best places for community support?]]


== Is a quick installation possible? ==
== Is a quick installation possible? ==


If you're Ok with an Internet-in-a-Box that might be older, you can download a prefab image for your Raspberry Pi microSD card [https://github.com/iiab/iiab/wiki/Raspberry-Pi-Images:-Summary here].
<!--If you're Ok with an Internet-in-a-Box that might be a bit older, you can download a prefab-->
1. Yes!  Download one of our [https://github.com/iiab/iiab/wiki/Raspberry-Pi-Images-~-Summary#iiab-images-for-raspberry-pi '''IIAB Images for Raspberry Pi'''] to your microSD card.  You can then boot the microSD card in [[#What_hardware_should_I_use%3F|almost any Raspberry Pi]].
 
Clarification: the above IIAB images contain ''software only (you then [[#How_do_I_customize_my_Internet-in-a-Box_home_page%3F|add content]] !)'' and can occasionally be months out-of-date.
 
 
2. If you want the '''very latest''' IIAB software that undergoes continuous improvement and QA, <!--(images can occasionally be months out-of-date)--> we recommend you instead use the 1-line-installer at [https://download.iiab.io '''download.iiab.io'''] and check out IIAB's new [https://github.com/iiab/iiab/wiki/Technical-Contributors-Guide '''Technical Contributors Guide'''].
<!--Otherwise we recommend the '''very latest''' &mdash;-->


Otherwise we recommend the '''very latest''' &mdash; first verifying that your [[#What_hardware_should_I_use.3F|hardware]] and [[#What_OS_should_I_use.3F|Linux OS]] are appropriate: <!--Visual shortcuts to some of the more common installs can then be found at the top-right of http://schoolserver.org = https://wiki.iiab.io (please see https://download.iiab.io and the '''[https://github.com/iiab/iiab/wiki/IIAB-Installation Install Doc]''' for more!)-->  <!-- Images for each platform are accompanied by a '''README page''' with additional instructions.-->  <!-- Yes, please try our XSCE 6.0 RC1 [http://download.unleashkids.org/xsce/downloads/installer/centos/ offline installer] (1.8GB from Nov 19, centos7_xsce.6.rc1.img) --> <!-- http://download.unleashkids.org/xsce/downloads/installer/experimental/centos_150507.img offline installer] (2.4GB) --> <!-- which works on 64-bit Intel NUC x86 PC's, and likely many others?  It includes CentOS 7.1 (1503) as the base OS.  New users please see February 2016's fresh [https://github.com/xsce/xsce/wiki/IIAB-Installation Install Doc] (and [https://github.com/xsce/xsce/blob/master/ReleaseNotes6.0.md DRAFT XSCE 6.0 Release Notes]). --> <!-- In particular, complete XSCE 6.0 images will be published by early March 2016, with instructions in the [https://github.com/xsce/xsce/wiki/IIAB-Installation#take-a-short-cut "short cuts" sections of the Install Doc]. -->
First verify that your [[#What_hardware_should_I_use%3F|hardware]] and [[#What_OS_should_I_use%3F|Linux OS]] are appropriate: <!--Visual shortcuts to some of the more common installs can then be found at the top-right of http://schoolserver.org = https://wiki.iiab.io (please see https://download.iiab.io and the '''[https://github.com/iiab/iiab/wiki/IIAB-Installation Install Doc]''' for more!)-->  <!-- Images for each platform are accompanied by a '''README page''' with additional instructions.-->  <!-- Yes, please try our XSCE 6.0 RC1 [http://download.unleashkids.org/xsce/downloads/installer/centos/ offline installer] (1.8GB from Nov 19, centos7_xsce.6.rc1.img) --> <!-- http://download.unleashkids.org/xsce/downloads/installer/experimental/centos_150507.img offline installer] (2.4GB) --> <!-- which works on 64-bit Intel NUC x86 PC's, and likely many others?  It includes CentOS 7.1 (1503) as the base OS.  New users please see February 2016's fresh [https://github.com/xsce/xsce/wiki/IIAB-Installation Install Doc] (and [https://github.com/xsce/xsce/blob/master/ReleaseNotes6.0.md DRAFT XSCE 6.0 Release Notes]). --> <!-- In particular, complete XSCE 6.0 images will be published by early March 2016, with instructions in the [https://github.com/xsce/xsce/wiki/IIAB-Installation#take-a-short-cut "short cuts" sections of the Install Doc]. -->


* If you're using a Raspberry Pi 4 or 400 (or the older 3 or 3 B+) [https://www.raspberrypi.org/documentation/installation/installing-images/README.md install] the [https://www.raspberrypi.org/software/operating-systems/ official Raspberry Pi OS] ''(do NOT use NOOBS!)''
* If you're using a Raspberry Pi 4 or 400 (or the older 3 or 3 B+) [https://www.raspberrypi.com/documentation/computers/getting-started.html#using-raspberry-pi-imager install] the [https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-64-bit latest 64-bit Raspberry Pi OS] ''(do NOT use NOOBS!)''


* If you're using a PC/Laptop or VM, install a [https://github.com/iiab/iiab/wiki/IIAB-Platforms#operating-systems minimal OS] like Ubuntu 20.04+, Debian 11+ or Linux Mint 20+.
* If you're using a PC/Laptop or VM, install a [https://github.com/iiab/iiab/wiki/IIAB-Platforms#operating-systems minimal OS] like Ubuntu 22.04+, Debian 12+ or Linux Mint 21+.


Then run this <!--[[../7.0|--> [http://download.iiab.io 1-line installer] to install Internet-in-a-Box (IIAB) 7.2's latest pre-release, by typing in: <!--onto [https://www.raspberrypi.org/software/operating-systems/ Raspberry Pi OS] on a $35 Raspberry Pi 3 (or 3 B+) computer, Debian 9 or Ubuntu 18.04, try-->
Then run IIAB's <!--[[../7.0|--> [https://download.iiab.io 1-line installer] to install Internet-in-a-Box (IIAB) 8.0's latest pre-release, by typing in: <!--onto [https://www.raspberrypi.org/software/operating-systems/ Raspberry Pi OS] on a $35 Raspberry Pi 3 (or 3 B+) computer, Debian 9 or Ubuntu 18.04, try-->


<center><big>
<center><big>
   curl [https://d.iiab.io/install.txt d.iiab.io/install.txt] | sudo bash
   curl [https://iiab.io/install.txt iiab.io/install.txt] | bash
</big></center>
</big></center>


This can take an hour or more to complete &mdash; depending whether you choose SMALL-sized (~6 server apps), MEDIUM-sized (~12 server apps) or LARGE-sized (~30 server apps) as the installer begins.  ''Use our [[#What_services_.28IIAB_apps.29_are_suggested_during_installation.3F|comparison table]] below, to decide which is most suitable for your needs.''
This can take an hour or more to complete &mdash; depending whether you choose SMALL-sized (~10 server apps), MEDIUM-sized (~16 server apps) or LARGE-sized (~30 server apps) as the installer begins.  ''Use our [[#What_services_.28IIAB_apps.29_are_suggested_during_installation%3F|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!'''
 
While a lot has changed since 2019, consider also the "ZERO to IIAB" installation video on our [https://www.youtube.com/channel/UC0cBGCxr_WPBPa3IqPVEe3g YouTube channel].  <!-- to get familiar with important offline learning ideas.-->
 
Remember: IIAB's 1-line installer might need you to run <code>sudo iiab</code> multiple times, before IIAB's software install fully completes &mdash; e.g. if Internet connectivity is interrupted for any reason.  When your IIAB software install is 100% complete, you'll be asked to reboot &mdash; typically within about-an-hour-or-so (so you can begin [[#How_do_I_customize_my_Internet-in-a-Box_home_page%3F|installing content!]])


'''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!'''  While a lot has changed since 2019, we still encourage you to watch the "ZERO to IIAB" installation video on our [https://www.youtube.com/channel/UC0cBGCxr_WPBPa3IqPVEe3g YouTube channel] to get familiar with important offline learning ideas.


Remember: IIAB's 1-line installer might need you to run <code>sudo iiab</code> multiple times, before IIAB's software install fully completes &mdash; e.g. if Internet connectivity is interrupted for any reason.  When that's done and your IIAB software install is 100% complete, you'll be asked to reboot &mdash; typically within about-an-hour-or-so.  (Such that you can begin [[#How_do_I_customize_my_Internet-in-a-Box_home_page.3F|installing content!]])
3. Linux hackers: [https://github.com/iiab/iiab/wiki/IIAB-Platforms other distros] might be possible, but can require extensive babysitting to get right.  Consider the long-form [https://github.com/iiab/iiab/wiki/IIAB-Installation#do-everything-from-scratch "Do Everything from Scratch"] install instructions if porting IIAB to a new Linux distribution is your goal.


Linux hackers please note that [https://github.com/iiab/iiab/wiki/IIAB-Platforms other Linux OS's] might be possible, but can require extensive babysitting to get right, so consider the long-form [https://github.com/iiab/iiab/wiki/IIAB-Installation#do-everything-from-scratch "Do Everything from Scratch"] install instructions if porting IIAB to a new Linux distribution is your goal.  Noting that when booting your PC, traditional [https://en.wikipedia.org/wiki/Master_boot_record MBR] is preferred, but [https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface UEFI] can also work (as set in your PC/server's BIOS) if your [[#What_OS_should_I_use.3F|Linux distribution]] supports that.
<!--Noting that when booting your PC, traditional [https://en.wikipedia.org/wiki/Master_boot_record MBR] is preferred, but [https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface UEFI] can also work (as set in your PC/server's BIOS) if your [[#What_OS_should_I_use%3F|Linux distribution]] supports that.


Beware that [https://github.com/iiab/iiab/wiki/IIAB-Platforms#disk-partitioning partitioning is critical] particularly with distros like CentOS that attempt to allocate all extra/surplus space to <code>/home</code> by default (this won't work, as gigabytes of content need to be placed in <code>/library</code> instead!)  Avoid enabling LVM partitioning, especially if you'll later be needing Clonezilla to duplicate the disk.
Beware that [https://github.com/iiab/iiab/wiki/IIAB-Platforms#disk-partitioning partitioning is critical] particularly with distros like CentOS that attempt to allocate all extra/surplus space to <code>/home</code> by default (this won't work, as gigabytes of content need to be placed in <code>/library</code> instead!)  Avoid enabling LVM partitioning, especially if you'll later be needing Clonezilla to duplicate the disk.


''Finally, If you get completely stuck, capture a screenshot (take a photo if copying & pasting is not possible) then [[#What_are_the_best_places_for_community_support.3F|get in touch]] so volunteers can help you work it out.''
''Finally, If you get completely stuck, capture a screenshot (take a photo if copying & pasting is not possible) then [[#What_are_the_best_places_for_community_support%3F|get in touch]] so volunteers can help.''
 
 
'''No matter which of the 3 ways you chose (above) to install IIAB software, that should now be complete.  <!--it's time to get down to real business (education!)  There are a variety of ways to-->  <!--So it's now time to [https://github.com/iiab/iiab/wiki/IIAB-Installation#add-content add content] to your Internet-in-a-Box (IIAB) server, as [[#How_do_I_customize_my_Internet-in-a-Box_home_page%3F|outlined below]] — tailoring it to your community/library or clinic's precise needs!-->


'''Once the IIAB software is installed, <!--it's time to get down to real business (education!)  There are a variety of ways to--> it's time to [https://github.com/iiab/iiab/wiki/IIAB-Installation#add-content add content] to your Internet-in-a-Box (IIAB) server, as [[#How_do_I_customize_my_Internet-in-a-Box_home_page.3F|outlined below]], tailoring it to your community/library or clinic's precise needs!<!--Please watch the HOW-TO videos on Internet-in-a-Box's [https://www.youtube.com/channel/UC0cBGCxr_WPBPa3IqPVEe3g YouTube channel] (several available as [http://d.iiab.io/content/videos .mp4 and .WebMD]) to get up to speed with downloading & installing content to your IIAB!'''
<!--Please watch the HOW-TO videos on Internet-in-a-Box's [https://www.youtube.com/channel/UC0cBGCxr_WPBPa3IqPVEe3g YouTube channel] (several available as [https://download.iiab.io/content/videos .mp4 and .WebMD]) to get up to speed with downloading & installing content to your IIAB!'''


Specifically, please explore the materials on your server's home page (http://box or http://box.lan) and get to know the Admin Console (http://box/admin or http://box.lan/admin, with [[#What_are_the_default_passwords.3F|default password]] below) which permits you to (1) configure your server and (2) download new content.  Example screenshots: (stale graphics from 2015, but that's the idea!)
Specifically, please explore the materials on your server's home page (http://box or http://box.lan) and get to know the Admin Console (http://box/admin or http://box.lan/admin, with [[#What_are_the_default_passwords%3F|default password]] below) which permits you to (1) configure your server and (2) download new content.  Example screenshots: (stale graphics from 2015, but that's the idea!)
* [http://ibin.co/2BDiyiJ9rAxS Main Menu]
* [http://ibin.co/2BDiyiJ9rAxS Main Menu]
* [http://ibin.co/2BDjTw3m4xB1 Install Kiwix ZIM Files]
* [http://ibin.co/2BDjTw3m4xB1 Install Kiwix ZIM Files]
Line 234: Line 291:
* [http://ibin.co/2BDkGKTWvR0K Display Job Status]
* [http://ibin.co/2BDkGKTWvR0K Display Job Status]


Finally, to arrange an elegant portal/home page (typically http://box) for all your students or users to explore, organize your chosen Content Packs and IIAB Apps using the [https://github.com/iiab/iiab/wiki/IIAB-Menuing Dynamic Menuing] system.  '''[[#How_do_I_customize_my_Internet-in-a-Box_home_page.3F|This is explained below]]''', allowing you to prototype and rapidly revise/iterate your portal/home page's presentation, tailoring it to your community/library or clinic's precise needs!-->  <!--Legacy Install Techniques, many of which are deprecated as they long predate 2018, just for the record: Tom Gilliard's [http://wiki.sugarlabs.org/go/XSCE 6.0 Installation Notes & Screenshots] and [[XS_Community_Edition/6.0/Tony's_install_recipe|Tony Anderson's XSCE 6.0 Install Recipe]].  [https://ca.linkedin.com/pub/jerry-vonau/5b/905/627 Jerry Vonau] and others have demonstrated that UEFI support out-of-the-box may in fact be possible in future.  Detailed install instructions for the older [[XS_Community_Edition/5.1|XSCE 5.1]] can still be [https://docs.google.com/document/d/1Ez1H2LYrkqeXR_r5T93CMdmx9CeTJp_vC-IDBGam1Bc/edit#heading=h.raunf6lwahje found here].-->  <!-- https://docs.google.com/document/d/1Ez1H2LYrkqeXR_r5T93CMdmx9CeTJp_vC-IDBGam1Bc/edit#heading=h.eob20jsspchj -->  <!--New offline install images will appear for many of the most common hardware platforms, like Raspberry Pi 3 (or 3 B+), [http://tinyurl.com/iiabimages starting April 2017].  Looking back, [https://schoolserver.wordpress.com/author/georgejhunt/ George Hunt] and others have worked extremely hard on these, and greatly appreciate all your [http://iiab.io "fieldback"] !-->
Finally, to arrange an elegant portal/home page (typically http://box) for all your students or users to explore, organize your chosen Content Packs and IIAB Apps using the [https://github.com/iiab/iiab/wiki/IIAB-Menuing Dynamic Menuing] system.  '''[[#How_do_I_customize_my_Internet-in-a-Box_home_page%3F|This is explained below]]''', allowing you to prototype and rapidly revise/iterate your portal/home page's presentation, tailoring it to your community/library or clinic's precise needs!-->  <!--Legacy Install Techniques, many of which are deprecated as they long predate 2018, just for the record: Tom Gilliard's [https://wiki.sugarlabs.org/go/XSCE 6.0 Installation Notes & Screenshots] and [[XS_Community_Edition/6.0/Tony's_install_recipe|Tony Anderson's XSCE 6.0 Install Recipe]].  [https://ca.linkedin.com/pub/jerry-vonau/5b/905/627 Jerry Vonau] and others have demonstrated that UEFI support out-of-the-box may in fact be possible in future.  Detailed install instructions for the older [[XS_Community_Edition/5.1|XSCE 5.1]] can still be [https://docs.google.com/document/d/1Ez1H2LYrkqeXR_r5T93CMdmx9CeTJp_vC-IDBGam1Bc/edit#heading=h.raunf6lwahje found here].-->  <!-- https://docs.google.com/document/d/1Ez1H2LYrkqeXR_r5T93CMdmx9CeTJp_vC-IDBGam1Bc/edit#heading=h.eob20jsspchj -->  <!--New offline install images will appear for many of the most common hardware platforms, like Raspberry Pi 3 (or 3 B+), [https://tinyurl.com/iiabimages starting April 2017].  Looking back, [https://schoolserver.wordpress.com/author/georgejhunt/ George Hunt] and others have worked extremely hard on these, and greatly appreciate all your [https://iiab.io "fieldback"] !-->


See: [[#Can_I_buy_my_own_Internet-in-a-Box.3F|Can I buy my own Internet-in-a-Box?]]<br>
See: [[#Can_I_buy_my_own_Internet-in-a-Box%3F|Can I buy my own Internet-in-a-Box?]]<br>
See: [[#What_hardware_should_I_use.3F|What hardware should I use?]]<br>
See: [[#What_hardware_should_I_use%3F|What hardware should I use?]]<br>
See: [[#What_OS_should_I_use.3F|What OS should I use?]]<br>
See: [[#What_OS_should_I_use%3F|What OS should I use?]]<br>
See: [[#What_technical_documentation_exists.3F|What technical documentation exists?]]<br>
See: [[#What_technical_documentation_exists%3F|What technical documentation exists?]]<br>
See: [[#What_are_the_default_passwords.3F|What are the default passwords?]]<br>
See: [[#What_are_the_default_passwords%3F|What are the default passwords?]]<br>
See: [[#How_do_I_customize_my_Internet-in-a-Box_home_page.3F|How do I customize my Internet-in-a-Box home page?]]<br>
See: [[#How_do_I_customize_my_Internet-in-a-Box_home_page%3F|How do I customize my Internet-in-a-Box home page?]]<br>
See: [[#Can_I_create_a_Wi-Fi_hotspot_using_an_old_laptop.3F|Can I create a Wi-Fi hotspot using an old laptop?]]<br>
See: [[#Can_I_create_a_Wi-Fi_hotspot_using_an_old_laptop%3F|Can I create a Wi-Fi hotspot using an old laptop?]]<br>
See: [[#How_do_I_back_up.2C_shrink_.26_copy_IIAB_microSD_cards.3F|How do I back up, shrink & copy IIAB microSD cards?]]<br>
See: [[#How_do_I_back_up.2C_shrink_.26_copy_IIAB_microSD_cards%3F|How do I back up, shrink & copy IIAB microSD cards?]]<br>
See: [[#What_are_the_best_places_for_community_support?|What are the best places for community support?]]<br>
See: [[#What_are_the_best_places_for_community_support%3F|What are the best places for community support?]]<br>
See: [[#Can_I_install_IIAB_onto_a_USB_drive.3F|Can I install IIAB onto a USB drive?]]<br>
See: [[#Can_I_install_IIAB_onto_a_USB_drive%3F|Can I install IIAB onto a USB drive?]]<br>


== What services (IIAB apps) are suggested during installation? ==
== What services (IIAB apps) are suggested during installation? ==
Line 253: Line 310:
Which services (IIAB apps) are included in each of these 3?  The summary table below helps you choose among IIAB's almost 40 powerful apps — optionally with a complete LMS (learning management system) like Kolibri, Moodle, WordPress, Sugarizer or Nextcloud.
Which services (IIAB apps) are included in each of these 3?  The summary table below helps you choose among IIAB's almost 40 powerful apps — optionally with a complete LMS (learning management system) like Kolibri, Moodle, WordPress, Sugarizer or Nextcloud.


Then, after choosing among these 3 sizes, IIAB's installer encourages you to further refine your choice of IIAB apps — by customizing your very own [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|/etc/iiab/local_vars.yml]]
Then, after choosing among these 3 sizes, IIAB's installer encourages you to further refine your choice of IIAB apps — by customizing your very own [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|/etc/iiab/local_vars.yml]]


{| class="wikitable" style="text-align: center;"
{| class="wikitable" style="text-align: center;"
! SMALL
! [https://github.com/iiab/iiab/blob/master/vars/local_vars_small.yml SMALL]
! MEDIUM
! [https://github.com/iiab/iiab/blob/master/vars/local_vars_medium.yml MEDIUM]
! LARGE
! [https://github.com/iiab/iiab/blob/master/vars/local_vars_large.yml LARGE]
! IIAB APP URL
! IIAB APP URL
! DOCS
! DOCS
Line 264: Line 321:
|-
|-
| X || X || X || box/awstats || [https://awstats.sourceforge.io/ AWStats]
| X || X || X || box/awstats || [https://awstats.sourceforge.io/ AWStats]
| style="text-align:left;" | 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.
| style="text-align:left;" | 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. See Also: Matomo
|-
|-
| X || X || X || box:8008 || [https://github.com/iiab/iiab/tree/master/roles/kalite#ka-lite-readme KA Lite]
| X || X || X || box/books box/libros box/livres || [https://github.com/iiab/iiab/tree/master/roles/calibre-web#readme Calibre-Web]
<br>
[https://www.youtube.com/watch?v=iTJQktIg4sY&t=72s (Video Tips)]
| style="text-align:left;" | Calibre-Web is a web app for organizing E-Books into bookshelves.  You can begin your community library with an existing [https://calibre-ebook.com/whats-new Calibre] database.
|-
| X || X || X || box:8008 || [https://github.com/iiab/iiab/tree/master/roles/kalite#readme KA Lite]
<br>
[https://www.youtube.com/watch?v=hopq0lq-qu4 (Video Tips)]
| style="text-align:left;" | 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.
| style="text-align:left;" | 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 || [https://github.com/iiab/iiab/tree/master/roles/kiwix#kiwix-readme Kiwix]
| X || X || X || box/kiwix || [https://github.com/iiab/iiab/tree/master/roles/kiwix#readme Kiwix]
| style="text-align:left;" | Kiwix is a free and open-source offline web engine created by Emmanuel Engelhart and Renaud Gaudin in 2007.
| style="text-align:left;" | Kiwix is a free and open-source offline web engine created by Emmanuel Engelhart and Renaud Gaudin in 2007.
|-
|-
| X || X || X || box/maps || [[#How_do_I_add_zoomable_maps_for_my_region.3F|OpenStreetMap]]
| X || X || X || box/matomo || [https://github.com/iiab/iiab/blob/master/roles/matomo#readme Matomo]
<br>
[https://matomo.org/faq/videos/video-welcome-to-matomo/ (Video Tips)]
| style="text-align:left;" | Matomo is a web analytics alternative to Google Analytics, emphasizing privacy and data ownership.  See Also: AWStats
|-
| X || X || X || box/maps || [[#How_do_I_add_zoomable_maps_for_my_region%3F|OpenStreetMap]]
<br>
[https://www.youtube.com/watch?v=Ir-3K0pjwOI (Video Tips)]
| style="text-align:left;" | 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 includes 10+ zoom levels of satellite imagery!
| style="text-align:left;" | 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 includes 10+ zoom levels of satellite imagery!
|-
|-
| X || X || X || box/usb || [https://github.com/iiab/iiab/tree/master/roles/usb_lib#usb_lib-readme USB_LIB]
| X || X || X || box/usb || [https://github.com/iiab/iiab/tree/master/roles/usb_lib#readme USB_LIB]
| style="text-align:left;" | Content from USB sticks/drives, that teachers can [[#Can_teachers_display_their_own_content.3F|insert anytime]].
| style="text-align:left;" | Content from USB sticks/drives, that teachers can [[#Can_teachers_display_their_own_content%3F|insert anytime]].
|-
|-
| I || I || I || (none) || [https://github.com/iiab/iiab/tree/master/roles/bluetooth#bluetooth-readme Bluetooth]
| I || I || I || (none) || [https://github.com/iiab/iiab/tree/master/roles/bluetooth#readme Bluetooth]
| style="text-align:left;" | Bluetooth access to IIAB's Admin Console, for IIAB field operators/administrators and advanced teachers too. Provides two services, pan (or Personal Area Network) and term (terminal emulation) &mdash; installed (I) but not enabled. Works on Raspberry Pi only.
| style="text-align:left;" | Bluetooth access to IIAB's Admin Console, for IIAB field operators/administrators and advanced teachers too. Provides two services, pan (or Personal Area Network) and term (terminal emulation) &mdash; installed (I) but not enabled. Works on Raspberry Pi only.
|-
|-
| I || I || I || (none) || [[#Captive_Portal_Administration:_What_tips_.26_tricks_exist.3F|Captive Portal]]
| I || I || I || (none) || [[#Captive_Portal_Administration:_What_tips_.26_tricks_exist%3F|Captive Portal]]
| style="text-align:left;" | Captive Portal attempts to help people who get frustrated typing in http://box.lan onto their phone, tablet or laptop &mdash; attempting to open their browser for them, to display Internet-in-a-Box automatically  &mdash; installed (I) but not enabled. [https://github.com/iiab/iiab/issues/1182 #1182]
| style="text-align:left;" | Captive Portal attempts to help people who get frustrated typing in http://box.lan onto their phone, tablet or laptop &mdash; attempting to open their browser for them, to display Internet-in-a-Box automatically  &mdash; installed (I) but not enabled. [https://github.com/iiab/iiab/issues/1182 #1182]
|-
|-
| I || I || I || (none) || [[#How_can_I_remotely_manage_my_Internet-in-a-Box.3F|OpenVPN]]
| I || I || I || (none) || [[#How_can_I_remotely_manage_my_Internet-in-a-Box%3F|OpenVPN]]
| style="text-align:left;" | 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 &mdash; installed (I) but not enabled.
| style="text-align:left;" | 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 &mdash; installed (I) but not enabled.
|-
|-
| I || I || I || (none) || [https://github.com/iiab/iiab/tree/master/roles/remoteit#remote-support-of-an-internet-in-a-box-using-httpsremoteit remote.it]
| I || I || I || (none) || [https://github.com/iiab/iiab/tree/master/roles/remoteit#readme remote.it]
| style="text-align:left;" | https://remote.it can help you remotely maintain an IIAB.  Some benefits include: crossing multiple NATs/firewalls using a single TCP port, without requiring router port forwarding, and reducing your network's vulnerability.  &mdash; installed (I) but not enabled.
| style="text-align:left;" | https://remote.it can help you remotely maintain an IIAB.  Some benefits include: crossing multiple NATs/firewalls using a single TCP port, without requiring router port forwarding, and reducing your network's vulnerability.  &mdash; installed (I) but not enabled.
|-
|-
| || X || X || box/books box/libros box/livres || [https://github.com/iiab/iiab/tree/master/roles/calibre-web#calibre-web-readme Calibre-Web]
| || X || X || box/kolibri || [https://github.com/iiab/iiab/tree/master/roles/kolibri#readme Kolibri]
| style="text-align:left;" | Calibre-Web is a web app providing a clean interface for browsing, reading and downloading E-books using an existing Calibre database.
<br>
<!--[https://www.youtube.com/watch?v=YOBgx_rvebI (Video Tips)]-->
[https://www.youtube.com/watch?v=ynFwMoJ3jeI (Video Tips)]
| style="text-align:left;" | Kolibri (might replace KA Lite in future!) provides offline access to a wide range of quality, openly licensed educational content.  Supports <!--[https://kolibri-studio.readthedocs.io/ Kolibri Studio]--> Kolibri Studio so online teachers can quickly remix & redistribute innovative lesson plans.
|-
|-
| || X || X || box/nextcloud || [https://github.com/iiab/iiab/blob/master/roles/nextcloud/README.md#nextcloud-readme Nextcloud]
| || X || X || box/nextcloud || [https://github.com/iiab/iiab/blob/master/roles/nextcloud#readme Nextcloud]
<br>
[https://www.youtube.com/watch?v=I8GtygCoNcY (Video Tips)]
| style="text-align:left;" | Nextcloud puts your data at your fingertips, under your control.  Store your documents, calendar, contacts and photos on your local server.
| style="text-align:left;" | 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 || [https://sugarizer.org Sugarizer]
| || X || X || box/sugarizer || [https://sugarizer.org Sugarizer]
| style="text-align:left;" | A taste of Sugar on any device, used every day by children around the world connected with the One Laptop per Child project.  Does not run on Debian 10, due to MongoDB requirement: [https://github.com/iiab/iiab/issues/1437 #1437]
<br>
[https://try.sugarizer.org (Live Demo)]
| style="text-align:left;" | Program or be programmed!  Explore creativity puzzles originally from MIT's One Laptop Per Child global project.  ''(64-BIT ONLY)''
|-
|-
| || X || X || box:9091 || [https://github.com/iiab/iiab/tree/master/roles/transmission#transmission-readme Transmission]
| || X || X || box:9091 || [https://github.com/iiab/iiab/tree/master/roles/transmission#readme Transmission]
| style="text-align:left;" | Transmission is a BitTorrent client (software) that helps you auto-download KA Lite (Khan Academy) videos and similar.
| style="text-align:left;" | Transmission is a BitTorrent client (software) that helps you auto-download KA Lite (Khan Academy) videos and similar. ''(COMPILING TRANSMISSION 4.0.4+ TAKES AN HOUR AS OF OCTOBER 2023; TRANSMISSION 4.1+ SHOULD FIX THAT IN 2024)''
|-
|-
| || X || X || box/wordpress || [https://wordpress.org/ WordPress]
| || X || X || box/wordpress || [https://wordpress.org/ WordPress]
<br>
[https://www.youtube.com/watch?v=kYY88h5J86A (Video Tips)]
| style="text-align:left;" | 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.<!--and online stores.-->
| style="text-align:left;" | 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.<!--and online stores.-->
|-
|-
| || || X || box/print or localhost:631 || [https://github.com/iiab/iiab/tree/master/roles/cups#cups-printing-readme CUPS]
| || || X || box/print or localhost:631 || [https://github.com/iiab/iiab/tree/master/roles/cups#readme CUPS]
| style="text-align:left;" | CUPS is a modular printing system for Unix-like computer operating systems which allows a computer to act as a print server.
| style="text-align:left;" | CUPS is a modular printing system for Unix-like computer operating systems which allows a computer to act as a print server.
|-
|-
Line 311: Line 391:
| style="text-align:left;" | Gitea is a lightweight self-hosted Git service similar to GitHub.com, and written in Go.
| style="text-align:left;" | Gitea is a lightweight self-hosted Git service similar to GitHub.com, and written in Go.
|-
|-
| || || X || box:4244 or box/archive ? || [https://github.com/iiab/iiab/tree/master/roles/internetarchive#offline-internet-archive-readme Internet Archive]
| || || X || box:4244 or box/archive ? || [https://github.com/iiab/iiab/tree/master/roles/internetarchive#readme Internet Archive]
| style="text-align:left;" | The Internet Archive is famous for their Wayback Machine that keeps a copy of 400+ 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
| style="text-align:left;" | The Internet Archive is famous for their Wayback Machine that keeps a copy of 600+ 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 ''(64-BIT ONLY)''
|-
|-
| || || X || box/jupyterhub || [https://github.com/iiab/iiab/tree/master/roles/jupyterhub#jupyterhub-programming-environment-with-student-notebooks JupyterHub]
| || || X || box/jupyterhub || [https://github.com/iiab/iiab/tree/master/roles/jupyterhub#readme JupyterHub]
<br>
[https://www.youtube.com/watch?v=Mk6ZHVIw0Xs (Video Tips)]
| style="text-align:left;" | High Schools may want to consider JupyterHub to integrate coding with dynamic interactive graphing — A New Way to Think About Programming — allowing students to integrate science experiment results and program output within their notebook/document/blog.
| style="text-align:left;" | High Schools may want to consider JupyterHub to integrate coding with dynamic interactive graphing — A New Way to Think About Programming — allowing students to integrate science experiment results and program output within their notebook/document/blog.
|-
| || || X || box/kolibri || [https://github.com/iiab/iiab/tree/master/roles/kolibri#kolibri-readme Kolibri]
| style="text-align:left;" | Kolibri (might replace KA Lite in future!) provides offline access to a wide range of quality, openly licensed educational content.  Supports <!--[https://kolibri-studio.readthedocs.io/ Kolibri Studio]--> Kolibri Studio so online teachers can quickly remix & redistribute innovative lesson plans.
|-
| || || X || box/lokole || [https://github.com/iiab/iiab/tree/master/roles/lokole#lokole-readme Lokole]
| style="text-align:left;" | Lokole is an Email service that works offline for rural communities, students and teachers.  With a 3G/4G modem, you can arrange to batch-upload / batch-download emails once per night &mdash; for almost no cost at all &mdash; depending on mobile data plans in your country.
|-
|-
| || || X || box/wiki <- box/mediawiki || [https://www.mediawiki.org/wiki/MediaWiki MediaWiki]
| || || X || box/wiki <- box/mediawiki || [https://www.mediawiki.org/wiki/MediaWiki MediaWiki]
| style="text-align:left;" | 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.
| style="text-align:left;" | 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) || [https://github.com/iiab/iiab/tree/master/roles/minetest#minetest-readme Minetest]
| || || X || (none) || [https://github.com/iiab/iiab/tree/master/roles/minetest#readme Minetest]
<br>
[https://www.youtube.com/watch?v=c7D3aK-8rew (Video Tips)]
| style="text-align:left;" | 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.
| style="text-align:left;" | 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/moodle || [https://docs.moodle.org/311/en/About_Moodle_FAQ Moodle]
| || || X || box/moodle || [https://docs.moodle.org/311/en/About_Moodle_FAQ Moodle]
| style="text-align:left;" | 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''
<br>
[https://www.youtube.com/watch?v=oJ3qwBaQsOk (Video Tips)]
| style="text-align:left;" | 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.
|-
|-
| || || X || (none) || [https://github.com/iiab/iiab/tree/master/roles/mosquitto#mosquitto-readme Mosquitto]
| || || X || (none) || [https://github.com/iiab/iiab/tree/master/roles/mosquitto#readme Mosquitto]
| style="text-align:left;" | 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
| style="text-align:left;" | 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/munin || [http://munin-monitoring.org/ Munin]
| || || X || box/munin || [https://munin-monitoring.org/ Munin]
| style="text-align:left;" | 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.
| style="text-align:left;" | 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 || box/nodered || [https://github.com/iiab/iiab/tree/master/roles/nodered#node-red-readme Node-RED]
| || || X || box/nodered || [https://github.com/iiab/iiab/tree/master/roles/nodered#readme Node-RED]
<br>
[https://www.youtube.com/watch?v=GeN7g4bdHiM (Video Tips)]
| style="text-align:left;" | Node-RED enables electronics projects with a flow-based development tool for visual programming, originally developed by IBM for wiring together hardware devices, APIs and online services as part of the Internet of Things (IoT).  "Low-code programming for event-driven applications."  See also: Mosquitto
| style="text-align:left;" | Node-RED enables electronics projects with a flow-based development tool for visual programming, originally developed by IBM for wiring together hardware devices, APIs and online services as part of the Internet of Things (IoT).  "Low-code programming for event-driven applications."  See also: Mosquitto
|-
|-
Line 345: Line 427:
|-
|-
| || || I || box/phpmyadmin ? || [https://www.phpmyadmin.net/ phpMyAdmin]
| || || I || box/phpmyadmin ? || [https://www.phpmyadmin.net/ phpMyAdmin]
| style="text-align:left;" | phpMyAdmin is a free and open source administration tool for MySQL and MariaDB &mdash; installed (I) but not enabled in [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|LARGE]].
| style="text-align:left;" | phpMyAdmin is a free and open source administration tool for MySQL and MariaDB &mdash; installed (I) but not enabled in [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|LARGE]].
|-
|-
| || || I || (none) || [https://github.com/iiab/iiab/tree/master/roles/samba#samba-readme Samba]
| || || I || (none) || [https://github.com/iiab/iiab/tree/master/roles/samba#readme Samba]
| style="text-align:left;" | Samba is the standard Windows interoperability suite of programs for Linux and Unix &mdash; installed (I) but not enabled in [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|LARGE]].
| style="text-align:left;" | Samba is the standard Windows interoperability suite of programs for Linux and Unix &mdash; installed (I) but not enabled in [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|LARGE]].
|-
|-
| || || || box:10080 || [https://github.com/iiab/iiab/tree/master/roles/azuracast#azuracast-readme AzuraCast]
| || || || box:12080 || [https://github.com/iiab/iiab/tree/master/roles/azuracast#readme AzuraCast]
| style="text-align:left;" | AzuraCast is a self-hosted, all-in-one radio station platform.  Use AzuraCast to schedule podcasts, music, and even do live streaming of audio contentA variety of streaming formats are supported.  Requires Ubuntu or Debian for now.  PR [https://github.com/iiab/iiab/pull/1733 #1733]
<br>
[https://www.youtube.com/watch?v=b1Rxlu5P804 (Video Tips)]
| style="text-align:left;" | AzuraCast is simple, self-hosted web radio.  Use it to schedule student newscasts, podcasts, music (e.g. MP3's and similar) and even do live-streaming.  ''(64-BIT ONLY; 4+ GB RAM RECOMMENDED)''
|-
|-
| || || || box:8080 || [https://calibre-ebook.com/about Calibre]
| || || || box:8080 || [https://calibre-ebook.com/about Calibre]
| style="text-align:left;" | 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''
<br>
[https://www.youtube.com/watch?v=fAVpwmeZoZE (Video Tips)]
| style="text-align:left;" | 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.  ''(VERY SLOW INSTALL)''
|-
|-
| || || || box:8081 box/stream ? || [https://github.com/eka-foundation/cham Cham]
| || || || box:8081 box/stream ? || [https://github.com/eka-foundation/cham Cham]
Line 360: Line 446:
|-
|-
| || || || box/dokuwiki ''(deprecated, Jan 2020)'' || [https://github.com/iiab/iiab/tree/master/roles/0-DEPRECATED-ROLES/dokuwiki#dokuwiki-readme DokuWiki]
| || || || box/dokuwiki ''(deprecated, Jan 2020)'' || [https://github.com/iiab/iiab/tree/master/roles/0-DEPRECATED-ROLES/dokuwiki#dokuwiki-readme DokuWiki]
| style="text-align:left;" | 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.
| style="text-align:left;" | DokuWiki was written in PHP, to work on plain text files (and thus not need a database).  Novel design, but it never caught on, and was poorly maintained.
|-
|-
| || || || box/elgg ''(deprecated, August 2021)'' || [https://github.com/iiab/iiab/tree/master/roles/0-DEPRECATED-ROLES/elgg#elgg-readme Elgg]
| || || || box/elgg ''(deprecated, August 2021)'' || [https://github.com/iiab/iiab/tree/master/roles/0-DEPRECATED-ROLES/elgg#elgg-readme Elgg]
| style="text-align:left;" | Elgg is a social networking engine used by offline schools to create a collaborative environment.  Includes basic blogging, microblogging, file sharing, networking and groups.
| style="text-align:left;" | Elgg is (was) a social networking engine used by offline schools to create a collaborative environment.  Includes basic blogging, microblogging, file sharing, networking and groups.
|-
|-
| || || || (none) ''(deprecated, 2019)'' || [https://en.wikipedia.org/wiki/Ejabberd ejabberd]
| || || || (none) ''(deprecated, 2019)'' || [https://en.wikipedia.org/wiki/Ejabberd ejabberd]
| style="text-align:left;" | ejabberd is a free and open source instant messaging server.
| style="text-align:left;" | ejabberd is a free and open source instant messaging server.
|-
| || || || box/lokole || [https://github.com/iiab/iiab/tree/master/roles/lokole#lokole-readme Lokole]
| style="text-align:left;" | Lokole is an Email service that works offline for rural communities, students and teachers.  With a 3G/4G modem, you can arrange to batch-upload / batch-download emails once per night &mdash; for almost no cost at all &mdash; depending on mobile data plans in your country.
|-
|-
| || || || box:2812 ? || [https://mmonit.com/monit/ Monit]
| || || || box:2812 ? || [https://mmonit.com/monit/ Monit]
| style="text-align:left;" | Monit is a process supervision tool.  With Monit, system status can be viewed directly from the command line, or via the native HTTP web serverDoes not run on Debian 10: [https://github.com/iiab/iiab/issues/1849 #1849]
| style="text-align:left;" | Monit is a process supervision tool.  View system status from the command line, or browserArguably no longer necessary, as a result of systemd: [https://github.com/iiab/iiab/issues/1849 #1849]
|-
|-
| || || || box:83/freepbx (Apache) box/freepbx (NGINX) || [https://github.com/iiab/iiab/tree/master/roles/pbx#pbx-readme PBX]
| || || || box:83/freepbx (Apache) box/freepbx (NGINX) || [https://github.com/iiab/iiab/tree/master/roles/pbx#readme PBX]
| style="text-align:left;" | 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''
| style="text-align:left;" | 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).  ''(VERY SLOW INSTALL)''
|-
|-
| || || || (none) || [http://www.squid-cache.org/ Squid]
| || || || (none) || [https://www.squid-cache.org/ Squid]
| style="text-align:left;" | Squid is a proxy server that can be helpful for caching and bandwidth shaping, but can be challenging to configure.
| style="text-align:left;" | Squid is a proxy server that can be helpful for caching and bandwidth shaping, as well as basic allowlist/denylist URL filtering.  See IIAB's sample [https://github.com/iiab/iiab/blob/master/roles/network/templates/squid/squid.conf.j2 /etc/squid/squid.conf]
|}
|}


See: [[#What_can_I_do_with_E-books_and_Internet-in-a-Box.3F|What can I do with E-books and Internet-in-a-Box?]]<br>
See: [[#What_can_I_do_with_E-books_and_Internet-in-a-Box%3F|What can I do with E-books and Internet-in-a-Box?]]<br>
See: [[#Is_a_quick_installation_possible.3F|Is a quick installation possible?]]<br>
See: [[#Is_a_quick_installation_possible%3F|Is a quick installation possible?]]<br>
See: [[#How_do_I_customize_my_Internet-in-a-Box_home_page.3F|How do I customize my Internet-in-a-Box home page?]]<br>
See: [[#How_do_I_customize_my_Internet-in-a-Box_home_page%3F|How do I customize my Internet-in-a-Box home page?]]<br>
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|What is local_vars.yml and how do I customize it?]]<br>
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|What is local_vars.yml and how do I customize it?]]<br>
See: [[#Can_I_upgrade_or_reinstall_server_apps.3F|Can I upgrade or reinstall server apps?]]
See: [[#Can_I_upgrade_or_reinstall_server_apps%3F|Can I upgrade or reinstall server apps?]]


== What technical documentation exists? ==
== What technical documentation exists? ==
Line 388: Line 477:
'''[https://github.com/iiab/iiab/wiki IIAB Tech Docs]''' explain the infrastructure that makes Internet-in-a-Box possible.<!--'''[https://github.com/iiab/iiab/wiki/IIAB-Installation IIAB Installation]''' document, and--><!--focusing on the '''[https://github.com/iiab/iiab/wiki/IIAB-Installation#take-a-short-cut "Take a Short Cut"]''' section!-->
'''[https://github.com/iiab/iiab/wiki IIAB Tech Docs]''' explain the infrastructure that makes Internet-in-a-Box possible.<!--'''[https://github.com/iiab/iiab/wiki/IIAB-Installation IIAB Installation]''' document, and--><!--focusing on the '''[https://github.com/iiab/iiab/wiki/IIAB-Installation#take-a-short-cut "Take a Short Cut"]''' section!-->


Living Docs are ever-evolving as technical progress is rapid, so please also search this very document ('''[http://FAQ.IIAB.IO FAQ.IIAB.IO]''') and consider <!--bookmark our http://IIAB.io community forums and--> monitoring the very latest [https://github.com/iiab/iiab/pulls?q=is%3Apr+is%3Amerged GitHub code merges].
Living Docs are ever-evolving as technical progress is rapid, so please scan this entire document ('''[https://wiki.iiab.io/go/FAQ FAQ.IIAB.IO]''') and consider <!--bookmark our https://IIAB.io community forums and--> monitoring the [https://github.com/iiab/iiab/pulls?q=is%3Apr+is%3Amerged latest code merges].
 
Developers can also consider our [https://github.com/iiab/iiab/wiki/IIAB-Contributors-Guide IIAB Contributors Guide], first published in October 2017.


More generally, see our [http://iiab.net/info/videos/ Tech Skills Videos] ([http://iiab.net/videos/ alternate view]) focusing on networking, Raspberry Pi, web basics, and security — with sub-titles in English, Spanish and French.  Some of which are also on [https://www.youtube.com/channel/UC0cBGCxr_WPBPa3IqPVEe3g YouTube]. <!-- HOW-TO videos -->
Developers can also consider our [https://github.com/iiab/iiab/wiki/Technical-Contributors-Guide Technical Contributors Guide], first published in October 2017, and overhauled in late 2021.


'''Offline Field Operators should also check our growing collection of Internet-in-a-Box technical support docs (and eventually videos!) available ''on your very own Internet-in-a-Box'' at http://box/info'''
More generally, see our [http://iiab.net/info/videos/ Tech Skills Videos] ([http://iiab.net/videos/ alternate view]) focused on networking, Raspberry Pi, web basics, and security — with subtitles in English, Spanish and French.  Some of which are also on [https://www.youtube.com/channel/UC0cBGCxr_WPBPa3IqPVEe3g IIAB's YouTube channel]. <!-- HOW-TO videos -->


Finally, you can force your IIAB to update these tech support docs, to include any/all recent changes, if you run [https://github.com/iiab/iiab/blob/master/roles/www_base/templates/iiab-refresh-wiki-docs.sh /usr/bin/iiab-refresh-wiki-docs] while online. <!-- opt/iiab/iiab/roles/www_base/templates/refresh-wiki-docs.sh (based on the pandoc document converter). -->
'''Offline Field Operators should also check our growing collection of Internet-in-a-Box tech support docs (and eventually videos!) available ''on your very own Internet-in-a-Box'' at http://box/info'''


Finally you can force your IIAB to update these offline docs (when your IIAB is online) by running: [https://github.com/iiab/iiab/blob/master/roles/www_base/templates/iiab-refresh-wiki-docs.sh /usr/bin/iiab-refresh-wiki-docs] <!-- opt/iiab/iiab/roles/www_base/templates/refresh-wiki-docs.sh (based on the pandoc document converter). -->
<!--
<hr>
<hr>


Line 406: Line 495:
The earlier [https://docs.google.com/document/d/1Ez1H2LYrkqeXR_r5T93CMdmx9CeTJp_vC-IDBGam1Bc XSCE 5.1 + Internet-in-a-Box Install Doc for Intel NUC] from 2015 can sometimes be very useful for larger hardware implementers.
The earlier [https://docs.google.com/document/d/1Ez1H2LYrkqeXR_r5T93CMdmx9CeTJp_vC-IDBGam1Bc 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
Also see George Hunt's foundational collection of XSCE (School Server Community Edition) docs from 2012-2015 at https://schoolserver.wordpress.com


Finally, <!--[https://twitter.com/m_anish--> Anish Mangal hopes to formally write up his [https://drive.google.com/drive/folders/0B2qGKOFYikSuT0dGRWZNWlVLUmM deployment recommendations / 8-part training materials] based on his experiences setting up IIAB/XSCE in [http://bhagmalpur.wordpress.com/ Northern India], while http://unleashkids.org with http://kidsoncomputers.org document the human experience around Haiti/Mexico deployments and beyond.
Finally, --> <!--[https://twitter.com/m_anish--> <!-- Anish Mangal hopes to formally write up his [https://drive.google.com/drive/folders/0B2qGKOFYikSuT0dGRWZNWlVLUmM deployment recommendations / 8-part training materials] based on his experiences setting up IIAB/XSCE in [https://bhagmalpur.wordpress.com/ Northern India], while https://unleashkids.org with https://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!
Please suggest improvements to this FAQ where you can, and check back to reread at a later date, Thank You! -->


See: [[#What_security_tips_exist?|What security tips exist?]]<br>
See: [[#What_security_tips_exist%3F|What security tips exist?]]<br>
See: [[#How_can_I_remotely_manage_my_Internet-in-a-Box.3F|How can I remotely manage my Internet-in-a-Box?]]<br>
See: [[#How_can_I_remotely_manage_my_Internet-in-a-Box%3F|How can I remotely manage my Internet-in-a-Box?]]<br>
See: [[#What_are_the_best_places_for_community_support?|What are the best places for community support?]]<br>
See: [[#What_are_the_best_places_for_community_support%3F|What are the best places for community support?]]<br>
See: [[#How_can_I_help.3F|How can I help?]]
See: [[#How_can_I_help%3F|How can I help?]]


== What is Ansible and what version should I use? ==
== What is Ansible and what version should I use? ==


[https://en.wikipedia.org/wiki/Ansible_(software) Ansible] is software that orchestrates the installation of Internet-in-a-Box (IIAB) and its component apps/services.
[https://en.wikipedia.org/wiki/Ansible_(software) Ansible] is software that [https://github.com/iiab/iiab/wiki/Technical-Contributors-Guide#female_detective-understanding-ansible orchestrates the installation of Internet-in-a-Box (IIAB)] and its [[#What_services_(IIAB_apps)_are_suggested_during_installation%3F|apps/services]].
 
FYI the latest Ansible version recommendation is posted near [https://github.com/iiab/iiab/blob/master/scripts/ansible#L11 Line 11 of scripts/ansible]. <!--(ansible-core 2.11.3+ is recommended as of 2021-07-19, but note this recommendation is upgraded frequently as Ansible evolves!)-->


If you need to upgrade Ansible, make sure your IIAB is online, and then run the following:
If you must upgrade Ansible, make sure your IIAB is online, and then run:


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
  cd /opt/iiab/iiab
  cd /opt/iiab/iiab
sudo git pull    # HIGH RISK IF YOUR IIAB IS OLDER
  sudo scripts/ansible</syntaxhighlight>
  sudo scripts/ansible</syntaxhighlight>
<!-- sudo git pull    # THIS LINE HIGH RISK IF YOUR IIAB IS OLDER -->


Done!  (It will explain how to verify your Ansible installation.)
Done!  (It will explain how to verify your Ansible installation.)


FYI the latest Ansible version recommendation is posted near [https://github.com/iiab/iiab/blob/master/scripts/ansible#L11 Line 11 of scripts/ansible]. <!--(ansible-core 2.11.3+ is recommended as of 2021-07-19, but note this recommendation is upgraded frequently as Ansible evolves!)-->
Finally if your IIAB is much older, upgrading Ansible can be challenging (And At Your Own Risk). But if you must: (run as root, when your IIAB is online)
 
Upgrading Ansible can be challenging on older IIAB's (and at your own risk!)  But if you must, below are recommendations to run as root or using sudo, if your IIAB is online:


# Run "ansible --version" to see what version of Ansible you might already have installed &mdash; make sure you don't have an old/troublesome version of Ansible installed!
# Run <code>ansible --version</code> to see what version of Ansible is installed.
# Remove all prior versions of Ansible using "apt purge ansible-core" (or "apt purge ansible-base" or "apt purge ansible" or "pip3 uninstall ansible-core" or "pip3 uninstall ansible-base" or "pip3 uninstall ansible") depending on how Ansible was originally installed &mdash; if necessary see [https://github.com/iiab/iiab/issues/564#issuecomment-347264985 #564]
# Remove all prior versions of Ansible using <code>apt purge ansible-core</code> (or <code>apt purge ansible-base</code> or <code>apt purge ansible</code> or <code>pip3 uninstall ansible-core</code> or <code>pip3 uninstall ansible-base</code> or <code>pip3 uninstall ansible</code>) depending on how Ansible was originally installed &mdash; if necessary see [https://github.com/iiab/iiab/issues/564#issuecomment-347264985 #564]
# Remove any and all lines containing "ansible" from /etc/apt/sources.list and the files in /etc/apt/sources.list.d/
# Remove any and all lines containing "ansible" from /etc/apt/sources.list and the files in /etc/apt/sources.list.d/
# Run the above-mentioned script, by typing "cd /opt/iiab/iiab" then "sudo scripts/ansible"
# Once again try to run <code>cd /opt/iiab/iiab</code> then <code>sudo scripts/ansible</code>
# Run "ansible --version" and/or "pip3 show ansible-core" <!--and/or "apt -a list ansible-core"--> to verify (on rare occasions you might first need to log out and log back in, if Ansible ends up being moved e.g. from /usr/bin to /usr/local/bin or vice versa)
# Run <code>ansible --version</code> and/or <code>pip3 show ansible-core</code> <!--and/or "apt -a list ansible-core"--> to verify (on rare occasion you might first need to log out and log back in, if Ansible ends up being moved, e.g. from /usr/bin to /usr/local/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: https://download.iiab.io (which installs Ansible for you!)''
''CLARIF: None of the above should be required if you're doing a fresh install on a clean OS, using IIAB's 1-line installer from: https://download.iiab.io (which installs Ansible for you!)''


PRO TIP: For those wanting to run a single Ansible playbook or role, run <code>./runrole <ROLE NAME></code> (see runrole's [https://github.com/iiab/iiab/blob/master/runrole source code]).<!--(prior to Ansible 2.5 arriving in March 2018, this was known as <code>./runtags</code>).-->
PRO TIP: IIAB's [https://github.com/iiab/iiab/blob/master/scripts/ansible Ansible install script] attempts to upgrade ~4 Ansible Collections as well.  See the line that begins with: [https://github.com/iiab/iiab/blob/31d7733b703f6220a59f678547085691dc9bdfc6/scripts/ansible#L199-L202 <code>ansible-galaxy collection install --force-with-deps</code>]
 
<!-- PRO TIP: For more of the nitty-gritty on how IIAB installs the most recent Ansible and associated python3-* apt packages, see also: https://github.com/iiab/iiab/blob/master/scripts/ansible.md -->
PRO TIP: Read https://github.com/iiab/iiab/wiki/IIAB-Contributors-Guide#ansible to learn more about how IIAB uses Ansible.


PRO TIP: IIAB's [https://github.com/iiab/iiab/blob/master/scripts/ansible Ansible install script] attempts to upgrade Ansible Collections as well. See the line near the bottom of the script, that begins with: <code>ansible-galaxy collection install --force-with-deps</code>
PRO TIP: For those wanting to run a single Ansible playbook or role, run <code>cd /opt/iiab/iiab</code> then <code>sudo ./runrole <ROLE NAME></code> (see runrole's [https://github.com/iiab/iiab/blob/master/runrole source code]).<!--(prior to Ansible 2.5 arriving in March 2018, this was known as <code>./runtags</code>).-->
<!-- PRO TIP: For more of the nitty-gritty on how IIAB installs the most recent Ansible and associated python3-* apt packages, see also: https://github.com/iiab/iiab/blob/master/scripts/ansible.md -->
<!-- PRO TIP: Read https://github.com/iiab/iiab/wiki/Technical-Contributors-Guide#understanding-ansible to learn more about how IIAB uses Ansible. -->


See: [[#Is_a_quick_installation_possible.3F|Is a quick installation possible?]]<br>
See: [[#Is_a_quick_installation_possible%3F|Is a quick installation possible?]]<br>
See: [[#What_technical_documentation_exists.3F|What technical documentation exists?]]
See: [[#What_services_(IIAB_apps)_are_suggested_during_installation%3F|What services (IIAB apps) are suggested during installation?]]<br>
See: [[#What_technical_documentation_exists%3F|What technical documentation exists?]]


== My Android device says "Connected, no Internet" and won't browse http://box ==
== My Android device says "Connected, no Internet" and won't browse http://box ==
Line 460: Line 549:
## '''When it asks "This network has no Internet access. Stay connected?" be sure to tap "Yes" !'''
## '''When it asks "This network has no Internet access. Stay connected?" be sure to tap "Yes" !'''
## 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.
## 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.
# Recent Samsung, Huawei smartphones (since about 2019) generally require to you to '''Turn Off "Mobile Data"''' before you can browse to http://box, http://box.lan or http://172.18.96.1
# ''Recent Samsung and Huawei smartphones (since about 2019) require to you to '''Turn Off "Mobile Data"''' before you can browse to http://box, http://box.lan or http://10.10.10.10 (or http://172.18.96.1 if your Internet-in-a-Box pre-dates July 2022)''


See: [[#Captive_Portal_Administration:_What_tips_.26_tricks_exist.3F|Captive Portal Administration: What tips & tricks exist?]]
See: [[#Captive_Portal_Administration:_What_tips_.26_tricks_exist%3F|Captive Portal Administration: What tips & tricks exist?]]


== What are the default passwords? ==
== What are the default passwords? ==


For [[#What_can_I_do_with_E-books_and_Internet-in-a-Box.3F|KA Lite, Kolibri, Calibre, Calibre-Web, Nextcloud, Moodle, CUPS, Elgg, JupyterHub, Transmission, etc]] the administrative user is '''Admin''' (don't forget the capital A) and the default/initial password is: '''changeme''' &mdash; WordPress as well, often uses this same account.  For MediaWiki however, Admin/changeme2020 is the initial username/password.
For [[#What_can_I_do_with_E-books_and_Internet-in-a-Box%3F|KA Lite, Kolibri, Calibre, Calibre-Web, Nextcloud, Moodle, CUPS, Elgg, JupyterHub, Transmission, etc]] the administrative user is '''Admin''' (don't forget the capital A) and the default/initial password is: '''changeme''' &mdash; WordPress as well, often uses this same account.  For MediaWiki however, Admin/changeme2020 is the initial username/password.


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
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


However 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.
However for IIAB's own '''Admin Console'''[*] at http://box/admin, http://box.lan/admin or http://10.10.10.10/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.


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


<u>If your OS is Raspberry Pi OS: also change the password for user "pi" from "raspberry" before connecting to the Internet.</u> At the command line, type "passwd pi".  Starting with [http://tinyurl.com/iiabimages 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 [http://unix.stackexchange.com/questions/252016/difference-between-vs-vs-in-etc-shadow password fields to * (the asterisk character)] within /etc/shadow.  This prevents direct ssh access to such accounts.
<u>If your OS is Raspberry Pi OS: also change the password for user "pi" from "raspberry" before connecting to the Internet.</u> At the command line, type "passwd pi".  Starting with [https://tinyurl.com/iiabimages 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 [https://unix.stackexchange.com/questions/252016/difference-between-vs-vs-in-etc-shadow 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 -".
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 -i".


''[*] 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, 3 B+ or 4, depending what changes you've requested!)''
''[*] 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, 3 B+ or 4, depending what changes you've requested!)''


Finally, certain install-time passwords are listed in [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|/etc/iiab/local_vars.yml]] which overrides passwords listed in [https://github.com/iiab/iiab/wiki/IIAB-Architecture#detailed-description-of-ansible-control-variables 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!  2020-09-23 Warning: MySQL/MariaDB passwords cannot easily be changed after IIAB install ([https://github.com/iiab/iiab/issues/2542 #2542]).
Finally, certain install-time passwords are listed in [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|/etc/iiab/local_vars.yml]] which overrides passwords listed in [https://github.com/iiab/iiab/wiki/IIAB-Architecture#detailed-description-of-ansible-control-variables 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!  2020-09-23 Warning: MySQL/MariaDB passwords cannot easily be changed after IIAB install ([https://github.com/iiab/iiab/issues/2542 #2542]).


<i>'''Admin Console:''' Please note that "systemctl restart iiab-cmdsrv.service" is sometimes necessary when http://box.lan/admin shows red errors upon login.</i>
'''Admin Console:''' Note that very occasionally it might be necessary to run <code>systemctl restart iiab-cmdsrv.service</code> if http://box.lan/admin shows red errors upon login.


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


See: [[#What_can_I_do_with_E-books_and_Internet-in-a-Box.3F|What can I do with E-books and Internet-in-a-Box?]]<br>
See: [[#What_can_I_do_with_E-books_and_Internet-in-a-Box%3F|What can I do with E-books and Internet-in-a-Box?]]<br>
See: [[#What_technical_documentation_exists.3F|What technical documentation exists?]]<br>
See: [[#What_technical_documentation_exists%3F|What technical documentation exists?]]<br>
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|What is local_vars.yml and how do I customize it?]]<br>
See: [[#Can_I_password_protect_the_Wi-Fi_hotspot%3F|Can I password protect the Wi-Fi hotspot?]]<br>
See: [[#What_security_tips_exist?|What security tips exist?]]<br>
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|What is local_vars.yml and how do I customize it?]]<br>
See: [[#How_can_I_remotely_manage_my_Internet-in-a-Box.3F|How can I remotely manage my Internet-in-a-Box?]]<br>
See: [[#What_security_tips_exist%3F|What security tips exist?]]<br>
See: [[#KA_Lite_Administration:_What_tips_.26_tricks_exist.3F|KA Lite Administration: What tips & tricks exist?]]<br>
See: [[#How_can_I_remotely_manage_my_Internet-in-a-Box%3F|How can I remotely manage my Internet-in-a-Box?]]<br>
See: [[#What_are_the_best_places_for_community_support?|What are the best places for community support?]]
See: [[#KA_Lite_Administration:_What_tips_.26_tricks_exist%3F|KA Lite Administration: What tips & tricks exist?]]<br>
See: [[#What_are_the_best_places_for_community_support%3F|What are the best places for community support?]]


== Where can I see live demos of Internet-in-a-Box? ==
== Where can I see live demos of Internet-in-a-Box? ==
Line 498: Line 588:
Please see these [http://med.iiab.me live demo examples] as used by medical clinics in 2018, hosted by the Wikimedia Foundation (Wikipedia).
Please see these [http://med.iiab.me live demo examples] as used by medical clinics in 2018, hosted by the Wikimedia Foundation (Wikipedia).


Many more examples from schools in [http://iiab.me/jamaica Jamaica], [http://iiab.me/mexico Mexico], <!--[http://iiab.me/peru Peru], [http://iiab.me/ghana Ghana], [http://iiab.me/nigeria Nigeria]--> and other places around the world, will be posted.  Here is a [http://med.iiab.me/s-asia/ South Asia Medical Version] including more than 30 languages.  Please [[#What_are_the_best_places_for_community_support.3F|contact us]] if you:
Many more examples from schools in [http://iiab.me/jamaica/ Jamaica], [http://iiab.me/mexico/ Mexico], [http://iiab.me/haiti/ Haiti] <!--[http://iiab.me/peru/ Peru], [http://iiab.me/ghana/ Ghana], [http://iiab.me/nigeria/ Nigeria]--> and other places around the world, will be posted.  Here is a [http://med.iiab.me/s-asia/ South Asia Medical Version] including more than 30 languages.  Please [[#What_are_the_best_places_for_community_support%3F|contact us]] if you:


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


See: [[#Can_I_buy_my_own_Internet-in-a-Box.3F|Can I buy my own Internet-in-a-Box?]]<br>
See: [[#Can_I_buy_my_own_Internet-in-a-Box%3F|Can I buy my own Internet-in-a-Box?]]<br>
See: [[#Is_a_quick_installation_possible.3F|Is a quick installation possible?]]<br>
See: [[#Is_a_quick_installation_possible%3F|Is a quick installation possible?]]<br>
See: [[#How_do_I_customize_my_Internet-in-a-Box_home_page.3F|How do I customize my Internet-in-a-Box home page?]]
See: [[#How_do_I_customize_my_Internet-in-a-Box_home_page%3F|How do I customize my Internet-in-a-Box home page?]]


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


<!--Starting April 2017, our install images often included sample content to more quickly springboard implementers into content curation, as outlined within [http://tinyurl.com/iiabimages Guidelines for Creating IIAB Images incl Sample Content Packs].-->
<!--Starting April 2017, our install images often included sample content to more quickly springboard implementers into content curation, as outlined within [https://tinyurl.com/iiabimages Guidelines for Creating IIAB Images incl Sample Content Packs].-->
''OPTIONAL: The 2019 videos on Internet-in-a-Box's [https://www.youtube.com/channel/UC0cBGCxr_WPBPa3IqPVEe3g YouTube channel] (several available as [http://d.iiab.io/content/videos .mp4 and .webm]) are a bit out-of-date, but can illustrate the big picture, showing how to get moving downloading and arranging content on your Internet-in-a-Box (IIAB).''
''OPTIONAL: Some 2019 videos on Internet-in-a-Box's [https://www.youtube.com/channel/UC0cBGCxr_WPBPa3IqPVEe3g YouTube channel] (several available as [https://download.iiab.io/content/videos .mp4 and .webm]) are a bit out-of-date, but can illustrate the big picture, showing how 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.  If you've just installed Internet-in-a-IIAB (IIAB) on your home network, here are some [https://github.com/iiab/iiab-factory/blob/f37bfd994bd9b4cc2c12470736e7ee3cc6f41380/iiab#L502-L534 great tricks] to [https://www.raspberrypi.com/documentation/computers/remote-access.html#ip-address find its IP Address].
Your IIAB home page is usually reachable at http://box, http://box.lan or http://10.10.10.10 from any nearby smartphone, tablet or laptop/computer.  If you've just installed Internet-in-a-Box (IIAB) on your home network, here are some [https://github.com/iiab/iiab-factory/blob/f37bfd994bd9b4cc2c12470736e7ee3cc6f41380/iiab#L502-L534 great tricks] to [https://www.raspberrypi.com/documentation/computers/remote-access.html#ip-address find its IP Address].


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


# [https://github.com/iiab/iiab/wiki/IIAB-Installation#add-content 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 [[#What_are_the_default_passwords.3F|default password]] above:
# [https://github.com/iiab/iiab/wiki/IIAB-Installation#add-content 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 [[#What_are_the_default_passwords%3F|default password]] above:
## Click the [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/InstContent.rst Install Content] tab, then explore [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/InstContent.rst#get-zim-files-from-kiwix Get ZIM Files from Kiwix] and [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/InstContent.rst#get-oer2gorachel-modules Get OER2Go(RACHEL) Modules] on the left.
## Click the [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/InstContent.rst Install Content] tab, then explore [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/InstContent.rst#get-zim-files-from-kiwix Get ZIM Files from Kiwix] and [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/InstContent.rst#get-oer2gorachel-modules Get OER2Go(RACHEL) Modules] on the left.
## If instead you want to load content from a USB drive, click [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/InstContent.rst#manage-content Manage Content] on the left.
## If instead you want to load content from a USB drive, click [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/InstContent.rst#manage-content Manage Content] on the left.
## 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 [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/Utilities.rst Utilities] tab -> Display Job Status &mdash; until all are marked as "SUCCEEDED" in the Status column.''
## 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 [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/Utilities.rst Utilities] tab -> Display Job Status &mdash; until all are marked as "SUCCEEDED" in the Status column.''
<!--## Check the Install Content [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/InstContent.rst Help] page for late-breaking tips.-->
<!--## Check the Install Content [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/InstContent.rst Help] page for late-breaking tips.-->
# Rearrange / re-order your menu items (the Content Packs and [[#What_services_.28IIAB_apps.29_are_suggested_during_installation.3F|IIAB Apps]] on your IIAB home page) including those that were added just above:
# Rearrange / re-order your menu items (the Content Packs and [[#What_services_.28IIAB_apps.29_are_suggested_during_installation%3F|IIAB Apps]] on your IIAB home page) including those that were added just above:
## Easy Way - use the drag-and-drop interface within Admin Console (http://box.lan/admin) -> [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/ContentMenus.rst Content Menus] tab -> [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/ContentMenus.rst#edit-content-menus Edit Content Menus] -> Content Item List.  You may need the "Load Menu", "Save Menu" and "Select Languages" buttons.<!--, as outlined on the Content Menus [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/ContentMenus.rst Help] page.-->
## Easy Way - use the drag-and-drop interface within Admin Console (http://box.lan/admin) -> [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/ContentMenus.rst Content Menus] tab -> [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/ContentMenus.rst#edit-content-menus Edit Content Menus] -> Content Item List.  You may need the "Load Menu", "Save Menu" and "Select Languages" buttons.<!--, as outlined on the Content Menus [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/ContentMenus.rst Help] page.-->
## Or Manually - rearrange the order of menu items by editing the <code>menu_items_1</code> array in [https://github.com/iiab/iiab-admin-console/blob/master/roles/js-menu/files/menu.json /library/www/html/home/menu.json].
## Or Manually - rearrange the order of menu items by editing the <code>menu_items_1</code> array in [https://github.com/iiab/iiab-admin-console/blob/master/roles/js-menu/files/menu.json /library/www/html/home/menu.json].
# If you need to change the description or logo for any particular menu item:
# If you need to change the description or logo for any particular menu item:
## Change its description by editing the menu item's <code>.json</code> and/or <code>.html</code> files within [https://github.com/iiab/iiab-admin-console/tree/master/roles/js-menu/files/menu-files/menu-defs /library/www/html/js-menu/menu-files/menu-defs] (e.g. to change the description of [http://oer2go.org/viewmod/en-practical_action Practical Action], edit <code>en-practical_action.json</code> and/or <code>en-practical_action.html</code>).
## Change its description by editing the menu item's <code>.json</code> and/or <code>.html</code> files within [https://github.com/iiab/iiab-admin-console/tree/master/roles/js-menu/files/menu-files/menu-defs /library/www/html/js-menu/menu-files/menu-defs] (e.g. to change the description of [https://rachel.worldpossible.org/viewmod/en-practical_action Practical Action], edit <code>en-practical_action.json</code> and/or <code>en-practical_action.html</code>).
## Change its logo by placing a new logo file in [https://github.com/iiab/iiab-admin-console/tree/master/roles/js-menu/files/menu-files/images /library/www/html/js-menu/menu-files/images], making sure that <code>logo_url</code> is set to the correct logo filename (in its above-mentioned <code>.json</code> file).
## Change its logo by placing a new logo file in [https://github.com/iiab/iiab-admin-console/tree/master/roles/js-menu/files/menu-files/images /library/www/html/js-menu/menu-files/images], making sure that <code>logo_url</code> is set to the correct logo filename (in its above-mentioned <code>.json</code> file).
# Finally, to showcase your school logo or community colors broadly on your Internet-in-a-Box home page, <!--on your http://box--> <!--server's--> <!--home page,--> <!--/ landing page / start page / launch page / navigation page / portal--> <!--(what users see at http://box or http://box.lan)--> you can customize [https://github.com/iiab/iiab-admin-console/blob/master/roles/js-menu/files/index.html /library/www/html/home/index.html] and the CSS files in [https://github.com/iiab/iiab-admin-console/tree/master/roles/js-menu/files/menu-files/css /library/www/html/js-menu/menu-files/css].<!--/var/www/html/xs-portal/index.en.php--><!--, where most standard HTML tags should work.--><!--  Please create a backup copy of your ongoing index.html beautifications regularly!-->  ''WARNING: editing the index.html page and css files can easily have unintended consequences. For this type of customization, you should consider using [[#WordPress_.26_Moodle_Administration:_What_tips_.26_tricks_exist.3F|WordPress]] (summarized just below).''
# Finally, to showcase your school logo or community colors broadly on your Internet-in-a-Box home page, <!--on your http://box--> <!--server's--> <!--home page,--> <!--/ landing page / start page / launch page / navigation page / portal--> <!--(what users see at http://box or http://box.lan)--> you can customize [https://github.com/iiab/iiab-admin-console/blob/master/roles/js-menu/files/index.html /library/www/html/home/index.html] and the CSS files in [https://github.com/iiab/iiab-admin-console/tree/master/roles/js-menu/files/menu-files/css /library/www/html/js-menu/menu-files/css].<!--/var/www/html/xs-portal/index.en.php--><!--, where most standard HTML tags should work.--><!--  Please create a backup copy of your ongoing index.html beautifications regularly!-->  ''WARNING: editing the index.html page and css files can easily have unintended consequences. For this type of customization, you should consider using [[#WordPress_.26_Moodle_Administration:_What_tips_.26_tricks_exist%3F|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!'''
'''Notice: clearing the browser's cache (e.g. Ctrl-Shift-Delete) is sometimes necessary after making any of the above changes!'''


<!--Finally, technical tips are contained in our older [https://github.com/xsce/xsce/blob/master/roles/portal/README.rst Portal README].-->
<!--Finally, technical tips are contained in our older [https://github.com/xsce/xsce/blob/master/roles/portal/README.rst Portal README].-->
''If you get completely stuck, capture a screenshot (take a photo if copying & pasting is not possible) then [[#What_are_the_best_places_for_community_support.3F|get in touch]] so volunteers can help you work it out.'' <!--If you need further customization suggestions and tips, don't hesitate to--> <!--post to our http://iiab.io forums and/or--> <!--write to: https://groups.google.com/group/unleashkids !-->
''If you get completely stuck, capture a screenshot (take a photo if copying & pasting is not possible) then [[#What_are_the_best_places_for_community_support%3F|get in touch]] so volunteers can help you work it out.'' <!--If you need further customization suggestions and tips, don't hesitate to--> <!--post to our https://iiab.io forums and/or--> <!--write to: https://groups.google.com/group/unleashkids !-->


'''How This All Works:''' [https://github.com/iiab/iiab/wiki/IIAB-Menuing Dynamic Menuing] was originally introduced by IIAB/XSCE 6.1, to reduce front-end hand-coding of HTML, <!--introduced an alternative approach for those wanting less hand-coding, that (as a bonus)--> by auto-adjusting all http://SERVERNAMES:PORTS links on-the-fly (using browser-side Javascript).  <!--, for maximum deployment flexibility.--> <!--To enable this on your server, please--> More advanced usages are also now possible, if you read about [https://github.com/iiab/iiab/wiki/IIAB-Menuing#menu-item-definitions Menu Item Definitions] and [https://github.com/iiab/iiab/wiki/IIAB-Menuing#html-fragments HTML Fragments] &mdash; taking note of the latest [https://github.com/iiab/iiab/wiki/IIAB-Menuing#2019-additions 2019 additions].
'''How This All Works:''' Please see Admin Console's [https://github.com/iiab/iiab-admin-console/tree/master/docs 5 technical overview docs] (NEW, as of 2022!)  [https://github.com/iiab/iiab/wiki/IIAB-Menuing Dynamic Menuing] was originally introduced by IIAB/XSCE 6.1, to reduce front-end hand-coding of HTML, <!--introduced an alternative approach for those wanting less hand-coding, that (as a bonus)--> by auto-adjusting all http://SERVERNAMES:PORTS links on-the-fly (using browser-side Javascript).  <!--, for maximum deployment flexibility.--> <!--To enable this on your server, please--> More advanced usages are also now possible, if you read about [https://github.com/iiab/iiab/wiki/IIAB-Menuing#menu-item-definitions Menu Item Definitions] and [https://github.com/iiab/iiab/wiki/IIAB-Menuing#html-fragments HTML Fragments] &mdash; taking note of the latest [https://github.com/iiab/iiab/wiki/IIAB-Menuing#2019-additions 2019 additions].


'''Alternatives:''' <!--Likewise as many educators want quick customizations on their portal/menuing beyond the logo,--> Some prefer <!--may consider experimental WYSIWYG tools--> a completely different front-end for their Internet-in-a-Box home page, e.g. [[#WordPress_.26_Moodle_Administration:_What_tips_.26_tricks_exist.3F|WordPress]] (with this possible [https://github.com/kananigit/iiab-menu-plugin IIAB plugin]), or DokuWiki, or even Moodle etc.  <!--For example you might lay out your content in an indigenous language, linking to content gems truly relevant to locals.-->  Several of these can be enabled in your IIAB's Admin Console (http://box/admin or http://box.lan/admin) -> [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/Config.rst Configure] tab -> [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/Config.rst#server-portal Server Portal] -> Select Server Home Page &mdash; <!-- Since IIAB/XSCE 6.2,--> where your choices include:
'''Alternatives:''' <!--Likewise as many educators want quick customizations on their portal/menuing beyond the logo,--> Some prefer <!--may consider experimental WYSIWYG tools--> a completely different front-end for their Internet-in-a-Box home page, e.g. [[#WordPress_.26_Moodle_Administration:_What_tips_.26_tricks_exist%3F|WordPress]] (with this possible [https://github.com/kananigit/iiab-menu-plugin IIAB plugin]), or DokuWiki, or even Moodle etc.  <!--For example you might lay out your content in an indigenous language, linking to content gems truly relevant to locals.-->  Several of these can be enabled in your IIAB's Admin Console (http://box/admin or http://box.lan/admin) -> [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/Config.rst Configure] tab -> [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/Config.rst#server-portal Server Portal] -> Select Server Home Page &mdash; <!-- Since IIAB/XSCE 6.2,--> where your choices include:


* /home
* /home
Line 544: Line 634:
If you do this, don't forget to enable "Check to Enable WordPress" or "Check to Enable DokuWiki" <!--correspondingly,--> at the top of that page &mdash; then on the left click "Save Configuration", followed by [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/Config.rst#actions Install Configured Options] &mdash; finally monitoring the result (typically takes 15-25min on a Raspberry Pi 3, 3 B+ or 4) under the [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/Utilities.rst Utilities] tab -> Display Job Status.
If you do this, don't forget to enable "Check to Enable WordPress" or "Check to Enable DokuWiki" <!--correspondingly,--> at the top of that page &mdash; then on the left click "Save Configuration", followed by [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/Config.rst#actions Install Configured Options] &mdash; finally monitoring the result (typically takes 15-25min on a Raspberry Pi 3, 3 B+ or 4) under the [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/Utilities.rst Utilities] tab -> Display Job Status.


See: [[#What_can_I_do_with_E-books_and_Internet-in-a-Box.3F|What can I do with E-books and Internet-in-a-Box?]]<br>
See: [[#What_can_I_do_with_E-books_and_Internet-in-a-Box%3F|What can I do with E-books and Internet-in-a-Box?]]<br>
See: [[#Can_teachers_display_their_own_content.3F|Can teachers display their own content?]]<br>
See: [[#Can_teachers_display_their_own_content%3F|Can teachers display their own content?]]<br>
See: [[#Is_a_quick_installation_possible.3F|Is a quick installation possible?]]<br>
See: [[#Is_a_quick_installation_possible%3F|Is a quick installation possible?]]<br>
See: [[#What_services_.28IIAB_apps.29_are_suggested_during_installation.3F|What services (IIAB apps) are suggested during installation?]]<br>
See: [[#What_services_.28IIAB_apps.29_are_suggested_during_installation%3F|What services (IIAB apps) are suggested during installation?]]<br>
See: [[#What_are_the_default_passwords?|What are the default passwords?]]<br>
See: [[#What_are_the_default_passwords%3F|What are the default passwords?]]<br>
See: [[#Where_can_I_see_live_demos_of_Internet-in-a-Box.3F|Where can I see live demos of Internet-in-a-Box?]]<br>
See: [[#Where_can_I_see_live_demos_of_Internet-in-a-Box%3F|Where can I see live demos of Internet-in-a-Box?]]<br>
See: [[#How_do_I_change_to_Mobile_view_or_Desktop_view.3F|How do I change to Mobile view or Desktop view?]]<br>
See: [[#How_do_I_change_to_Mobile_view_or_Desktop_view%3F|How do I change to Mobile view or Desktop view?]]<br>
See: [[#How_do_I_add_ZIM_files.2C_like_Wikipedia.3F|How do I add ZIM files, like Wikipedia?]]<br>
See: [[#How_do_I_add_ZIM_files.2C_like_Wikipedia%3F|How do I add ZIM files, like Wikipedia?]]<br>
See: [[#KA_Lite_Administration:_What_tips_.26_tricks_exist.3F|KA Lite Administration: What tips & tricks exist?]]<br>
See: [[#KA_Lite_Administration:_What_tips_.26_tricks_exist%3F|KA Lite Administration: What tips & tricks exist?]]<br>
See: [[#WordPress_.26_Moodle_Administration:_What_tips_.26_tricks_exist.3F|WordPress & Moodle Administration: What tips & tricks exist?]]<br>
See: [[#WordPress_.26_Moodle_Administration:_What_tips_.26_tricks_exist%3F|WordPress & Moodle Administration: What tips & tricks exist?]]<br>
See: [[#Can_I_permanently_attach_an_external_USB_drive,_to_add_more_content?|Can I permanently attach an external USB drive, to add more content?]]<br>
See: [[#Can_I_permanently_attach_an_external_USB_drive,_to_add_more_content%3F|Can I permanently attach an external USB drive, to add more content?]]<br>
See: [[#How_do_I_back_up.2C_shrink_.26_copy_IIAB_microSD_cards.3F|How do I back up, shrink & copy IIAB microSD cards?]]
See: [[#How_do_I_back_up.2C_shrink_.26_copy_IIAB_microSD_cards%3F|How do I back up, shrink & copy IIAB microSD cards?]]


== How do I change to Mobile view or Desktop view? ==
== How do I change to Mobile view or Desktop view? ==
Line 574: Line 664:
* Separately, many mobile browsers have their own button to force Desktop view &mdash; typically found in the top-right under the browser's own vertical ellipsis.  Look there for the "Desktop site [ ]" checkbox in Chrome, or the "Request desktop site [ ]" checkbox in Firefox.
* Separately, many mobile browsers have their own button to force Desktop view &mdash; typically found in the top-right under the browser's own vertical ellipsis.  Look there for the "Desktop site [ ]" checkbox in Chrome, or the "Request desktop site [ ]" checkbox in Firefox.


See: [[#How_do_I_customize_my_Internet-in-a-Box_home_page.3F|How do I customize my Internet-in-a-Box home page?]]
See: [[#How_do_I_customize_my_Internet-in-a-Box_home_page%3F|How do I customize my Internet-in-a-Box home page?]]


== How do I provide Solar Power to my school, library, clinic or orphanage? ==
== How do I provide Solar Power to my school, library, clinic or orphanage? ==
Line 580: Line 670:
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.  <!--Some [http://www.unleashkids.org/2014/02/21/off-the-grid-suitcase-solar-solutions-for-power-in-haiti/ experienced deployment voices] provide concrete examples,-->
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.  <!--Some [http://www.unleashkids.org/2014/02/21/off-the-grid-suitcase-solar-solutions-for-power-in-haiti/ experienced deployment voices] provide concrete examples,-->


In places like Haiti this typically revolves around a bank of 12-volt [http://en.wikipedia.org/wiki/Deep-cycle_battery 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 places like Haiti this typically revolves around a bank of 12-volt [https://en.wikipedia.org/wiki/Deep-cycle_battery 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: [https://github.com/eka-foundation/home/issues/24 eka-foundation/home#24]
In 2019, please see this India solar discussion: [https://github.com/eka-foundation/home/issues/24 eka-foundation/home#24]


Tips from earlier years can also still be useful:
Tips from earlier years can also still be useful:
* http://sunboxlabs.com (Personal Power Plant Projects, DIY Solar + Storage)<br>
* https://sunboxlabs.com (Personal Power Plant Projects, DIY Solar + Storage)<br>
* http://wiki.laptop.org/go/XO_Solar<br>
* https://wiki.laptop.org/go/XO_Solar<br>
* http://lists.laptop.org/listinfo/power<br>
* http://lists.laptop.org/listinfo/power<br>
* http://wiki.laptop.org/go/Battery_and_power<br>
* https://wiki.laptop.org/go/Battery_and_power<br>
* http://schoolserver.wordpress.com/training/power-when-its-not-always-available/
* https://schoolserver.wordpress.com/training/power-when-its-not-always-available/
 
<!--Thanks for taking solar engineering seriously &mdash; engineers especially should subscribe to Richard Smith's [http://lists.laptop.org/listinfo/power "power" discussion list] if you can!-->
Thanks for taking solar engineering seriously &mdash; engineers especially should subscribe to Richard Smith's [http://lists.laptop.org/listinfo/power "power" discussion list] if you can!


== How do I provide Wi-Fi (wireless) to all my kids? ==
== 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 [https://en.wikipedia.org/wiki/Hostapd hostapd].  Of course you may need to run "apt install iw" or "yum install iw" first, so the iw command is available on your server.
If you want a self-contained (single-unit) knowledge hotspot, consider the Wi-Fi capability possibly already built into the computer where you install IIAB. Run <code>iw list</code> and look for "AP" under "Supported interface modes" to see if it's capable of Access Point mode / AP mode ([https://github.com/iiab/iiab/issues/3057#issuecomment-987081624 #3057]) as would be enabled by [https://en.wikipedia.org/wiki/Hostapd hostapd].  (If the <code>iw</code> command isn't yet installed, run <code>sudo apt install iw</code> — also see [[#Can_I_create_a_Wi-Fi_hotspot_using_an_old_laptop%3F|"Can I create a Wi-Fi hotspot using an old laptop?"]] just below.)


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, [https://github.com/m-anish Anish Mangal] has experimented successfully with [https://en.wikipedia.org/wiki/Cantenna cantenna(e)] in India, between classrooms and schools.
Optionally, you may want to [https://github.com/iiab/iiab/wiki/IIAB-Networking#9-optionally-attach-a-wi-fi-access-point-or-ethernet-router-lan-side attach a Wi-Fi Access Point] to your IIAB.  If you want higher-powered Wi-Fi equipment and antenna(e) fully external to your IIAB server, consider approaches such as <!-- https://villagetelco.org or --> the [https://en.wikipedia.org/wiki/Cantenna cantenna] and [https://youtu.be/HkeS_EAIpv4 MeshNet] approaches used by Anish Mangal in India.
<!-- Within classrooms, many deployments use the $20 [https://www.tp-link.com/en/products/details/cat-9_TL-WR841N.html 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 [https://openwrt.org/ OpenWrt], but far simpler)


Within classrooms, many deployments use the $20 [http://www.tp-link.com/en/products/details/cat-9_TL-WR841N.html TP-LINK TL-WR841N] as these Wi-Fi Routers have proved generally reliable over the years.
  https://download.villagetelco.org/firmware/secn/unstable/tp-link/SECN-4/XSCE/
 
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 [https://openwrt.org/ 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.
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.
Line 611: Line 698:
There is also a wiki page outlining how to use PoE (Power over Ethernet) and how to daisy-chain multiple such routers together:
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
   https://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 [http://lists.laptop.org/listinfo/server-devel server-devel@lists.laptop.org] and [https://groups.google.com/group/xsce-devel xsce-devel@googlegroups.com] mailing lists.  There's always '''tons''' to learn from the latest Wi-Fi fieldwork success stories.
Most important: take advantage of community support, where volunteers are eager to help on the [https://groups.google.com/group/xsce-devel xsce-devel@googlegroups.com] and [http://lists.laptop.org/listinfo/server-devel server-devel@lists.laptop.org] 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 [https://groups.google.com/group/unleashkids 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!
Also consider <!--IRC channel #schoolserver on http://webchat.freednode.net for live chat, and--> [https://groups.google.com/group/unleashkids 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 https://internet-in-a-box.org and Pathagar e-books.
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/learning hotspots" in every sense) in turn allowing kids to take advantage of amazing free Digital Libraries like https://internet-in-a-box.org


See: [[#Can_I_create_a_Wi-Fi_hotspot_using_an_old_laptop.3F|Can I create a Wi-Fi hotspot using an old laptop?]]<br>
See: [[#Can_I_create_a_Wi-Fi_hotspot_using_an_old_laptop%3F|Can I create a Wi-Fi hotspot using an old laptop?]]<br>
See: [[#Any_other_networking_tips.3F|Any other networking tips?]]
See: [[#Any_other_networking_tips%3F|Any other networking tips?]]


== Can I create a Wi-Fi hotspot using an old laptop? ==
== 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).
Yes, it is possible to create a Wi-Fi hotspot (using hostapd) on some laptops and netbooks.
 
NOTE: To determine whether your PC/machine's internal WiFi chip has Linux/distro support for AP Mode (allowing for many students to connect to this hotspot) please run <code>/usr/sbin/iw list</code> and look for <code>* AP</code> under <code>Supported interface modes:</code> or <code>software interface modes</code> &mdash; as outlined at [https://github.com/iiab/iiab/issues/3057#issuecomment-987081624 #3057].
 
Equivalent to the above, most IIAB's should have a line in <code>/etc/iiab/iiab.ini</code> saying either <code>can_be_ap = True</code> or <code>can_be_ap = False</code> ([https://github.com/iiab/iiab/pull/3222 PR #3222]).
 
Similarly, you can try running:
 
  sudo iiab-hotspot-on
 
REMINDER: If you ever add or remove a USB Wi-Fi adapter (or an entire Wi-Fi router, typically connected over Ethernet), you then need to run:
 
  sudo iiab-network
<!-- (Prior to August 2022, you needed to run the equivalent:)
 
  cd /opt/iiab/iiab
  sudo ./iiab-network -->
 
You're likely to have good luck with Qualcomm Atheros chipsets &mdash; certainly older Atheros chipsets have good support in GNU/Linux (https://wiki.debian.org/ath9k).


February 2019 Testing Confirms: [https://github.com/iiab/iiab/wiki/IIAB-6.7-Release-Notes IIAB 6.7]'s hostapd Wi-Fi hotspot works with the Qualcomm Atheros AR9285 PCI-Express Wireless device found in an Acer Aspire One.
February 2019 Example: Testing confirmed that [https://github.com/iiab/iiab/wiki/IIAB-6.7-Release-Notes IIAB 6.7]'s hostapd Wi-Fi hotspot worked with the Qualcomm Atheros AR9285 PCI-Express Wireless device found in an Acer Aspire One.


See: [[#What_hardware_should_I_use.3F|What hardware should I use?]]<br>
See: [[#What_hardware_should_I_use%3F|What hardware should I use?]]<br>
See: [[#Any_other_networking_tips.3F|Any other networking tips?]]
See: [[#Any_other_networking_tips%3F|Any other networking tips?]]


== How do I change the wireless network name? ==
== How do I change the Wi-Fi hotspot 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.
The Wi-Fi hotspot name (also known as SSID) is what most people use to connect to Internet-in-a-Box using their Wi-Fi devices.  In other words the name that appears on the air, for your IIAB's wireless network / Access Point / AP.


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) :
How to rename it depends on whether your Wi-Fi hotspot is fully-external (such as a wireless router) or rather under direct OS control (e.g. internal, or a tiny USB-connected wireless adapter) :


<ul>
<ul>
Line 641: Line 746:
<li> If it's under direct OS control, then the Internet-in-a-Box (IIAB) is also the wireless access point:
<li> If it's under direct OS control, then the Internet-in-a-Box (IIAB) is also the wireless access point:
   <ul>
   <ul>
   <li> Edit this line in [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|/etc/iiab/local_vars.yml]] :<br>
   <li> Edit this line in [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|/etc/iiab/local_vars.yml]] :<br>
     <code>host_ssid: Internet in a Box</code> (quotation marks are OPTIONAL)<br>
     <code>host_ssid: Internet in a Box</code> (quotation marks are OPTIONAL)<br>
     Then run:<br>
     Then run:<br>
     <code>cd /opt/iiab/iiab && sudo ./iiab-network</code><!-- The above *vars.yml instructions do NOT work at all as of 14 Oct 2015, causing the AP to disappear even upon reboot.  What does work, on an interim basis: directly editing /etc/hostapd/hostapd.conf then running "systemctl restart hostapd" -- but this is NOT advised, as subsequent console changes will overwrite this. -->
     <code>sudo iiab-network</code><!-- The above *vars.yml instructions do NOT work at all as of 14 Oct 2015, causing the AP to disappear even upon reboot.  What does work, on an interim basis: directly editing /etc/hostapd/hostapd.conf then running "systemctl restart hostapd" -- but this is NOT advised, as subsequent console changes will overwrite this. -->
   <li> 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).
   <li> 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''' (menu) '''> Internal Wi-Fi AP > Internal Wi-Fi Access Point Name'''.
   <li> 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. <!-- add screenshot here -->
    <ul><li> This setting will not take effect until you click on '''Configure''' (menu) '''> Install Configured Options''' (red button), and wait several minutes for all new settings to take effect (monitor status under '''Utilities''' (menu) '''> Display Job Status''').</ul>
   <li> Finally you can run [https://github.com/iiab/iiab/blob/master/roles/network/templates/network/iiab-hotspot-on iiab-hotspot-on] and [https://github.com/iiab/iiab/blob/master/roles/network/templates/network/iiab-hotspot-off iiab-hotspot-off] which are found in /usr/bin &mdash; 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.
   <li> WARNING: do not edit <code>/etc/hostapd/hostapd.conf</code> 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 <code>systemctl restart hostapd</code> to avoid rebooting. <!-- add screenshot here -->
   <li> Finally you can run [https://github.com/iiab/iiab/blob/master/roles/network/templates/network/iiab-hotspot-on sudo iiab-hotspot-on] and [https://github.com/iiab/iiab/blob/master/roles/network/templates/network/iiab-hotspot-off sudo iiab-hotspot-off] which are found in /usr/bin &mdash; especially useful if you've used a Raspberry Pi's internal Wi-Fi to install IIAB software 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 [https://github.com/iiab/iiab/wiki/IIAB-Networking#common-customizations Common Customizations] for more detail.
   </ul>
   </ul>
</ul>
</ul>


See: [[#What_are_the_default_passwords?|What are the default passwords?]]<br>
See: [[#What_are_the_default_passwords%3F|What are the default passwords?]]<br>
See: [[#Any_other_networking_tips.3F|Any other networking tips?]]<br>
See: [[#Any_other_networking_tips%3F|Any other networking tips?]]<br>
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|What is local_vars.yml and how do I customize it?]]<br>
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|What is local_vars.yml and how do I customize it?]]<br>
 
== Can I password protect the Wi-Fi hotspot? ==
 
[https://internet-in-a-box.org Internet-in-a-Box (IIAB)] is generally intended as a free library completely open to all!
 
That said, if you have command-line access to your IIAB using a screen/keyboard or ssh, you can try setting a Wi-Fi password as follows: (assuming your IIAB Wi-Fi hotspot is internal, or is a USB Wi-Fi adapter)
 
# Run: <syntaxhighlight lang="bash">sudo nano /etc/iiab/local_vars.yml</syntaxhighlight>
# Look near [https://github.com/iiab/iiab/blob/f8efc93d0a2b1ac7cdcdb05d56d6a4b20c7fefd4/vars/local_vars_small.yml#L72-L73 Lines 72-73] in your [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|/etc/iiab/local_vars.yml]] to set these 2 variables: <!-- <source></source> --> <syntaxhighlight lang="text">
hostapd_secure: True
hostapd_password: ACTUAL_PASSWORD</syntaxhighlight>
# Save the file (Ctrl-O) and exit (Ctrl-X).
# Run <code>sudo iiab-network</code> and confirm that it completes without error (about 3 minutes later).
# Test it!  Further discussion: [https://github.com/iiab/iiab/discussions/3477#discussioncomment-4950885 #3477]
 
See: [[#Any_other_networking_tips%3F|Any other networking tips?]]<br>
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|What is local_vars.yml and how do I customize it?]]<br>


== Can I name my server something other than http://BOX.LAN ? ==
== Can I name my server something other than http://BOX.LAN ? ==
Line 659: Line 782:
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.
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 strongly desired, this can be implemented within each school/library/clinic by editing [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|/etc/iiab/local_vars.yml]] — and then run "cd /opt/iiab/iiab" followed by "./iiab-network"
If however a custom name is strongly desired, this can be implemented within each school/library/clinic by editing [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|/etc/iiab/local_vars.yml]] — and then run <code>sudo iiab-network</code>
 
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 ~20min on a Raspberry Pi 3, 3 B+ or 4!)


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:
Or: log into '''Admin Console''' (http://box/admin or http://box.lan/admin) '''> Configure''' (menu) '''> Network Parameters > Host Name > Save Configuration > Install Configured Options''' (waiting patiently for that to complete under '''Utilities''' (menu) '''> Display Job Status''' which can take ~20 min on older Raspberry Pi's!)


https://github.com/iiab/iiab/blob/master/roles/network/templates/named/school.external.zone.db<br>
Many different names have been used in the past, such as http://schoolserver.lan and http://school.lan &mdash; anything that resolves locally to http://10.10.10.10 should be sufficient with standard networking (or http://172.18.96.1 if your Internet-in-a-Box pre-dates July 2022). 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.internal.zone.db<br>
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:
https://github.com/iiab/iiab/blob/master/roles/network/templates/named.unused/school.external.zone.db<br>
https://github.com/iiab/iiab/blob/master/roles/network/templates/named.unused/school.internal.zone.db.j2<br>
https://github.com/iiab/iiab/blob/master/roles/network/templates/named.unused/school.local.zone.db.j2
<!-- 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<br>
school.internal.zone.16.in-addr.db<br>
school.internal.zone.32.in-addr.db<br>
school.internal.zone.32.in-addr.db<br>
school.internal.zone.48.in-addr.db<br>
school.internal.zone.48.in-addr.db<br>
school.internal.zone.in-addr.db
school.internal.zone.in-addr.db -->


See: [[#What_are_the_default_passwords?|What are the default passwords?]]<br>
See: [[#What_are_the_default_passwords%3F|What are the default passwords?]]<br>
See: [[#Any_other_networking_tips.3F|Any other networking tips?]]<br>
See: [[#Any_other_networking_tips%3F|Any other networking tips?]]<br>
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|What is local_vars.yml and how do I customize it?]]
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|What is local_vars.yml and how do I customize it?]]


== How do I set a static IP address? ==
== How do I set a static IP address? ==


To set a static (fixed) IP address such as 192.168.1.99, use lines like the following in [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|/etc/iiab/local_vars.yml]] and then run the './iiab-network' command (or './runrole network') in /opt/iiab/iiab :
To set a static (fixed) IP address such as 192.168.1.99, use lines like the following in [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|/etc/iiab/local_vars.yml]] &mdash; and then run <code>sudo iiab-network</code> :


   wan_ip: 192.168.1.99
   wan_ip: 192.168.1.99
Line 692: Line 814:
By default this is a FALLBACK static (fixed) IP address, which requires an Ethernet cable and link-light showing.  If that cable connects IIAB to an Internet router/cablemodem or similar (that is turned on) IIAB should receive a DHCP IP address within about 30 seconds.  Or, if there is no DHCP on the wire, IIAB will set its own IP address (typically on eth0) to 192.168.1.99 per this example, about 45 seconds later.
By default this is a FALLBACK static (fixed) IP address, which requires an Ethernet cable and link-light showing.  If that cable connects IIAB to an Internet router/cablemodem or similar (that is turned on) IIAB should receive a DHCP IP address within about 30 seconds.  Or, if there is no DHCP on the wire, IIAB will set its own IP address (typically on eth0) to 192.168.1.99 per this example, about 45 seconds later.


Specifically, if you keep <code>wan_try_dhcp_before_static_ip: True</code> your /etc/dhcpcd.conf will contain: ''(on Raspberry Pi OS)''
Specifically, if you keep <code>wan_try_dhcp_before_static_ip: True</code> your /etc/dhcpcd.conf will contain: ''(on any OS where IIAB [https://github.com/iiab/iiab/blob/fcc8bcc127355ec74ff890522032113722d2597f/roles/network/templates/network/dhcpcd.conf.j2#L71-L88 sets up] /etc/dhcpcd.conf)''


   profile static_eth0
   profile static_eth0
Line 702: Line 824:
   fallback static_eth0
   fallback static_eth0


Or if you set <code>wan_try_dhcp_before_static_ip: False</code> your /etc/dhcpcd.conf will contain: ''(on Raspberry Pi OS)''
Or if you set <code>wan_try_dhcp_before_static_ip: False</code> your /etc/dhcpcd.conf will contain: ''(on any OS where IIAB [https://github.com/iiab/iiab/blob/fcc8bcc127355ec74ff890522032113722d2597f/roles/network/templates/network/dhcpcd.conf.j2#L71-L88 sets up] /etc/dhcpcd.conf)''


   interface eth0
   interface eth0
Line 721: Line 843:
FYI the above 7 lines also work when nothing at all is added to /etc/dhcpcd.conf, if you want an alternative approach in support of intermittent online updates of your IIAB via Ethernet cable to cablemodem etc (careful though, this unsupported approach is risky as your eth0 will often have 2 IP addresses!)
FYI the above 7 lines also work when nothing at all is added to /etc/dhcpcd.conf, if you want an alternative approach in support of intermittent online updates of your IIAB via Ethernet cable to cablemodem etc (careful though, this unsupported approach is risky as your eth0 will often have 2 IP addresses!)


''WHEREAS on Ubuntu 18.04,'' the <code>wan_try_dhcp_before_static_ip</code> variable is currently ignored (i.e. treated as <code>False</code>) and [https://netplan.io/ netplan] stores your static IP address settings from /etc/iiab/local_vars.yml into /etc/netplan/01-iiab-config.yaml as follows:
''WHEREAS on Ubuntu,'' the <code>wan_try_dhcp_before_static_ip</code> variable is currently ignored (i.e. treated as <code>False</code>) and [https://netplan.io/ Netplan] stores your static IP address settings from [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|/etc/iiab/local_vars.yml]] into <code>/etc/netplan/01-iiab-config.yaml</code> as follows:


   network:
   network:
Line 735: Line 857:
           search: [lan]
           search: [lan]


Debian 10's equivalent to be clarified in future, after its 2019-07-06 release (please help us here if you can!)
Debian 12's equivalent to be clarified in future (please help us here if you can!)


FINALLY, if IIAB is already installed, also consider IIAB's Admin Console (http://box/admin or http://box.lan/admin) -> [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/Config.rst Configure] tab -> [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/Config.rst#network-parameters Network Parameters] -> Check to use a static WAN IP Address instead of DHCP -> (enter your) Static WAN IP Address -> Save Configuration -> [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/Config.rst#actions Install Configured Options].
FINALLY, if IIAB is already installed, also consider IIAB's '''Admin Console''' (http://box/admin or http://box.lan/admin) '''> [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/Config.rst Configure]''' (menu) '''> [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/Config.rst#network-parameters Network Parameters] > Check to use a static WAN IP Address instead of DHCP >''' (enter your) '''Static WAN IP Address > Save Configuration > [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/Config.rst#actions Install Configured Options]'''.


See: [[#What_are_the_default_passwords?|What are the default passwords?]]<br>
See: [[#What_are_the_default_passwords%3F|What are the default passwords?]]<br>
See: [[#Any_other_networking_tips.3F|Any other networking tips?]]<br>
See: [[#Any_other_networking_tips%3F|Any other networking tips?]]<br>
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|What is local_vars.yml and how do I customize it?]]
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|What is local_vars.yml and how do I customize it?]]


== Any other networking tips? ==
== Any other networking tips? ==


If you've just installed Internet-in-a-IIAB (IIAB) on your home network, here are some [https://github.com/iiab/iiab-factory/blob/f37bfd994bd9b4cc2c12470736e7ee3cc6f41380/iiab#L502-L534 great tricks] to [https://www.raspberrypi.com/documentation/computers/remote-access.html#ip-address find its IP Address].
If you've just installed Internet-in-a-Box (IIAB) on your home network, here are some [https://github.com/iiab/iiab-factory/blob/55a157180b2720ae663ce02b8804949b45684f5b/iiab#L579-L605 great tricks] to [https://www.raspberrypi.com/documentation/computers/remote-access.html#ip-address find its IP Address].


WI-FI RECOMMENDATIONS:
WI-FI RECOMMENDATIONS:


* Please change "host_country_code: US" to the correct country code, in [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|/etc/iiab/local_vars.yml]], prior to installing IIAB.  If IIAB is already installed, also run "cd /opt/iiab/iiab ; sudo ./iiab-network"
* Please change "host_country_code: US" to the correct country code, in [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|/etc/iiab/local_vars.yml]], prior to installing IIAB.  If IIAB is already installed, also run <code>sudo iiab-network</code> and then reboot.
** FYI as of 2022-01-04 this sets the country code in <code>/etc/hostapd/hostapd.conf</code> but not in <code>/etc/wpa_supplicant/wpa_supplicant.conf</code> (right after installing Raspberry Pi OS, you make that happen by running <code>raspi-config</code> -> '''Localisation Options > WLAN Country'''). [https://github.com/iiab/iiab/issues/3097 #3097]


* IF YOU CONNECT YOUR IIAB'S INTERNAL WI-FI TO THE INTERNET OVER 5 GHz, YOU'LL PREVENT OLDER LAPTOPS/PHONES/TABLETS (WHICH REQUIRE 2.4 GHz) FROM CONNECTING TO YOUR IIAB'S INTERNAL HOTSPOT.  This relates to "wifi_up_down: True" in [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|/etc/iiab/local_vars.yml]]
* IF YOU CONNECT YOUR IIAB'S INTERNAL WI-FI TO THE INTERNET OVER 5 GHz, YOU'LL PREVENT OLDER LAPTOPS/PHONES/TABLETS (WHICH REQUIRE 2.4 GHz) FROM CONNECTING TO YOUR IIAB'S INTERNAL HOTSPOT.  This relates to <code>wifi_up_down: True</code> in [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|/etc/iiab/local_vars.yml]]


* If your IIAB Raspberry Pi is connected to the Internet over Wi-Fi, and you need to change its upstream Wi-Fi connection: run "sudo iiab-hotspot-off" then "sudo raspi-config" (to [dis]associate from/to any upstream WiFi access point) then "sudo iiab-hotspot-on" and reboot, as outlined at: https://github.com/iiab/iiab/wiki/IIAB-7.2-Release-Notes#whats-upgraded
* If your IIAB Raspberry Pi is connected to the Internet over Wi-Fi, and you need to change its upstream Wi-Fi connection: run <code>sudo iiab-hotspot-off</code> then <code>sudo raspi-config</code> (to [dis]associate from/to any upstream WiFi access point) then <code>sudo iiab-hotspot-on</code> and reboot &mdash; as outlined in Section (2) of [https://github.com/iiab/iiab/wiki/IIAB-Networking#common-customizations Common Customizations].


PLEASE ALSO LOOK OVER:
PLEASE ALSO LOOK OVER:


* The [https://github.com/iiab/iiab/tree/master/roles/network#network-readme 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 to your final deployment topology.'''
* The [https://github.com/iiab/iiab/tree/master/roles/network#readme network README] outlines the [https://github.com/iiab/iiab/tree/master/roles/network 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 (<code>sudo iiab-network</code>) <!--or ./runrole network)--> after all your Ethernet and Wi-Fi network interfaces are '''plugged in and turned on properly ''(or unplugged properly!)'' according to your final deployment topology.'''


* The high-level [https://github.com/iiab/iiab/wiki/IIAB-Networking IIAB Networking] doc reviews Internet-in-a-Box's:
* The high-level [https://github.com/iiab/iiab/wiki/IIAB-Networking IIAB Networking] doc reviews Internet-in-a-Box's:
** [https://github.com/iiab/iiab/wiki/IIAB-Networking#internet-in-a-box-iiab-networking 3 Network Modes distinguishing WAN-side from LAN-side]
** [https://github.com/iiab/iiab/wiki/IIAB-Networking#three-network-modes Three Network Modes &mdash; distinguishing WAN side from LAN side]
** [https://github.com/iiab/iiab/wiki/IIAB-Networking#list-of-ports--services Common Ports]
** [https://github.com/iiab/iiab/wiki/IIAB-Networking#common-customizations Common Customizations]
** [https://github.com/iiab/iiab/wiki/IIAB-Networking#firewall-iptables Firewall (iptables) Settings]
** [https://github.com/iiab/iiab/wiki/IIAB-Networking#dns DNS Name Resolution]
** [https://github.com/iiab/iiab/wiki/IIAB-Networking#dns DNS Name Resolution]
** [https://github.com/iiab/iiab/wiki/IIAB-Networking#common-customizations Common Customizations]
** [https://github.com/iiab/iiab/wiki/IIAB-Networking#list-of-ports--services List of Ports / Services]
** [https://github.com/iiab/iiab/wiki/IIAB-Networking#firewall-iptables Firewall (iptables)]
 


PRO TIP: <i>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!</i>
PRO TIP: <i>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!</i>


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" from directory /opt/iiab/iiab when your Internet connection is live.
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 run <code>sudo iiab-network</code> <!--when your Internet connection is live.-->
 
FYI Wi-Fi (e.g. for Internet access, etc) is available on the graphical/desktop version of Ubuntu 22.04 LTS (e.g. use its desktop GUI to set SSID and password) &mdash; whereas server versions of Ubuntu don't offer Wi-Fi out of the box.
<!--More advanced networking insights follow from the [https://docs.google.com/document/d/1Ez1H2LYrkqeXR_r5T93CMdmx9CeTJp_vC-IDBGam1Bc/edit#heading=h.rt7rcwigph2r stock instructions for setting up upstream and downsteam routers] attached to ASUS NUC hardware, just as an example.-->


FYI Wi-Fi (e.g. for Internet access, etc) is available on the graphical/desktop version of Ubuntu 20.04 LTS (e.g. use its desktop GUI to set SSID and password) &mdash; whereas the server version of Ubuntu 20.04 LTS doesn't offer Wi-Fi out of the box.
NOTE: To determine whether your PC/machine's internal WiFi chip has Linux/distro support for AP Mode (allowing for many students to connect to this hotspot) please run <code>/usr/sbin/iw list</code> and look for "AP" under "Supported interface modes:" or "supported interface modes" &mdash; as outlined at [https://github.com/iiab/iiab/issues/3057#issuecomment-987081624 #3057].
<!--More advanced networking insights follow from the [https://docs.google.com/document/d/1Ez1H2LYrkqeXR_r5T93CMdmx9CeTJp_vC-IDBGam1Bc/edit#heading=h.rt7rcwigph2r 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.
Some prefer Gigabyte BRIX (a drop-in replacement Mini PC, instead of the ASUS [formerly Intel] NUC) as an Atheros internal Wi-Fi module can be inserted, to scale beyond the NUC'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.
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 [http://lists.laptop.org/listinfo/server-devel server-devel@lists.laptop.org] !
Please ask questions about your specific school's networking/wiring challenges <!--at https://IIAB.io and--> on mailing list [https://groups.google.com/group/unleashkids unleashkids@googlegroups.com] !
<!--FEBRUARY 2018 WORKAROUND: When IIAB is installed on Ubuntu 17.10 or (pre-release) Ubuntu 18.04 users might have difficulties connecting over Wi-Fi to the server.  As a temporary measure until IIAB supports Ubuntu 18.04 officially later in 2018, consider moving the contents of /etc/network/interfaces.d/iiab to /etc/network/interfaces (issue [https://github.com/iiab/iiab/issues/625 #625]).-->
<!-- FEBRUARY 2018 WORKAROUND: When IIAB is installed on Ubuntu 17.10 or (pre-release) Ubuntu 18.04 users might have difficulties connecting over Wi-Fi to the server.  As a temporary measure until IIAB supports Ubuntu 18.04 officially later in 2018, consider moving the contents of /etc/network/interfaces.d/iiab to /etc/network/interfaces (issue [https://github.com/iiab/iiab/issues/625 #625]). -->
<!--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 [https://github.com/iiab/iiab/pull/697 Pull Request #697] similar to Jerry Vonau's [https://github.com/iiab/iiab/pull/748 Pull Request #748].-->
<!-- 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 [https://github.com/iiab/iiab/pull/697 Pull Request #697] similar to Jerry Vonau's [https://github.com/iiab/iiab/pull/748 Pull Request #748]. -->


See: [[#How_do_I_provide_Wi-Fi_.28wireless.29_to_all_my_kids.3F|How do I provide Wi-Fi (wireless) to all my kids?]]<br>
See: [[#How_do_I_provide_Wi-Fi_.28wireless.29_to_all_my_kids%3F|How do I provide Wi-Fi (wireless) to all my kids?]]<br>
See: [[#Can_I_create_a_Wi-Fi_hotspot_using_an_old_laptop.3F|Can I create a Wi-Fi hotspot using an old laptop?]]<br>
See: [[#Can_I_create_a_Wi-Fi_hotspot_using_an_old_laptop%3F|Can I create a Wi-Fi hotspot using an old laptop?]]<br>
See: [[#How_do_I_change_the_wireless_network_name.3F|How do I change the wireless network name?]]<br>
See: [[#How_do_I_change_the_Wi-Fi_hotspot_name%3F|How do I change the Wi-Fi hotspot name?]]<br>
See: [[#Can_I_name_my_server_something_other_than_http:.2F.2FBOX.LAN_.3F|Can I name my server something other than http://BOX.LAN ?]]<br>
See: [[#Can_I_name_my_server_something_other_than_http:.2F.2FBOX.LAN_%3F|Can I name my server something other than http://BOX.LAN ?]]<br>
See: [[#How_do_I_set_a_static_IP_address.3F|How do I set a static IP address?]]<br>
See: [[#How_do_I_set_a_static_IP_address%3F|How do I set a static IP address?]]<br>
See: [[#Captive_Portal_Administration:_What_tips_.26_tricks_exist.3F|Captive Portal Administration: What tips & tricks exist?]]
See: [[#Captive_Portal_Administration:_What_tips_.26_tricks_exist%3F|Captive Portal Administration: What tips & tricks exist?]]


== What is local_vars.yml and how do I customize it? ==
== What is local_vars.yml and how do I customize it? ==
Line 792: Line 918:
To customize your Internet-in-a-Box (IIAB), modify IIAB configuration variables within '''/etc/iiab/local_vars.yml'''
To customize your Internet-in-a-Box (IIAB), modify IIAB configuration variables within '''/etc/iiab/local_vars.yml'''


''It's best to do this prior to installing IIAB, when IIAB's [http://download.iiab.io/ 1-line installer] prompts you with "Edit /etc/iiab/local_vars.yml to customize your Internet-in-a-Box? [Y/n]"''  <!--After installing IIAB, also consider IIAB's Admin Console (http://box.lan/admin).-->
''It's best to do this prior to installing IIAB, when IIAB's [https://download.iiab.io/ 1-line installer] prompts you with "Edit /etc/iiab/local_vars.yml to customize your Internet-in-a-Box? [Y/n]"''  <!--After installing IIAB, also consider IIAB's Admin Console (http://box.lan/admin).-->


Three common example local_vars.yml files are posted for comparison ([https://github.com/iiab/iiab/blob/master/vars/local_vars_small.yml SMALL-sized], [https://github.com/iiab/iiab/blob/master/vars/local_vars.yml MEDIUM-sized], and [https://github.com/iiab/iiab/blob/master/vars/local_vars_large.yml LARGE-sized]).  See also this [https://github.com/iiab/iiab/blob/master/vars/local_vars_medical.yml medical example] used by the [https://meta.wikimedia.org/wiki/Wiki_Project_Med Wiki Project Med Foundation] e.g. for http://med.iiab.me.  In addition see our bare bones example, very useful for [https://github.com/iiab/iiab/blob/master/vars/local_vars_unittest.yml unit testing of a single IIAB App].
Three common example local_vars.yml files are posted for comparison ([https://github.com/iiab/iiab/blob/master/vars/local_vars_small.yml SMALL-sized], [https://github.com/iiab/iiab/blob/master/vars/local_vars_medium.yml MEDIUM-sized], and [https://github.com/iiab/iiab/blob/master/vars/local_vars_large.yml LARGE-sized]).  See also this [https://github.com/iiab/iiab/blob/master/vars/local_vars_medical.yml medical example] used by the [https://meta.wikimedia.org/wiki/Wiki_Project_Med Wiki Project Med Foundation] e.g. for http://med.iiab.me.  In addition see our bare bones example, very useful for [https://github.com/iiab/iiab/blob/master/vars/local_vars_unittest.yml unit testing of a single IIAB App].


<br>
<br>
Line 804: Line 930:
#* One way to do this is <code>cd /opt/iiab/iiab</code> followed by <!--'./iiab-install --reinstall'--> <code>sudo ./iiab-configure</code> (this can take many minutes on a Raspberry Pi, depending on your changes!)
#* One way to do this is <code>cd /opt/iiab/iiab</code> followed by <!--'./iiab-install --reinstall'--> <code>sudo ./iiab-configure</code> (this can take many minutes on a Raspberry Pi, depending on your changes!)
#** FYI this runs [https://github.com/iiab/iiab/blob/master/iiab-from-cmdline.yml Stage 0, followed by Stages 4-9], WITHOUT running the [https://github.com/iiab/iiab/tree/master/roles/network#network-readme 'network' role].
#** FYI this runs [https://github.com/iiab/iiab/blob/master/iiab-from-cmdline.yml Stage 0, followed by Stages 4-9], WITHOUT running the [https://github.com/iiab/iiab/tree/master/roles/network#network-readme 'network' role].
#** This is very similar to [[#What_are_the_default_passwords?|logging into]] IIAB's '''Admin Console''' (http://box.lan/admin) and then clicking '''Configure''' > '''Install Configured Options''' &mdash; which runs [https://github.com/iiab/iiab/blob/master/iiab-from-console.yml Stage 0, followed by Stages 4-9, WITH the 'network' role].  Then monitor the progress, in '''Utilities''' > '''Display Job Status'''.  Or if you prefer the command-line, use: <code>tail -f /tmp/job-<JOB NUMBER></code>
#** This is very similar to [[#What_are_the_default_passwords%3F|logging into]] IIAB's '''Admin Console''' (http://box.lan/admin) and then clicking '''Configure''' > '''Install Configured Options''' &mdash; which runs [https://github.com/iiab/iiab/blob/master/iiab-from-console.yml Stage 0, followed by Stages 4-9, WITH the 'network' role].  Then monitor the progress, in '''Utilities''' > '''Display Job Status'''.  Or if you prefer the command-line, use: <code>tail -f /tmp/job-<JOB NUMBER></code>
#* Or, run a (fast) surgical strike using <code>cd /opt/iiab/iiab</code> followed by <code>sudo ./runrole <ROLE NAME></code> to run a single [https://github.com/iiab/iiab/tree/master/roles Ansible role] or [https://github.com/iiab/iiab/wiki/IIAB-Contributors-Guide#ansible IIAB Stage].
#* Or, run a (fast) surgical strike using <code>cd /opt/iiab/iiab</code> followed by <code>sudo ./runrole <ROLE NAME></code> to run a single [https://github.com/iiab/iiab/tree/master/roles Ansible role] or [https://github.com/iiab/iiab/wiki/Technical-Contributors-Guide#understanding-ansible IIAB Stage].
#** Try <code>sudo ./runrole</code> (without parameters) to see its options, e.g. <code>sudo ./runrole --reinstall <ROLE NAME></code>
#** Try <code>sudo ./runrole</code> (without parameters) to see its options, e.g. <code>sudo ./runrole --reinstall <ROLE NAME></code>
#** Or, run <code>sudo ./iiab-network</code> to run IIAB's [https://github.com/iiab/iiab/tree/master/roles/network#network-readme 'network' role]. This is equivalent to: <code>sudo ./runrole network</code>
#** Or, run <code>sudo iiab-network</code> to run IIAB's [https://github.com/iiab/iiab/tree/master/roles/network#network-readme 'network' role].
#* If you must, you can force the running of [https://github.com/iiab/iiab/blob/master/iiab-stages.yml all Stages 0-9, WITH the 'network' role].  Use <code>cd /opt/iiab/iiab</code> followed by <code>sudo ./iiab-install --reinstall</code>
#* If you must, you can force the running of [https://github.com/iiab/iiab/blob/master/iiab-stages.yml all Stages 0-9, WITH the 'network' role].  Use <code>cd /opt/iiab/iiab</code> followed by <code>sudo ./iiab-install --reinstall</code>
#** DANGER: You may first want to delete <code>/opt/iiab/iiab/iiab_state.yml</code> (to apply more force, At Your Own Risk!)
#** DANGER: You may first want to delete <code>/opt/iiab/iiab/iiab_state.yml</code> (to apply more force, At Your Own Risk!)
Line 817: Line 943:
<br>
<br>


PRO TIP: A couple very practical networking variables are posted at the [https://github.com/iiab/iiab/wiki/IIAB-Networking#common-customizations bottom of the IIAB Networking] document.
PRO TIP: Some very practical networking variables are posted at the [https://github.com/iiab/iiab/wiki/IIAB-Networking#common-customizations bottom of the IIAB Networking] document.


<!--<br>
<!--<br>
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".-->
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_services_.28IIAB_apps.29_are_suggested_during_installation.3F|What services (IIAB apps) are suggested during installation?]]<br>
See: [[#What_services_.28IIAB_apps.29_are_suggested_during_installation%3F|What services (IIAB apps) are suggested during installation?]]<br>
See: [[#What_are_the_default_passwords?|What are the default passwords?]]<br>
See: [[#What_are_the_default_passwords%3F|What are the default passwords?]]<br>
See: [[#Any_other_networking_tips.3F|Any other networking tips?]]<br>
See: [[#Any_other_networking_tips%3F|Any other networking tips?]]<br>
See: [[#Can_I_upgrade_IIAB_software.3F|Can I upgrade IIAB software?]]<br>
See: [[#Can_I_upgrade_IIAB_software%3F|Can I upgrade IIAB software?]]<br>
See: [[#Can_I_upgrade_or_reinstall_server_apps.3F|Can I upgrade or reinstall server apps?]]<br>
See: [[#Can_I_upgrade_or_reinstall_server_apps%3F|Can I upgrade or reinstall server apps?]]<br>
See: [[#What_are_the_best_places_for_community_support?|What are the best places for community support?]]
See: [[#What_are_the_best_places_for_community_support%3F|What are the best places for community support?]]


== Is a "Rapid Power Off" button possible for low-electricity environments? ==
== Is a "Rapid Power Off" button possible for low-electricity environments? ==
Line 833: Line 959:
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.
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.


"'''apache_allow_sudo: True'''" is the default in [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|/etc/iiab/local_vars.yml]] to make this possible.<!--and then run "cd /opt/iiab/iiab" then "./iiab-install --reinstall" 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 [https://github.com/iiab/iiab/pull/1165 #1165]]-->
"'''apache_allow_sudo: True'''" is the default in [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|/etc/iiab/local_vars.yml]] to make this possible.<!--and then run "cd /opt/iiab/iiab" then "./iiab-install --reinstall" 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 [https://github.com/iiab/iiab/pull/1165 #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)
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)
Line 842: Line 968:
   sudo ./runrole www_options
   sudo ./runrole www_options


The "Power Off" button can also 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 [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/ContentMenus.rst help page] and [https://github.com/iiab/iiab/issues/1689 #1689].
The "Power Off" button can also be customized in IIAB's '''Admin Console''' (http://box/admin or http://box.lan/admin) '''> Content''' (menu) '''> Load Menu >''' (change the settings in) '''Properties of Current Menu > Save Menu'''.  More detail on the Content Menus [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/ContentMenus.rst help page] and [https://github.com/iiab/iiab/issues/1689 #1689].
<!--Earlier Known Issue in [[IIAB/6.3|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.-->
<!--Earlier Known Issue in [[IIAB/6.3|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.3F|What is local_vars.yml and how do I customize it?]]
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|What is local_vars.yml and how do I customize it?]]


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


Look in <code>/etc/iiab/iiab.env</code> for the line(s) that begin with "IIAB_RELEASE=".  This is followed by a number like "7.2" showing the version level (even if you're running a pre-release of that version!)  Context: <code>IIAB_RELEASE</code> is sourced from <code>iiab_base_ver</code> at the top of [https://github.com/iiab/iiab/blob/master/vars/default_vars.yml /etc/iiab/iiab/vars/default_vars.yml] during IIAB (re-)installation.
The best way is to run <code>iiab-summary</code> to get a quick ~20 line overview of your Internet-in-a-Box (IIAB) system.


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".
Also, look for <code>iiab_base_ver</code> near the top of your [https://github.com/iiab/iiab/blob/master/vars/default_vars.yml <code>/opt/iiab/iiab/vars/default_vars.yml</code>].  This is followed by a number like "8.1" showing the version level (even if you're running a pre-release of that version!)  You can also look in <code>/etc/iiab/iiab.env</code> for the line(s) with "IIAB_RELEASE=".


The "Version" field should show something more definitive like "release-7.1" &mdash; 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)
Finally, your iiab branch name is visible if you log into your IIAB'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 typically shows "master" (or something like "release-8.1").  <!-- &mdash; 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-7.1) to reconfirm you have [http://wiki.laptop.org/go/IIAB/7.1 IIAB 7.1] (e.g. it should begin with '''58fcf69''' if you're running the official IIAB 7.1 from June 6, 2020.
The 40-character "Commit ID" string gives more detail.  You can compare this to commits within https://github.com/iiab/iiab/commits/master and https://github.com/iiab/iiab/releases <!-- (such as https://github.com/iiab/iiab/tree/release-8.0) --> &mdash; e.g. if you're running the older [https://github.com/iiab/iiab/releases/tag/release-8.0 IIAB 8.0] from December 31, 2022, it would begin with '''8f04d45'''.


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 https://download.iiab.io/6.2/rpi/ and https://download.iiab.io/6.2/x86/
CAUTION: the letter 'g' is confusingly sometimes added in front of such 7-character githashes (abbreviated from the full 40-character SHA-1 githash) in a few places, like the install image filenames at https://download.iiab.io/8.1/


See: [[#Is_a_quick_installation_possible.3F|Is a quick installation possible?]]<br>
See: [[#Is_a_quick_installation_possible%3F|Is a quick installation possible?]]<br>
See: [[#What_are_the_default_passwords?|What are the default passwords?]]<br>
See: [[#What_are_the_default_passwords%3F|What are the default passwords?]]<br>
See: [[#Can_I_upgrade_IIAB_software.3F|Can I upgrade IIAB software?]]
See: [[#Can_I_upgrade_IIAB_software%3F|Can I upgrade IIAB software?]]


== Can I upgrade IIAB software? ==
== Can I upgrade IIAB software? ==
Line 869: Line 995:
''If your IIAB is more than a few weeks old, it's generally much better to install IIAB from scratch at https://download.iiab.io''
''If your IIAB is more than a few weeks old, it's generally much better to install IIAB from scratch at https://download.iiab.io''


But if you're willing to proceed At Your Own Risk ([[#How_do_I_back_up.2C_shrink_.26_copy_IIAB_microSD_cards.3F|making a backup first]]) here are instructions, if you've connected your IIAB to the Internet: (about 15 steps)
But if you're willing to proceed AT YOUR OWN RISK ([[#How_do_I_back_up.2C_shrink_.26_copy_IIAB_microSD_cards%3F|MAKE A BACKUP FIRST]]) here are instructions, if you've connected your IIAB to the Internet: (about 15 commands in total)


   sudo su -
   sudo -i


   cd /opt/iiab/iiab
   cd /opt/iiab/iiab
Line 880: Line 1,006:
   git pull
   git pull


WARNING: At this point it's best to regenerate your [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|/etc/iiab/local_vars.yml]] settings and customizations, starting with a fresh copy from one of the 3 local_vars_*.yml files (SMALL-sized, MEDIUM-sized, or LARGE-sized) available in <code>/opt/iiab/iiab/vars</code>
WARNING: At this point it's best to regenerate your [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|/etc/iiab/local_vars.yml]] settings and customizations, starting with a fresh copy from one of the 3 local_vars_*.yml files (SMALL-sized, MEDIUM-sized, or LARGE-sized) available in <code>/opt/iiab/iiab/vars</code>


WARNING: You may want to delete <code>/opt/iiab/iiab/iiab_state.yml</code> (to apply more force, AT YOUR OWN RISK!)
WARNING: You may want to delete <code>/opt/iiab/iiab/iiab_state.yml</code> (to apply more force, AT YOUR OWN RISK!)
Line 900: Line 1,026:
FYI the 2+2 "git checkout" lines above are NOT necessary if each local repo is already on the <code>master</code> branch.  You can run 'git branch' in each of the 2 above (local repo) directories, if you want to see what branch they're on.
FYI the 2+2 "git checkout" lines above are NOT necessary if each local repo is already on the <code>master</code> branch.  You can run 'git branch' in each of the 2 above (local repo) directories, if you want to see what branch they're on.


See: [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|What is local_vars.yml and how do I customize it?]]<br>
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|What is local_vars.yml and how do I customize it?]]<br>
See: [[#How_do_I_know_what_version_of_IIAB_I.27m_running.3F|How do I know what version of IIAB I'm running?]]<br>
See: [[#How_do_I_know_what_version_of_IIAB_I.27m_running%3F|How do I know what version of IIAB I'm running?]]<br>
See: [[#Can_I_upgrade_or_reinstall_server_apps.3F|Can I upgrade or reinstall server apps?]]<br>
See: [[#Can_I_upgrade_or_reinstall_server_apps%3F|Can I upgrade or reinstall server apps?]]<br>
See: [[#Can_I_get_content_updates_every_few_months_or_semester.3F|Can I get content updates every few months or semester?]]<br>
See: [[#Can_I_get_content_updates_every_few_months_or_semester%3F|Can I get content updates every few months or semester?]]<br>
See: [[#How_do_I_back_up.2C_shrink_.26_copy_IIAB_microSD_cards.3F|How do I back up, shrink & copy IIAB microSD cards?]]
See: [[#How_do_I_back_up.2C_shrink_.26_copy_IIAB_microSD_cards%3F|How do I back up, shrink & copy IIAB microSD cards?]]


== Can I upgrade or reinstall server apps? ==
== Can I upgrade or reinstall server apps? ==
Line 910: Line 1,036:
1) Most IIAB Apps can be reinstalled to the very latest available version when you're online, as follows:
1) Most IIAB Apps can be reinstalled to the very latest available version when you're online, as follows:


   sudo su -
   sudo -i
   cd /opt/iiab/iiab
   cd /opt/iiab/iiab
   ./runrole --reinstall [https://github.com/iiab/iiab/tree/master/roles <APP OR ROLE NAME>]
   ./runrole --reinstall [https://github.com/iiab/iiab/tree/master/roles <APP OR ROLE NAME>]
Line 925: Line 1,051:
2) HIGH RISK: ''If your IIAB was recently installed,'' you can try to reinstall all of your apps to the latest available versions, and reinstall IIAB itself, as follows: (this could take a while!)
2) HIGH RISK: ''If your IIAB was recently installed,'' you can try to reinstall all of your apps to the latest available versions, and reinstall IIAB itself, as follows: (this could take a while!)


   sudo su -
   sudo -i
   mv /etc/iiab/iiab_state.yml /etc/iiab/iiab_state.yml.old
   mv /etc/iiab/iiab_state.yml /etc/iiab/iiab_state.yml.old
   cd /opt/iiab/iiab
   cd /opt/iiab/iiab
   git pull &nbsp; &nbsp; # THIS LINE AT YOUR OWN RISK!
   git pull &nbsp;&nbsp; # THIS LINE AT YOUR OWN RISK!
   ./iiab-install --reinstall
   ./iiab-install --reinstall


Line 950: Line 1,076:
* /usr/libexec/iiab-startup.sh ''(delete this if you want to upgrade to IIAB's latest e.g. [https://github.com/iiab/iiab/blob/master/roles/2-common/templates/iiab-startup.sh /opt/iiab/iiab/roles/2-common/templates/iiab-startup.sh])''
* /usr/libexec/iiab-startup.sh ''(delete this if you want to upgrade to IIAB's latest e.g. [https://github.com/iiab/iiab/blob/master/roles/2-common/templates/iiab-startup.sh /opt/iiab/iiab/roles/2-common/templates/iiab-startup.sh])''
* [Deletion of /library/wordpress is optional; online-upgrade is automatic/mandatory when running "./iiab-install --reinstall" or "./runrole wordpress" in /opt/iiab/iiab] Also Note: 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 database "iiab_wp" by running "mysql" as root, and then "drop database iiab_wp;" confirmed by "show databases;".  Dropping the db is an easy way to change the language of WordPress' user interface &mdash; or this can also be done in http://box/wordpress > Settings > General > Site Language &mdash; and if the desired language is not one of your OS's installed locales, WordPress will try to download it.)''
* [Deletion of /library/wordpress is optional; online-upgrade is automatic/mandatory when running "./iiab-install --reinstall" or "./runrole wordpress" in /opt/iiab/iiab] Also Note: 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 database "iiab_wp" by running "mysql" as root, and then "drop database iiab_wp;" confirmed by "show databases;".  Dropping the db is an easy way to change the language of WordPress' user interface &mdash; or this can also be done in http://box/wordpress > Settings > General > Site Language &mdash; and if the desired language is not one of your OS's installed locales, WordPress will try to download it.)''
* [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 [https://www.mediawiki.org/wiki/Manual:Upgrading#Frequently_asked_questions 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 [https://github.com/iiab/iiab/blob/master/roles/mediawiki/defaults/main.yml /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/mediawiki-ACTUAL.VERSION.NUMBER/LocalSettings.php no longer required; BUT database schema changes on almost every upgrade.  So: automatic installation of latest (during "./runrole --reinstall mediawiki") generally requires you first drop or update mysql "iiab_mediawiki"; for database/schema upgrades read about update.php in [https://www.mediawiki.org/wiki/Manual:Upgrading#Frequently_asked_questions MediaWiki Manual's Upgrading FAQ]] ''(MediaWiki version visible within http://box.lan/wiki/Special:Version and in dir name e.g. /library/mediawiki-ACTUAL.VERSION.NUMBER, as installed by [https://github.com/iiab/iiab/blob/master/roles/mediawiki/defaults/main.yml /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)''
* [Upgrading a very recent version of Lokole MAY require deletion e.g. with "rm -rf /library/lokole"]  In any case, attempt to install the latest Lokole using: "./runrole --reinstall lokole".  ''(Lokole version is shown by "grep ^Version /library/lokole/venv/lib/python3.*/site-packages/opwen_email_client-*/*" [METADATA on some OS's, PKG-INFO on others].  If removing Lokole entirely, you may also want to clear out its Apache config files: "rm -rf /library/lokole /etc/apache2/sites-*/lokole.conf")''
* [Upgrading a very recent version of Lokole MAY require deletion e.g. with "rm -rf /library/lokole"]  In any case, attempt to install the latest Lokole using: "./runrole --reinstall lokole".  ''(Lokole version is shown by "grep ^Version /library/lokole/venv/lib/python3.*/site-packages/opwen_email_client-*/*" [METADATA on some OS's, PKG-INFO on others].  If removing Lokole entirely, you may also want to clear out its Apache config files: "rm -rf /library/lokole /etc/apache2/sites-*/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 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/bin/kolibri --version")''
* [No file deletion required; <code>apt update</code> then <code>apt install kolibri</code> can work to upgrade Kolibri since August 2022.  CAUTION: Administrators need to type in the username <code>kolibri</code> when apt upgrading Kolibri as of 2022, due to Kolibri bug [https://github.com/learningequality/kolibri-installer-debian/issues/115 learningequality/kolibri-installer-debian#115]] ''(Kolibri version shown by <code>/usr/bin/kolibri --version</code> &mdash; a full wipe/purge of Kolibri can be accomplished by <code>apt purge kolibri</code> and then removing [1] /library/kolibri [2] /etc/kolibri and [3] /usr/bin/kolibri as nec.)''
* [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; 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 directories /opt/iiab/sugarizer-server/node_modules and MongoDB's entire /library/dbdata/mongodb)''
* [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 directories /opt/iiab/sugarizer-server/node_modules and MongoDB's entire /library/dbdata/mongodb)''
* [No file deletion required, online-upgrade is automatic/mandatory during "./iiab-install --reinstall" or "./runrole --reinstall gitea"] ''(High-level Gitea version is shown by "ls -l /library/gitea/gitea" &mdash; point release is shown at bottom-left of http://box/gitea)''
* [No file deletion required; online-upgrade is automatic/mandatory during "./iiab-install --reinstall" or "./runrole --reinstall gitea"] ''(High-level Gitea version is shown by "ls -l /library/gitea/gitea" &mdash; point release is shown at bottom-left of http://box/gitea)''
* After JupyterHub is installed, here are 2 ways to check the version number: (1) <code>ls -d /opt/iiab/jupyterhub/lib/python3.*/site-packages/jupyterhub-*</code> (2) http://box/jupyterhub -> log in (e.g. Admin/changeme) -> File menu -> Hub Control Panel -> Admin menu.  If you want to reinstall JupyterHub from scratch, first delete directory <code>/opt/iiab/jupyterhub</code> &mdash; and read more about JupyterHub operations here: https://github.com/iiab/iiab/blob/master/roles/jupyterhub/README.md


''WARNING #1: Data loss of kids', teachers' and users' personal materials is always possible, ALWAYS back up any relevant databases first!''
''WARNING #1: Data loss of kids', teachers' and users' personal materials is always possible, ALWAYS back up any relevant databases first!''
Line 967: Line 1,094:
# 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
# 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_.28IIAB_apps.29_are_suggested_during_installation.3F|What services (IIAB apps) are suggested during installation?]]<br>
See: [[#What_services_.28IIAB_apps.29_are_suggested_during_installation%3F|What services (IIAB apps) are suggested during installation?]]<br>
See: [[#What_are_the_default_passwords?|What are the default passwords?]]<br>
See: [[#What_are_the_default_passwords%3F|What are the default passwords?]]<br>
See: [[#KA_Lite_Administration:_What_tips_.26_tricks_exist.3F|KA Lite Administration: What tips & tricks exist?]]<br>
See: [[#KA_Lite_Administration:_What_tips_.26_tricks_exist%3F|KA Lite Administration: What tips & tricks exist?]]<br>
See: [[#How_do_I_back_up.2C_shrink_.26_copy_IIAB_microSD_cards.3F|How do I back up, shrink & copy IIAB microSD cards?]]
See: [[#How_do_I_back_up.2C_shrink_.26_copy_IIAB_microSD_cards%3F|How do I back up, shrink & copy IIAB microSD cards?]]


== Can I get content updates every few months or semester? ==
== Can I get content updates every few months or semester? ==
Line 983: Line 1,110:
<!--overweight/monolithic download torrents-->
<!--overweight/monolithic download torrents-->


'''Please watch the HOW-TO videos on Internet-in-a-Box's [https://www.youtube.com/channel/UC0cBGCxr_WPBPa3IqPVEe3g YouTube channel] (several available as [http://d.iiab.io/content/videos .mp4 and .WebMD]) to get up to speed with downloading & installing content to your IIAB!'''
'''Please watch the HOW-TO videos on Internet-in-a-Box's [https://www.youtube.com/channel/UC0cBGCxr_WPBPa3IqPVEe3g YouTube channel] (several available as [https://download.iiab.io/content/videos .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.
On the high end, IIAB's '''Admin Console''' (http://box/admin or http://box.lan/admin '''> Install Content''') supports piecewise incremental content updates, e.g. for schools with very high-bandwidth Internet connectionsNote that older Content Packs can be individually be removed within '''Admin Console''' (http://box.lan/admin) '''> Manage Content''', when there's a need to free up disk space.  Likewise IIAB Apps such as KA Lite and Kolibri offer administrative interfaces, supporting deletion of lessons/videos within their environments, 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.
As a practical matter, remote schools may receive larger updates via hard drive or USB memory stick every semester or every year — e.g. flown in or driven in or mailed in by a partner.  Empowering them with new maps / encyclopedias / E-Books / video lessons — as well as other content and apps.


Keep in touch as new options evolve!  Make contact with http://unleashkids.org to keep up with other communities' offline content collections and recommendations. <!--obtain a copy of the [https://docs.google.com/document/d/1RXzapvzvGRxPoJk0v9Wsdn0Wv02M-iokY6jZ8BQDh9U latest Internet-in-a-Box content] from these volunteers' community efforts.-->
Keep in touch as new options evolve!  Please make contact to keep up with other communities' offline content collections and recommendations. <!--obtain a copy of the [https://docs.google.com/document/d/1RXzapvzvGRxPoJk0v9Wsdn0Wv02M-iokY6jZ8BQDh9U latest Internet-in-a-Box content] from these volunteers' community efforts.-->


See: [[#What_are_the_default_passwords?|What are the default passwords?]]<br>
See: [[#What_are_the_default_passwords%3F|What are the default passwords?]]<br>
See: [[#How_do_I_customize_my_Internet-in-a-Box_home_page.3F|How do I customize my Internet-in-a-Box home page?]]<br>
See: [[#How_do_I_customize_my_Internet-in-a-Box_home_page%3F|How do I customize my Internet-in-a-Box home page?]]<br>
See: [[#How_do_I_add_ZIM_files.2C_like_Wikipedia.3F|How do I add ZIM files, like Wikipedia?]]<br>
See: [[#How_do_I_add_ZIM_files.2C_like_Wikipedia%3F|How do I add ZIM files, like Wikipedia?]]<br>
See: [[#Can_I_permanently_attach_an_external_USB_drive,_to_add_more_content?|Can I permanently attach an external USB drive, to add more content?]]<br>
See: [[#Can_I_permanently_attach_an_external_USB_drive,_to_add_more_content%3F|Can I permanently attach an external USB drive, to add more content?]]<br>
See: [[#What_are_the_best_places_for_community_support?|What are the best places for community support?]]
See: [[#What_are_the_best_places_for_community_support%3F|What are the best places for community support?]]


== What security tips exist? ==
== What security tips exist? ==


Please read more about the 'iiab-admin' Linux user and group, which allow you to log in to IIAB's Admin Console:
Please read more about the <code>iiab-admin</code> Linux user and group, which allow you to log in to IIAB's Admin Console:


* https://github.com/iiab/iiab/tree/master/roles/iiab-admin
* https://github.com/iiab/iiab/tree/master/roles/iiab-admin
* https://github.com/iiab/iiab-admin-console/blob/master/Authentication.md
* https://github.com/iiab/iiab-admin-console/blob/master/Authentication.md


Some <!--http://tinyurl.com/iiabimages--> IIAB installations 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 <code>rm -f /root/.ssh/authorized_keys</code><!-- &mdash; whereas in the past this was "sudo rm -r /home/iiab-admin/.ssh/authorized_keys".-->
Some <!--https://tinyurl.com/iiabimages--> IIAB installations 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 <code>sudo rm /root/.ssh/authorized_keys</code><!-- &mdash; whereas in the past this was "sudo rm -r /home/iiab-admin/.ssh/authorized_keys".-->


Whether running your server online or offline, please see [[Security]] and help us contribute to this evolving knowledge & repertoire of 21st century hygiene, thanks to professional volunteers from many backgrounds.
Whether running your server online or offline, please see [[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?|What are the default passwords?]]<br>
See: [[#What_are_the_default_passwords%3F|What are the default passwords?]]<br>
See: [[#How_can_I_remotely_manage_my_Internet-in-a-Box.3F|How can I remotely manage my Internet-in-a-Box?]]<br>
See: [[#How_can_I_remotely_manage_my_Internet-in-a-Box%3F|How can I remotely manage my Internet-in-a-Box?]]<br>
See: [[#Is_campuswide_access_possible_for_all_server_apps.3F|Is campuswide access possible for all server apps?]]<br>
See: [[#Is_campuswide_access_possible_for_all_server_apps%3F|Is campuswide access possible for all server apps?]]<br>
See: [[#What_are_the_best_places_for_community_support?|What are the best places for community support?]]
See: [[#What_are_the_best_places_for_community_support%3F|What are the best places for community support?]]
 
== Can I use HTTPS / TLS / SSL instead of HTTP? ==
 
This is impossible with an Internet-in-a-Box (IIAB) set up in a permanently OFFLINE school or community, as the World Wide Web Consortium sadly does not allow this ([https://github.com/w3c/webappsec-secure-contexts/issues/60#issuecomment-1504392682 reasons explained here]).  Worse, those who try to force this with self-signed web server certificates find that everyday users (the world's poorest citizens, and others!) do not tolerate the complexity and hassle of scary browser pop-up overrides.
 
If however you're setting up an IIAB that will be ONLINE (with regular Internet access) then HTTPS encryption is thankfully easy to set up:
 
# Set <code>gui_port: 443</code> in <code>/etc/iiab/local_vars.yml</code> preferably prior to installing IIAB.  (Or if IIAB software is already installed, modify and then run <code>/usr/bin/iiab-gen-iptables</code> so that your [https://github.com/iiab/iiab/wiki/IIAB-Networking#firewall-iptables iptables firewall] opens up port 443 instead of port 80).
# After IIAB software is installed, edit <code>/etc/nginx/server.conf</code> to remove or comment out <code>server_name $hostname;</code> — instead set '''your actual domain name''' e.g. <code>server_name MY-DOMAIN.ORG;</code>
# Run: <syntaxhighlight lang="text">
sudo -i
apt install certbot python3-certbot-nginx
certbot --nginx -d MY-DOMAIN.ORG</syntaxhighlight>
# The above <code>certbot</code> command asks you a few simple questions to help arrange [https://letsencrypt.org/2015/11/09/why-90-days.html auto-renewal of your web certificate every 60-to-90 days], before it modifies your <code>/etc/nginx/server.conf</code> (check this file carefully for any further manual modifications that you might require!)
# If you modified any NGINX (web server) configuration files, run <code>nginx -t && nginx -s reload</code> to validate then "reload" NGINX.
# Test HTTPS access to your IIAB, by browsing to your actual Internet domain name, e.g. https://MY-DOMAIN.ORG
# If you later need to manually renew your web certificate (e.g. if its Internet access is very unreliable) then consider commands like: <code>certbot renew --dry-run</code>, <code>certbot renew --force-renewal</code> or simply <code>certbot renew</code>
 
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|What is local_vars.yml and how do I customize it?]]


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


1. You can use https://remote.it to remotely support almost any IIAB, as summarized here: https://github.com/iiab/iiab/tree/master/roles/remoteit
1. You can use https://remote.it to remotely support almost any IIAB.  Simply run <code>sudo iiab-remoteit</code> at the Linux command-line (of any IIAB that is online) and it tells you what to do.  And if necessary, long-form instructions are here: https://github.com/iiab/iiab/tree/master/roles/remoteit
<!--or [https://remote.it/ remot3.it] (formerly known as [http://www.weaved.com/raspberry-pi-remote-connection/ Weaved]).-->
<!--or [https://remote.it/ remot3.it] (formerly known as [http://www.weaved.com/raspberry-pi-remote-connection/ Weaved]).-->


2. Another option is [https://en.wikipedia.org/wiki/OpenVPN OpenVPN] permitting remote maintenance of your IIAB over ssh and http, among a core trusted group.  This is a well-tested arrangement, likewise suitable for a wider enterprise's remote administration needs.  (Alternatively the newer [https://en.wikipedia.org/wiki/WireGuard WireGuard] can also be considered, as is now integrated with the Linux kernel.)  <sub>[https://github.com/iiab/iiab/issues/318 #318] [https://github.com/iiab/iiab/issues/1124 #1124]</sub>
2. Another option is [https://en.wikipedia.org/wiki/OpenVPN OpenVPN] permitting remote maintenance of your IIAB over ssh and http, among a core trusted group.  This is a well-tested arrangement, likewise suitable for a wider enterprise's remote administration needs.  (Alternatively the newer [https://en.wikipedia.org/wiki/WireGuard WireGuard] can also be considered, as is now integrated with the Linux kernel.)  <sub>[https://github.com/iiab/iiab/issues/318 #318] [https://github.com/iiab/iiab/issues/1124 #1124]</sub>


3. Smaller-scale implementers may prefer traditional Linux-and-ssh arrangements across firewalls using https://ngrok.com or https://dataplicity.com &mdash; possibly in combination with router port-forwarding and Dynamic DNS services like No-IP (https://noip.com).  <!-- (in the past https://serveo.net was useful but is often offline in 2019/2020) -->
3. Smaller-scale implementers may prefer traditional Linux-and-ssh arrangements across firewalls using https://ngrok.com or https://dataplicity.com or https://www.zerotier.com &mdash; possibly in combination with router port-forwarding and Dynamic DNS services like No-IP (https://noip.com).  <!-- (in the past https://serveo.net was useful but is often offline in 2019/2020) -->
 
4. In all 3 above cases, consider [https://github.com/iiab/iiab/wiki/Technical-Contributors-Guide#low-bandwidth-screen-sharing low-bandwidth screen sharing using the <code>screen</code> command] as explained in IIAB's [https://github.com/iiab/iiab/wiki/Technical-Contributors-Guide Technical Contributors Guide].


4. Finally, beginners sometimes prefer classical screensharing, e.g. using [https://en.wikipedia.org/wiki/TeamViewer TeamViewer] "unattended access.This can work well if you have a graphical desktop environment <!-- (like X Windows) --> on your Internet-in-a-Box, to take advantage of [https://en.wikipedia.org/wiki/TeamViewer TeamViewer's] full visual/remote support.  This can also be priceless when mentoring/learning at a distance, thanks to TeamViewer's screen-sharing, keyboard-sharing and mouse-sharing &mdash; helping to onboard new operators who aren't yet comfortable with GNU/Linux and its command line tools.  In a graphical desktop environment, simply [https://www.teamviewer.com/en/download/linux/ install TeamViewer], which by default randomizes TeamViewer's password (needed for remote access) every time TeamViewer is launched, preserving local operator control.
5. Beginners may prefer graphical screensharing via Zoom, Google Meet, or [https://en.wikipedia.org/wiki/TeamViewer TeamViewer] "unattended access"  especially if you have a graphical desktop environment <!-- (like X Windows) --> on your Internet-in-a-Box.  This can also be priceless when mentoring/learning at a distance, thanks to TeamViewer's screen-sharing, keyboard-sharing and mouse-sharing &mdash; helping to onboard new operators who aren't yet comfortable with GNU/Linux and its command line tools.  In a graphical desktop environment, simply [https://www.teamviewer.com/en/download/linux/ install TeamViewer], which by default randomizes TeamViewer's password (needed for remote access) every time TeamViewer is launched, preserving local operator control.


And if you want, enable TeamViewer's fully "unattended access" by setting a more permanent password for remote access here: TeamViewer > Extras > Options > Security > Personal Password (for unattended access).
And if you want, enable TeamViewer's fully "unattended access" by setting a more permanent password for remote access here: TeamViewer > Extras > Options > Security > Personal Password (for unattended access).


Raspberry Pi: If you're using the [https://www.raspberrypi.org/software/operating-systems/ Raspberry Pi OS] (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 version 15.22.3 as of 2021-10-28).  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.
Raspberry Pi: If you're using the [https://www.raspberrypi.com/software/operating-systems/ Raspberry Pi OS] (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 version 15.51.5 as of 2024-03-16).  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 Raspberry Pi OS Lite) with "teamviewer info" "teamviewer passwd <ACTUAL-PASSWORD>" and "teamviewer help" per https://community.teamviewer.com/English/kb/articles/6318-how-to-install-teamviewer-for-linux.  <!--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 Raspberry Pi OS, Ubuntu or Debian: http://download.iiab.io/7.0/prep+teamviewer.txt
Bonus: headless installation/configuration is also now supported (e.g. on Raspberry Pi OS Lite) with "teamviewer info" "teamviewer passwd <ACTUAL-PASSWORD>" and "teamviewer help" per https://community.teamviewer.com/English/kb/articles/6318-how-to-install-teamviewer-for-linux.  <!--In future, it might even be possible to install directly with "apt install teamviewer-host" ?  Here is an older way to automate the installation of TeamViewer and a few other basic tools on a fresh OS, that was used with IIAB 7.0 on OS's like Raspberry Pi OS, Ubuntu or Debian: https://download.iiab.io/7.0/prep+teamviewer.txt
'''Ubuntu/Debian Warning:''' If you insist on installing the Calibre E-Book Reader [https://github.com/iiab/iiab/blob/master/roles/calibre/tasks/debs.yml via .debs] (instead of the [https://github.com/iiab/iiab/blob/master/roles/calibre/tasks/py-installer.yml 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. -->
'''Ubuntu/Debian Warning:''' If you insist on installing the Calibre E-Book Reader [https://github.com/iiab/iiab/blob/master/roles/calibre/tasks/debs.yml via .debs] (instead of the [https://github.com/iiab/iiab/blob/master/roles/calibre/tasks/py-installer.yml 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. -->


<i>'''Note:''' Developers' ssh keys may be included with <!-- [http://tinyurl.com/iiabimages --> [https://github.com/iiab/iiab/wiki/Raspberry-Pi-Images:-Summary install images], to facilitate remote support during Beta programs and similar.  Read "[[#What_security_tips_exist?|What security tips exist?]]" if you want instructions to remove these keys.</i>
<i>'''Note:''' Developers' ssh keys may be included with <!-- [https://tinyurl.com/iiabimages --> [https://github.com/iiab/iiab/wiki/Raspberry-Pi-Images-~-Summary#iiab-images-for-raspberry-pi IIAB install images], to facilitate remote support during Beta programs and similar.  Read "[[#What_security_tips_exist%3F|What security tips exist?]]" if you want instructions to remove these keys.</i>


<i>'''Admin Console:''' if http://box.lan/admin shows red errors when you try to log in, please read the red messages and try reloading the page a minute later &mdash; you can also take a look at the output of: <code>systemctl status iiab-cmdsrv.service</code></i>
<i>'''Admin Console:''' if http://box.lan/admin shows red errors when you try to log in, please read the red messages and try reloading the page a minute later &mdash; you can also take a look at the output of: <code>systemctl status iiab-cmdsrv.service</code></i>


See: [[#What_are_the_default_passwords?|What are the default passwords?]]<br>
See: [[#What_are_the_default_passwords%3F|What are the default passwords?]]<br>
See: [[#What_security_tips_exist?|What security tips exist?]]<br>
See: [[#What_security_tips_exist%3F|What security tips exist?]]<br>
See: [[#What_are_the_best_places_for_community_support?|What are the best places for community support?]]
See: [[#What_are_the_best_places_for_community_support%3F|What are the best places for community support?]]


== How do I view usage statistics? ==
== How do I view usage statistics? ==


To help teachers view which ZIM files are most popular:
Please consider [[#What_services_%28IIAB_apps%29_are_suggested_during_installation%3F|AWStats and Matomo in the table above]].
 
EXAMPLE &mdash; to help teachers understand which ZIM files are most popular:


# 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
# Ensure the following lines are in [[#What_services_.28IIAB_apps.29_are_suggested_during_installation%3F|/etc/iiab/local_vars.yml]]<syntaxhighlight>
#* kiwix_install: True
kiwix_install: True
#* kiwix_enabled: True
kiwix_enabled: True</syntaxhighlight>
# Visit http://box/awstats or http://box/awstats/awstats.pl to view stats
# If the above lines are newly added, run <code>cd /opt/iiab/iiab</code> then <code>sudo ./runrole kiwix</code> <!--or <code>./iiab-install [--reinstall] was already run (installing IIAB 6.5+ generally takes care of this)</code>-->
#* user visits to http://box/kiwix/ZIMNAME/ are tabulated
# Visit http://box/awstats <!-- or http://box/awstats/awstats.pl --> to view stats:
#* user visits to http://box:3000/kiwix/ZIMNAME/ (formerly http://box:3000/ZIMNAME/) are NOT tabulated
#* User visits to http://box/kiwix/ZIMNAME/ are recorded
#* User visits to http://box:3000/kiwix/ZIMNAME/ (formerly http://box:3000/ZIMNAME/) are NOT recorded


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


* [https://github.com/iiab/iiab/pull/585 PR #585 Proxy for Kiwix]
* [https://github.com/iiab/iiab/issues/1268 #1268 AWStats]
* [https://github.com/iiab/iiab/issues/1762 #1762 IIAB Community Analytics framework, above & beyond AWStats]
* [https://github.com/iiab/iiab/pull/3304 PR #3304 Matomo]
<!--Noting: [warning some instructions below are stale as of 2022]
* 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
* 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")
* 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.
* 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: [https://github.com/iiab/iiab/pull/585 PR #585]
* Underlying code is at: [https://github.com/iiab/iiab/pull/585 PR #585]
* Please help us improve this community analytics approach if you can: [https://github.com/iiab/iiab/issues/1268 #1268]
* Please help us improve these community analytics approaches if you can:-->
 
See: [[#What_services_.28IIAB_apps.29_are_suggested_during_installation%3F|What services (IIAB apps) are suggested during installation?]]<br>
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|What is local_vars.yml and how do I customize it?]]


== How do I add ZIM files, like Wikipedia? ==
== How do I add ZIM files, like Wikipedia? ==


'''Please read "[[#How_do_I_customize_my_Internet-in-a-Box_home_page.3F|How do I customize my Internet-in-a-Box home page?]]" and see the HOW-TO videos on Internet-in-a-Box's [https://www.youtube.com/channel/UC0cBGCxr_WPBPa3IqPVEe3g YouTube channel] (several available as [http://d.iiab.io/content/videos .mp4 and .webm]) to get up to speed with downloading & installing content to your IIAB!'''
'''Please read "[[#How_do_I_customize_my_Internet-in-a-Box_home_page%3F|How do I customize my Internet-in-a-Box home page?]]"'''  Several HOW-TO videos on Internet-in-a-Box's [https://www.youtube.com/channel/UC0cBGCxr_WPBPa3IqPVEe3g YouTube channel] (some available as [https://download.iiab.io/content/videos .mp4 and .webm]) can also help you install content onto your IIAB:


1. Definitely consider Internet-in-a-Box's [https://github.com/iiab/iiab/wiki/IIAB-Installation#add-with-admin-console Admin Console] (http://box/admin or http://box.lan/admin) -> [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/InstContent.rst Install Content] as an alternative to the command-line!
1. To download ZIM files, [[#What_are_the_default_passwords%3F|log in]] to your Internet-in-a-Box's (IIAB) [https://github.com/iiab/iiab/wiki/IIAB-Installation#add-with-admin-console Admin Console] (http://box.lan/admin) '''-> Install Content -> [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/InstContent.rst#get-zim-files-from-kiwix Get ZIM Files from Kiwix]''' <!-- 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.
2. Or, if you already have content on hand (like ZIM files or OER2Go/RACHEL modules) on a portable USB disk or USB flash drive, insert the USB drive into your Internet-in-a-Box (IIAB).  Then use your IIAB's Admin Console (http://box.lan/admin) '''-> Install Content -> [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/InstContent.rst#manage-content Manage Content]''' to copy the content you need, installing it onto your IIAB: <!-- PLEASE NOTE: -->


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.  
* The USB drive must have the same <code>/library</code> layout as your IIAB:
** ZIM files belong in <code>/library/zims/content</code>
** OER2Go/RACHEL modules belong in <code>/library/www/html/modules</code> <!--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".  
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.
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.
* Copying content works in both directions!  (You can also copy ZIM files and OER2Go/RACHEL modules ''from'' your IIAB ''to'' the USB drive &mdash; to bring content to another IIAB, community or school.)


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 &mdash; for example:
3. Or, if you prefer the command-line, download the ZIM file you want (e.g. from https://download.kiwix.org/zim/) directly to your IIAB's /library/zims/content &mdash; for example:


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


Then run /usr/bin/iiab-make-kiwix-lib to rebuild the Kiwix index:
Then run /usr/bin/iiab-make-kiwix-lib to update your IIAB's ZIM file index:


   sudo iiab-make-kiwix-lib
   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!
While rarely necessary, if you need to completely rebuild your IIAB's ZIM file index, run:
 
  sudo iiab-make-kiwix-lib -f
 
4. Finally, whichever approach you choose above, test that your new ZIM file(s) are browsable at http://box/kiwix and that search features (at the top-right of the page) are working!
 
IN FUTURE:


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 &mdash; see also: https://github.com/iiab/iiab/blob/master/roles/kiwix/README.rst
* Students may be able to take small ZIM files home with them, on their own phones.
* Teachers might be able to auto-display (or auto-install) ZIM files from USB sticks/drives inserted into any IIAB: [https://github.com/iiab/iiab/issues/857 #857] [https://github.com/iiab/iiab/issues/1538 #1538]


IN FUTURE, it might be possible for teachers to auto-display (or auto-install) ZIM files from USB sticks/drives inserted into IIAB: [https://github.com/iiab/iiab/issues/857 #857] [https://github.com/iiab/iiab/issues/1538 #1538]
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 https://download.kiwix.org/portable -->) the ZIM comes with associated index files that must be placed in /library/zim/index &mdash; please see: https://github.com/iiab/iiab/tree/master/roles/kiwix#readme


See: [[#What_can_I_do_with_E-books_and_Internet-in-a-Box?|What can I do with E-books and Internet-in-a-Box?]]<br>
See: [[#What_can_I_do_with_E-books_and_Internet-in-a-Box%3F|What can I do with E-books and Internet-in-a-Box?]]<br>
See: [[#Can_teachers_display_their_own_content.3F|Can teachers display their own content?]]<br>
See: [[#Can_teachers_display_their_own_content%3F|Can teachers display their own content?]]<br>
See: [[#What_are_the_default_passwords?|What are the default passwords?]]<br>
See: [[#What_are_the_default_passwords%3F|What are the default passwords?]]<br>
See: [[#How_do_I_customize_my_Internet-in-a-Box_home_page.3F|How do I customize my Internet-in-a-Box home page?]]<br>
See: [[#How_do_I_customize_my_Internet-in-a-Box_home_page%3F|How do I customize my Internet-in-a-Box home page?]]<br>
See: [[#Can_I_upgrade_or_reinstall_server_apps.3F|Can I upgrade or reinstall server apps?]]<br>
See: [[#Can_I_upgrade_or_reinstall_server_apps%3F|Can I upgrade or reinstall server apps?]]<br>
See: [[#Can_I_permanently_attach_an_external_USB_drive,_to_add_more_content?|Can I permanently attach an external USB drive, to add more content?]]
See: [[#Can_I_permanently_attach_an_external_USB_drive,_to_add_more_content%3F|Can I permanently attach an external USB drive, to add more content?]]


== KA Lite Administration: What tips & tricks exist? ==
== 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 [http://download.iiab.io/ 1-line installer] does this for you!)
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 [https://download.iiab.io 1-line installer] does this for you!)


* assessment (836 MB on a new install)
* assessment (836 MB on a new install)
Line 1,103: Line 1,271:
* srt (subtitles, 105MB 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?|What are the default passwords?]]" above.
To change KA Lite's Admin and user-level passwords, see "[[#What_are_the_default_passwords%3F|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.
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 [https://ka-lite.readthedocs.io/en/latest/usermanual/userman_admin.html#bulk-video-downloads torrenting the compressed KA Lite videos] ([http://pantry.learningequality.org/downloads/ka-lite/0.17/content/ available in 7 common languages], [http://download.iiab.io/packages/ka-lite/ also here]) ''as their storage footprint is more than 3X smaller!''
'''Instead of the above,''' many prefer [https://ka-lite.readthedocs.io/en/latest/usermanual/userman_admin.html#bulk-video-downloads torrenting the compressed KA Lite videos] ([https://pantry.learningequality.org/downloads/ka-lite/0.17/content/ available in 7 common languages], [https://download.iiab.io/packages/ka-lite/ also here]) ''as their storage footprint is more than 3X smaller!''


Traditionally Windows users use BitTorrent client software like [https://www.tixati.com/ Tixati], and Linux users use command-line BitTorrent tools like [https://aria2.github.io/ 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:
Traditionally Windows users use BitTorrent client software like [https://www.tixati.com/ Tixati], and Linux users use command-line BitTorrent tools like [https://aria2.github.io/ 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 [https://github.com/iiab/iiab/tree/master/roles/transmission Transmission] by running "cd /opt/iiab/iiab" then "./runrole transmission" then "./iiab-network".
A. Internet-in-a-Box can now kickstart the BitTorrent download(s) for you, if you set <code>transmission_install</code> and <code>transmission_enabled</code> to <code>True</code> in [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|/etc/iiab/local_vars.yml]] and pick the KA Lite language(s) you need.  Install and launch [https://github.com/iiab/iiab/tree/master/roles/transmission Transmission] by running <code>cd /opt/iiab/iiab</code> then <code>sudo ./runrole transmission</code> then <code>sudo iiab-network</code>


B. Monitor your BitTorrent download(s) at http://box:9091 using Admin/changeme until download is confirmed complete (can take hours if not days!)
B. Monitor your BitTorrent download(s) at http://box:9091 using Admin/changeme until download is confirmed complete (can take hours if not days!)
Line 1,125: Line 1,293:
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:
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!)
'''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 https://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 [https://github.com/iiab/iiab/wiki/IIAB-Networking#list-of-ports--services English on port 8008, Spanish on port 8007, and French on port 8006].  Examine the [https://github.com/iiab/iiab-factory/blob/master/content/khan/mk-other-kalite /opt/iiab/iiab-factory/content/khan/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 8006" (make sure your mk-other-kalite is up-to-date!)
'''Multilingual?'''  Consider running 2 or 3 instances of KA Lite on the same Internet-in-a-Box server, e.g. we sometimes put [https://github.com/iiab/iiab/wiki/IIAB-Networking#list-of-ports--services English on port 8008, Spanish on port 8007, and French on port 8006].  Examine the [https://github.com/iiab/iiab-factory/blob/master/content/khan/mk-other-kalite /opt/iiab/iiab-factory/content/khan/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 8006" (make sure your mk-other-kalite is up-to-date!)


If you do this, make sure [https://github.com/iiab/iiab/wiki/IIAB-Networking#firewall-iptables 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 <code>ports_externally_visible:</code> variable in [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|/etc/iiab/local_vars.yml]] and consider these 2 older examples: [https://github.com/iiab/iiab/issues/88 open ports below 8008], [https://github.com/iiab/iiab/issues/1519 open up port 4244].
If you do this, make sure [https://github.com/iiab/iiab/wiki/IIAB-Networking#firewall-iptables 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 <code>ports_externally_visible:</code> variable in [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|/etc/iiab/local_vars.yml]] and consider these 2 older examples: [https://github.com/iiab/iiab/issues/88 open ports below 8008], [https://github.com/iiab/iiab/issues/1519 open up port 4244].


'''Monolingual in Spanish or French or similar?'''  Fool [https://github.com/iiab/iiab-admin-console/blob/master/roles/js-menu/templates/config.json.j2 /opt/iiab/iiab-admin-console/roles/js-menu/templates/config.json.j2] (live at /library/www/html/js-menu/config.json) by changing the line with "es-kalitePort" from 8007 to 8008 &mdash; 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).  A separate/crude hack to get other languages to work with ports 8006 or 8007 is to put <code>"lang": "fr",</code> or <code>"lang": "es",</code> in the .json file in the /library/www/html/js-menu/menu-files/menu-defs directory.
'''Monolingual in Spanish or French or similar?'''  Fool [https://github.com/iiab/iiab-admin-console/blob/master/roles/js-menu/templates/config.json.j2 /opt/iiab/iiab-admin-console/roles/js-menu/templates/config.json.j2] (live at /library/www/html/js-menu/config.json) by changing the line with "es-kalitePort" from 8007 to 8008 &mdash; 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).  A separate/crude hack to get other languages to work with ports 8006 or 8007 is to put <code>"lang": "fr",</code> or <code>"lang": "es",</code> in the .json file in the /library/www/html/js-menu/menu-files/menu-defs directory.
Line 1,139: Line 1,307:
'''What about Kolibri, also from Learning Equality?'''  Please see the [https://github.com/iiab/iiab/tree/master/roles/kolibri#kolibri-readme Kolibri README].
'''What about Kolibri, also from Learning Equality?'''  Please see the [https://github.com/iiab/iiab/tree/master/roles/kolibri#kolibri-readme Kolibri README].


See: [[#What_are_the_default_passwords?|What are the default passwords?]]<br>
See: [[#What_are_the_default_passwords%3F|What are the default passwords?]]<br>
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|What is local_vars.yml and how do I customize it?]]
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|What is local_vars.yml and how do I customize it?]]


== How do I add zoomable maps for my region? ==
== How do I add zoomable maps for my region? ==


Please explore our [http://iiab.me/maps Live Demo] and read our new [https://github.com/iiab/iiab/wiki/IIAB-Maps IIAB Maps instructions] from September 2020 for [https://github.com/iiab/iiab/wiki/IIAB-7.2-Release-Notes IIAB 7.2], which explains:
Please explore our [http://iiab.me/maps Live Demo] and read our new [https://github.com/iiab/iiab/wiki/IIAB-Maps IIAB Maps instructions] from May 2022 for [https://github.com/iiab/iiab/wiki/IIAB-8.0-Release-Notes IIAB 8.0], which explains:


* [https://github.com/iiab/iiab/wiki/IIAB-Maps#whats-new-with-iiab-maps What's New with IIAB Maps?]
* [https://github.com/iiab/iiab/wiki/IIAB-Maps#whats-new-with-iiab-maps What's New with IIAB Maps?]
* [https://github.com/iiab/iiab/wiki/IIAB-Maps#how-do-i-install-map-packs-and-satellite-photo-regions-on-iiab-72- How do I install Map Pack(s) and Satellite Photo Region(s) on IIAB 7.2+ ?]
* [https://github.com/iiab/iiab/wiki/IIAB-Maps#how-do-i-install-map-packs-and-satellite-photo-regions-on-iiab-80- How do I install Map Pack(s) and Satellite Photo Region(s) on IIAB 8.0+ ?]
* [https://github.com/iiab/iiab/wiki/IIAB-Maps#how-do-i-upgrade-an-iiab-map-pack How do I upgrade an IIAB Map Pack?]
* [https://github.com/iiab/iiab/wiki/IIAB-Maps#how-do-i-upgrade-an-iiab-map-pack How do I upgrade an IIAB Map Pack?]
* [https://github.com/iiab/iiab/wiki/IIAB-Maps#where-are-iiab-maps-stored Where are IIAB Maps stored?]
* [https://github.com/iiab/iiab/wiki/IIAB-Maps#where-are-iiab-maps-stored Where are IIAB Maps stored?]
* [https://github.com/iiab/iiab/wiki/IIAB-Maps#customizations Customizations]
* [https://github.com/iiab/iiab/wiki/IIAB-Maps#what-might-future-iiab-maps-bring What might future IIAB Maps bring?]
* [https://github.com/iiab/iiab/wiki/IIAB-Maps#what-might-future-iiab-maps-bring What might future IIAB Maps bring?]
* [https://github.com/iiab/iiab/wiki/IIAB-Maps#links--advanced-topics Links & Advanced Topics]
* [https://github.com/iiab/iiab/wiki/IIAB-Maps#links--advanced-topics Links & Advanced Topics]


''INVITATION: If you can help ongoing efforts to polish maps for children in offline schools in all countries, directly contributing to [https://youtu.be/HJub6U_U7Mg beautifying OpenStreetMap (VIDEO)] thereby bringing Earth to life for all, Thank You!  Read more at ([https://github.com/iiab/iiab/issues/877#issuecomment-405935272 #877]) and please do [[#What_are_the_best_places_for_community_support.3F|get in touch]] to learn more!''
''INVITATION: If you can help ongoing efforts to polish maps for children in offline schools in all countries, directly contributing to [https://youtu.be/HJub6U_U7Mg beautifying OpenStreetMap (VIDEO)] thereby bringing Earth to life for all, Thank You!  Read more at ([https://github.com/iiab/iiab/issues/877#issuecomment-405935272 #877]) and please do [[#What_are_the_best_places_for_community_support%3F|get in touch]] to learn more!''
 
<!-- <hr>
<hr>


OLDER STUFF, JUST FOR THE RECORD...
OLDER STUFF, JUST FOR THE RECORD...
Line 1,168: Line 1,336:
ADVANCED/UNSUPPORTED: one day it might be possible to [https://github.com/iiab/iiab-factory/blob/master/content/vector-tiles/append2region.md combine multiple .mbtiles files] (vector map files, highlighting different regions) into a single .mbtiles file, using [https://github.com/iiab/iiab-factory/blob/master/content/vector-tiles/append2region append2region].
ADVANCED/UNSUPPORTED: one day it might be possible to [https://github.com/iiab/iiab-factory/blob/master/content/vector-tiles/append2region.md combine multiple .mbtiles files] (vector map files, highlighting different regions) into a single .mbtiles file, using [https://github.com/iiab/iiab-factory/blob/master/content/vector-tiles/append2region append2region].


ALTERNATIVE MAPS: the 10-layer http://oer2go.org/viewmod/en-worldmap-10 (10.7GB) can be downloaded to /library/www/html/modules.  Its map data is not as comprehensive as IIAB's 2018 or 2019 maps, and it lacks satellite photos, but it does cover the bases well with basic global maps.  One Catch: this download can take hours, as it includes a huge number of small files.
ALTERNATIVE MAPS: the 10-layer https://rachel.worldpossible.org/viewmod/en-worldmap-10 (10.7GB) can be downloaded to /library/www/html/modules.  Its map data is not as comprehensive as IIAB's 2018 or 2019 maps, and it lacks satellite photos, but it does cover the bases well with basic global maps.  One Catch: this download can take hours, as it includes a huge number of small files. -->


== WordPress & Moodle Administration: What tips & tricks exist? ==
== WordPress & Moodle Administration: What tips & tricks exist? ==
Line 1,178: Line 1,346:
* If you must change it later, follow the WordPress instructions for [https://wordpress.org/support/article/changing-the-site-url/ Changing The Site URL] which offers 5 different ways to get this done, 2 of which involved editing <code>/library/wordpress/wp-config.php</code>
* If you must change it later, follow the WordPress instructions for [https://wordpress.org/support/article/changing-the-site-url/ Changing The Site URL] which offers 5 different ways to get this done, 2 of which involved editing <code>/library/wordpress/wp-config.php</code>


'''How do I optimize WordPress and Moodle for high-traffic usage?'''
* Please review your options at [https://github.com/iiab/iiab/issues/3071 #3071].
 
'''How do I optimize Matomo or PBX or WordPress for high-traffic usage?'''


* Set <code>nginx_high_php_limits: True</code> in [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|/etc/iiab/local_vars.yml]] (NOTE: IIAB enables these settings for Moodle automatically, as of July 2021.)
* Set <code>nginx_high_php_limits: True</code> in [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|/etc/iiab/local_vars.yml]] (NOTE: IIAB enables these [https://github.com/iiab/iiab/blob/aabd59cc8ef459cad0b41d31251f2fb988bf663f/roles/www_options/tasks/php-settings.yml#L84-L110 higher settings] for Moodle and Nextcloud automatically, as of August 2023.)


* Then run as root: "cd /opt/iiab/iiab && sudo ./runrole www_options && sudo reboot"
* Then run <code>cd /opt/iiab/iiab</code> followed by <code>sudo ./runrole www_options</code> and then reboot.


* ''Of course, make sure your Internet-in-a-Box has enough RAM and disk!''  Background: [https://github.com/iiab/iiab/issues/1147 #1147]
* ''Of course, make sure your Internet-in-a-Box has enough RAM and disk!''  Background: [https://github.com/iiab/iiab/issues/1147 #1147]


Optionally you might further customize the 6 settings ''{upload_max_filesize, post_max_size, max_execution_time, max_input_time, memory_limit, max_input_vars}'' in <code>/etc/php/<ACTUAL VERSION NUMBER>/fpm/php.ini</code> (reboot if so!)  This can also be done prior to IIAB's install, about halfway down [https://github.com/iiab/iiab/blob/master/roles/www_options/tasks/main.yml#L88-L131 /opt/iiab/iiab/roles/www_options/tasks/main.yml]
Optionally you might further customize the 6 settings ''{upload_max_filesize, post_max_size, max_execution_time, max_input_time, memory_limit, max_input_vars}'' in both <code>/etc/php/<ACTUAL VERSION NUMBER>/*/php.ini</code> files (reboot if so!)  This is best done prior to IIAB's install, within [https://github.com/iiab/iiab/blob/master/roles/www_options/tasks/php-settings.yml /opt/iiab/iiab/roles/www_options/tasks/php-settings.yml]


'''How do I copy a complete installation of WordPress to another Internet-in-a-Box?'''
'''How do I copy a complete installation of WordPress to another Internet-in-a-Box?'''
Line 1,194: Line 1,364:
'''How do I integrate IIAB Apps and Content Packs (and custom menuing!) into a larger WordPress site?'''
'''How do I integrate IIAB Apps and Content Packs (and custom menuing!) into a larger WordPress site?'''


Please see Joshua Kanani's WordPress plugin [https://github.com/kananigit/iiab-menu-plugin#internet-in-a-box-menu-plugin instructions].  Thank you for providing [[#What_are_the_best_places_for_community_support.3F|feedback]] in support of this emerging effort!
Please see Joshua Kanani's WordPress plugin [https://github.com/kananigit/iiab-menu-plugin#internet-in-a-box-menu-plugin instructions].  Thank you for providing [[#What_are_the_best_places_for_community_support%3F|feedback]] in support of this emerging effort!


'''How do I set the Moodle URL (like http://box.lan/moodle) so it works for everyone?'''
'''How do I set the Moodle URL (like http://box.lan/moodle) so it works for everyone?'''


* Most prefer to modify <code>/opt/iiab/moodle/config.php</code> including their customized school URL in a line like <code>$CFG->wwwroot = 'http://192.168.0.100/moodle';</code> or <code>$CFG->wwwroot = 'http://myschool.mydomain/moodle';</code>
* Most prefer to modify <code>/opt/iiab/moodle/config.php</code> including their customized school URL in a line like <code>$CFG->wwwroot = 'http://192.168.0.100/moodle';</code> or <code>$CFG->wwwroot = 'http://myschool.mydomain/moodle';</code>
* Please review your options at [https://github.com/iiab/iiab/issues/941 #941].
* Please review your options at [https://github.com/iiab/iiab/issues/941 #941] and [https://github.com/iiab/iiab/issues/3071#issuecomment-997212470 #3071].
 
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|What is local_vars.yml and how do I customize it?]]<br>
See: [[#Can_I_upgrade_or_reinstall_server_apps.3F|Can I upgrade or reinstall server apps?]]<br>
See: [[#Is_campuswide_access_possible_for_all_server_apps.3F|Is campuswide access possible for all server apps?]]


== Elgg Administration: What tips & tricks exist? ==
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|What is local_vars.yml and how do I customize it?]]<br>
See: [[#Can_I_upgrade_or_reinstall_server_apps%3F|Can I upgrade or reinstall server apps?]]<br>
See: [[#Is_campuswide_access_possible_for_all_server_apps%3F|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.
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.
Line 1,215: Line 1,384:
'''More Documentation?''' Please see the original [https://github.com/iiab/iiab/tree/master/roles/elgg#elgg-readme Elgg README].
'''More Documentation?''' Please see the original [https://github.com/iiab/iiab/tree/master/roles/elgg#elgg-readme Elgg README].


See: [[#What_are_the_default_passwords?|What are the default passwords?]]<br>
See: [[#What_are_the_default_passwords%3F|What are the default passwords?]]<br>
See: [[#Can_I_upgrade_or_reinstall_server_apps.3F|Can I upgrade or reinstall server apps?]]
See: [[#Can_I_upgrade_or_reinstall_server_apps%3F|Can I upgrade or reinstall server apps?]] -->
 
== How do I add TuxMath? ==
 
Run this:
 
  sudo -i
  cd /library/www/html/modules
  git clone https://gitlab.com/Afrikalan/tuxmath-js --depth 1
  rm -rf tuxmath-js/.git*
 
Using Admin Console, [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/ContentMenus.rst set up a menu item] on your IIAB home page, to help students access http://box/modules/tuxmath-js
 
See: [[#How_do_I_customize_my_Internet-in-a-Box_home_page%3F|How do I customize my Internet-in-a-Box home page?]]<br>
 
== How do I add Scratch-like “Snap!” ? ==
 
Run this:
 
  sudo -i
  cd /library/www/html/modules
  git clone https://github.com/jmoenig/Snap en-snap -b v9.2.13 --depth 1
  rm -rf en-snap/.git*
 
Using Admin Console, [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/ContentMenus.rst set up a menu item] on your IIAB home page, to help students access http://box/modules/en-snap (or similar!)
 
Examples:
 
* [https://github.com/iiab-share/js-menu-files/blob/master/menu-defs/en-snap.json en-snap.json]
* [https://github.com/iiab-share/js-menu-files/blob/master/menu-defs/es-snap.json es-snap.json]
* [https://github.com/iiab-share/js-menu-files/blob/master/menu-defs/fr-snap.json fr-snap.json]
 
See: [[#How_do_I_customize_my_Internet-in-a-Box_home_page%3F|How do I customize my Internet-in-a-Box home page?]]<br>


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


When installed on Raspberry Pi OS, 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.
When installed on Raspberry Pi OS, 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://10.10.10.10) 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.
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.
Line 1,229: Line 1,430:




'''Captive Portal is installed but not enabled in [https://github.com/iiab/iiab/wiki/IIAB-7.1-Release-Notes IIAB 7.1], but here are instructions to enable it:'''
'''Captive Portal is installed but not enabled in [https://github.com/iiab/iiab/wiki/IIAB-8.1-Release-Notes IIAB 8.1].  Here are instructions to enable it:'''


* sudo su -
* sudo -i


* Run 'nano /etc/iiab/local_vars.yml' to set both these variables: (around Lines 100-101)
* Run 'nano /etc/iiab/local_vars.yml' to set both these variables: (typically around Lines 379-380)


   captiveportal_install: True
   captiveportal_install: True
Line 1,245: Line 1,446:
'''Conversely, note that many schools prefer to disable Captive Portal entirely, which can be done as follows:'''
'''Conversely, note that many schools prefer to disable Captive Portal entirely, which can be done as follows:'''


* sudo su -
* sudo -i


* Run 'nano /etc/iiab/local_vars.yml' to set this variable to False: (around Line 101)
* Run 'nano /etc/iiab/local_vars.yml' to set this variable to False: (typically around Line 342)


   captiveportal_enabled: False
   captiveportal_enabled: False
Line 1,257: Line 1,458:
<!--'''Or in a pinch you can disable Captive Portal right away, by running:'''
<!--'''Or in a pinch you can disable Captive Portal right away, by running:'''


* sudo su -
* sudo -i


* rm /etc/dnsmasq.d/capture
* rm /etc/dnsmasq.d/capture
Line 1,274: Line 1,475:


See: [[#My_Android_device_says_.22Connected.2C_no_Internet.22_and_won.27t_browse_http:.2F.2Fbox|My Android device says "Connected, no Internet" and won't browse http://box]]<br>
See: [[#My_Android_device_says_.22Connected.2C_no_Internet.22_and_won.27t_browse_http:.2F.2Fbox|My Android device says "Connected, no Internet" and won't browse http://box]]<br>
See: [[#Any_other_networking_tips.3F|Any other networking tips?]]<br>
See: [[#Any_other_networking_tips%3F|Any other networking tips?]]<br>
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|What is local_vars.yml and how do I customize it?]]
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|What is local_vars.yml and how do I customize it?]]
 
<!--== How can I try XO laptop services? ==
<!--== How can I try XO laptop services? ==


Starting with [http://wiki.laptop.org/go/IIAB/6.5 IIAB 6.5+], you can test XO laptop services by uncommenting lines under "5-XO-SERVICES"  within /etc/iiab/local_vars.yml
Starting with [https://wiki.laptop.org/go/IIAB/6.5 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" being patient until it finishes.
Finally, run "cd /opt/iiab/iiab" then "./iiab-install --reinstall" being patient until it finishes.


See: [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|What is local_vars.yml and how do I customize it?]]<br>
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|What is local_vars.yml and how do I customize it?]]<br>


== Can my XO-based server boot with a unique startup sound? ==
== Can my XO-based server boot with a unique startup sound? ==
Line 1,289: Line 1,489:
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.
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 [http://wiki.laptop.org/go/XS_Community_Edition/Features/Startup_sound instructions] for adding a unique startup sound.-->
Here are [https://wiki.laptop.org/go/XS_Community_Edition/Features/Startup_sound instructions] for adding a unique startup sound.-->


== Is campuswide access possible for all server apps? ==
== Is campuswide access possible for all server apps? ==
Line 1,301: Line 1,501:
ASIDE: efforts are ongoing to make [https://github.com/iiab/iiab/issues/923 snappy/mnemonic URL's] (like http://box/books) in support of teachers' and medical clinics' desires to rapidly onramp information literacy among new users.
ASIDE: efforts are ongoing to make [https://github.com/iiab/iiab/issues/923 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?|What security tips exist?]]
See: [[#What_security_tips_exist%3F|What security tips exist?]]<br>
See: [[#WordPress_.26_Moodle_Administration:_What_tips_.26_tricks_exist%3F|WordPress & Moodle Administration: What tips & tricks exist?]]


== Is there a file like AUTOEXEC.BAT to run jobs on boot? ==
== Is there a file like AUTOEXEC.BAT to run jobs on boot? ==
Line 1,315: Line 1,516:
Format the USB drive with the ext4 filesystem:
Format the USB drive with the ext4 filesystem:


   mkfs.ext4 /dev/sdX
   mkfs.ext4 /dev/sdX   # Or if the device is partitioned: mkfs.ext4 /dev/sdXN


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".
Before running the above, change 'X' (and 'N' if necessary) to correspond to your actual USB drive.  You can uncover this (its device name) by running commands like <code>lsblk</code> or <code>blkid</code> with <code>df -h</code>.


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


   e2label /dev/sdX IIAB-LIBRARY-EXT
   e2label /dev/sdX IIAB-LIBRARY-EXT    # Or if the device is partitioned: e2label /dev/sdXN IIAB-LIBRARY-EXT


Put this line (using the same label as above) into your IIAB's <code>/etc/fstab</code>
Put this line (using the same label as above) into your IIAB's [https://en.wikipedia.org/wiki/Fstab /etc/fstab]


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


Create the needed mount point on IIAB, by running:
Alternatively, a popular option is to put ALL your content in the ''USB drive's own'' top-level <code>library</code> folder.  (This works well with [[#How_do_I_customize_my_Internet-in-a-Box_home_page%3F|'''Admin Console''']] -> '''Install Content''' -> [https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/InstContent.rst#manage-content '''Manage Content'''] to import/export content.)  BONUS: If you choose this approach, you can avoid creating the symbolic link[s] mentioned further below!
 
  LABEL=IIAB-LIBRARY-EXT  /library-ext  ext4  defaults,nofail      0  0
  /library-ext/library    /library      none  defaults,bind,nofail  0  0
 
Either way, create the needed mount point on your IIAB, by running:


   mkdir /library-ext
   mkdir /library-ext


After you've tested that your USB drive automounts correctly on boot, create the symbolic link(s) you need &mdash; so that IIAB can find any Content Packs you've placed on the external USB drive.
After you've tested that your USB drive automounts correctly on boot, create any symbolic link(s) you need &mdash; 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 <code>/library-ext/www/html/modules/</code> when mounted)
Example command: (if for example you placed all your OER2Go/RACHEL modules onto the external USB drive, so they appear as <code>/library-ext/www/html/modules/</code> when mounted)
Line 1,341: Line 1,547:
CLARIF 2: If this USB drive is plugged into another Linux computer, the above example folder might automount differently, e.g. appearing as <code>/media/usb/www/html/modules</code>
CLARIF 2: If this USB drive is plugged into another Linux computer, the above example folder might automount differently, e.g. appearing as <code>/media/usb/www/html/modules</code>


CLARIF 3: When copying large Content Packs, we strongly recommend the <code>rsync -av</code> command, so that files are not lost and the copy process can continue if interrupted — while preserving ownership and timestamps.
CLARIF 3: Use the very same IIAB to set up and verify that the external USB drive's file ownership and read/write permissions work (e.g. use Linux commands <code>chown</code> and <code>chmod</code> if necessary).
 
CLARIF 4: When copying large Content Packs, we strongly recommend the <code>rsync -av</code> command, so that files are not lost and the copy process can continue if interrupted — while preserving ownership and timestamps.
 
CLARIF 5: Another way to do this (e.g. on a more temporary basis) is "bind mounting" as mentioned at [https://github.com/iiab/iiab/issues/2679 #2679], [https://github.com/iiab/iiab/issues/3106 #3106] and [https://unix.stackexchange.com/questions/198590/what-is-a-bind-mount "What is a bind mount?"]
 
CLARIF 6: If your Linux OS has a graphical desktop, it's common to see popup message warnings like:
 
  Unable to mount 128 GB Volume
  Device /dev/sdb1 is already mounted at '/media/usb0'.


CLARIF 4: Another way to do this (e.g. on a more temporary basis) is "bind mounting" as mentioned at [https://github.com/iiab/iiab/issues/2679 #2679] and [https://unix.stackexchange.com/questions/198590/what-is-a-bind-mount "What is a bind mount?"]
It's safe to ignore these messages. Or you can make these popup messages go away, typically by clicking through your graphical File Manager's preferences or OS settings, and unchecking the box for "Mount removable media automatically when they are inserted" or "Automatically mount removable media when inserted and on startup." [https://github.com/iiab/iiab/issues/86 #86]


See: [[#Can_teachers_display_their_own_content.3F|Can teachers display their own content?]]<br>
See: [[#Can_teachers_display_their_own_content%3F|Can teachers display their own content?]]<br>
See: [[#How_do_I_customize_my_Internet-in-a-Box_home_page.3F|How do I customize my Internet-in-a-Box home page?]]<br>
See: [[#How_do_I_customize_my_Internet-in-a-Box_home_page%3F|How do I customize my Internet-in-a-Box home page?]]<br>
See: [[#How_do_I_add_ZIM_files.2C_like_Wikipedia.3F|How do I add ZIM files, like Wikipedia?]]<br>
See: [[#How_do_I_add_ZIM_files.2C_like_Wikipedia%3F|How do I add ZIM files, like Wikipedia?]]<br>
See: [[#Can_I_install_IIAB_onto_a_USB_drive.3F|Can I install IIAB onto a USB drive?]]<br>
See: [[#Can_I_install_IIAB_onto_a_USB_drive%3F|Can I install IIAB onto a USB drive?]]<br>


== Can I install IIAB onto a USB drive? ==
== Can I install IIAB onto a USB drive? ==
Line 1,354: Line 1,569:
''This can fail with consumer-grade hardware,'' because the boot device's USB 3.0 frequencies (e.g. radiating from a USB flash drive, Raspberry Pi "hat" or other peripheral — especially those lacking a ferrite [https://en.wikipedia.org/wiki/Ferrite_bead RF choke] and/or lacking proper USB3 cable shielding) very often interfere with the Raspberry Pi's internal Wi-Fi.
''This can fail with consumer-grade hardware,'' because the boot device's USB 3.0 frequencies (e.g. radiating from a USB flash drive, Raspberry Pi "hat" or other peripheral — especially those lacking a ferrite [https://en.wikipedia.org/wiki/Ferrite_bead RF choke] and/or lacking proper USB3 cable shielding) very often interfere with the Raspberry Pi's internal Wi-Fi.


As explained in [https://github.com/iiab/iiab/issues/2638 #2638], [https://github.com/raspberrypi/firmware/issues/1430 raspberrypi/firmware#1430] and this Intel White Paper:
As explained in [https://github.com/iiab/iiab/issues/2638 #2638], [https://github.com/raspberrypi/firmware/issues/1430 raspberrypi/firmware#1430] and this 2012 Intel White Paper:


   USB 3.0 Radio Frequency Interference Impact on 2.4GHz Wireless Devices
   USB 3.0 Radio Frequency Interference Impact on 2.4GHz Wireless Devices
   https://www.intel.com/content/www/us/en/products/docs/io/universal-serial-bus/usb3-frequency-interference-paper.html
 
   https://www.usb.org/document-library/usb-30-radio-frequency-interference-impact-24-ghz-wireless-devices (PDF)


DO THIS FIRST: A 1st order test of the quality of your hardware is to set up USB 3.0 boot '''(do this prior to installing IIAB)''' then connect to your building's 2.4GHz (NOT 5GHz !) Wi-Fi &mdash; without an Ethernet cable!  Then carefully test web/online tasks like running <code>apt update</code>, downloading large files, <code>ping mit.edu</code>, etc &mdash; ''evaluating packet loss over many minutes to be sure.''  (If your hardware/layout cannot function reliably as a Wi-Fi client device, don't even bother trying to set it up as an Internet-in-a-Box learning hotspot!)
DO THIS FIRST: A 1st order test of the quality of your hardware is to set up USB 3.0 boot '''(do this prior to installing IIAB)''' then connect to your building's 2.4GHz (NOT 5GHz !) Wi-Fi &mdash; without an Ethernet cable!  Then carefully test web/online tasks like running <code>apt update</code>, downloading large files, <code>ping mit.edu</code>, etc &mdash; ''evaluating packet loss over many minutes to be sure.''  (If your hardware/layout cannot function reliably as a Wi-Fi client device, don't even bother trying to set it up as an Internet-in-a-Box learning hotspot!)
Line 1,367: Line 1,583:
THEFT WARNING: Of course there is a risk your USB (flash or hard disk) drive might be stolen, as there's always a temptation for others to "borrow" external USB devices.  For many similar/such practical reasons, an IIAB microSD card (placed inside the Raspberry Pi) usually makes much more sense.
THEFT WARNING: Of course there is a risk your USB (flash or hard disk) drive might be stolen, as there's always a temptation for others to "borrow" external USB devices.  For many similar/such practical reasons, an IIAB microSD card (placed inside the Raspberry Pi) usually makes much more sense.


PRIVACY AND SECURITY WARNING: If you're booting from a USB device (e.g. an external disk or flash drive) please set <code>usb_lib_enabled: False</code> in /etc/iiab/local_vars.yml prior to installing IIAB, so that your filesystem is not viewable at http://box/usb.  You can also do this after installing IIAB, using Admin Console (http://box.lan/admin) > Content > Services Enabled > USB based content libraries (uncheck the checkbox) > Save Configuration > Install Configured Options &mdash; give it 1-2 minutes and then verify that this completed in Utilities (menu) > Display Job Status &mdash; and finally reboot. ([https://github.com/iiab/iiab/issues/2552 #2552])
PRIVACY AND SECURITY WARNING: If you're booting from a USB device (e.g. an external disk or flash drive) please set <code>usb_lib_enabled: False</code> in /etc/iiab/local_vars.yml prior to installing IIAB, so that your filesystem is not viewable at http://box/usb.  You can also do this after installing IIAB, using '''Admin Console''' (http://box.lan/admin) '''> Content > Services Enabled > USB based content libraries''' (uncheck the checkbox) '''> Save Configuration > Install Configured Options''' &mdash; give it 1-2 minutes and then verify that this completed in '''Utilities''' (menu) '''> Display Job Status''' &mdash; and finally reboot. ([https://github.com/iiab/iiab/issues/2552 #2552])


See: [[#What_hardware_should_I_use.3F|What hardware should I use?]]<br>
See: [[#What_hardware_should_I_use%3F|What hardware should I use?]]<br>
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it.3F|What is local_vars.yml and how do I customize it?]]<br>
See: [[#What_is_local_vars.yml_and_how_do_I_customize_it%3F|What is local_vars.yml and how do I customize it?]]<br>
See: [[#Can_I_permanently_attach_an_external_USB_drive,_to_add_more_content?|Can I permanently attach an external USB drive, to add more content?]]
See: [[#Can_I_permanently_attach_an_external_USB_drive,_to_add_more_content%3F|Can I permanently attach an external USB drive, to add more content?]]


== How do I back up, shrink & copy IIAB microSD cards? ==
== How do I back up, shrink & copy IIAB microSD cards? ==
Line 1,377: Line 1,593:
Privacy Practices for removing student/teacher personal data and protecting medical confidentiality will emerge at [https://github.com/iiab/iiab/issues/1516 #1516] and/or [[Security]].
Privacy Practices for removing student/teacher personal data and protecting medical confidentiality will emerge at [https://github.com/iiab/iiab/issues/1516 #1516] and/or [[Security]].


IIAB communities around the world would '''love''' your help making a 1-to-2 minute [https://github.com/iiab/iiab/issues/1601#issuecomment-494176251 "Offline YouTube" (friendly screencast)] outlining the best approach(es) below &mdash; and how to use them &mdash; please if you can, do consider making any such very short video!
IIAB communities around the world would ''LOVE'' your help making a 1-to-2 minute [https://github.com/iiab/iiab/issues/1601#issuecomment-494176251 "Offline YouTube" (friendly screencast)] outlining the best approach(es) below &mdash; and how to use them &mdash; please if you can, do consider making any such very short video!


1. Self-Clone your entire Internet-in-a-Box (IIAB) e.g. to an external microSD card, using IIAB's Admin Console: http://box.lan/admin > Install Content > Clone IIAB ([https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/InstContent.rst#clone-iiab-server details]).
1. Self-Clone your entire Internet-in-a-Box (IIAB) e.g. to an external microSD card, using IIAB's '''Admin Console''' http://box.lan/admin '''> Install Content > Clone IIAB''' ([https://github.com/iiab/iiab-admin-console/blob/master/roles/console/files/help/InstContent.rst#clone-iiab-server details]).
:* ''This approach works to copy to another brand/model of microSD card that happens to be a few bytes smaller!''
:* ''This approach works to copy to another brand/model of microSD card that happens to be a few bytes smaller!''
:* Copy from your IIAB's internal microSD to an external microSD (placed in a microSD card reader/writer, that plugs into one of your IIAB's USB ports).
:* Copy from your IIAB's internal microSD to an external microSD (placed in a microSD card reader/writer, that plugs into one of your IIAB's USB ports).
:* This is based on [https://github.com/georgejhunt/piclone_cmd piclone_cmd] which brings the Raspberry Pi's "SD Card Copier" approach below ([https://github.com/raspberrypi-ui/piclone piclone]) to the command-line, and other platforms and OS's (e.g. 64-bit Ubuntu not just 32-bit Raspberry Pi OS) ([https://github.com/iiab/iiab/issues/2268 #2268]).
:* This is based on [https://github.com/georgejhunt/piclone_cmd piclone_cmd] (similar to [https://github.com/billw2/rpi-clone rpi-clone]) which brings the Raspberry Pi's "SD Card Copier" approach below ([https://github.com/raspberrypi-ui/piclone piclone]) to the command-line, and other platforms and OS's (e.g. 64-bit Ubuntu not just 32-bit Raspberry Pi OS) ([https://github.com/iiab/iiab/issues/2268 #2268]).
:* This approach can be slower than 3. and 4. (below) but is far easier to understand (and a real lifesaver in the field, when duplication hardware/peripherals/adapters are often scarce!)
:* This approach can be slower than 3. and 4. (below) but is far easier to understand (and a real lifesaver in the field, when duplication hardware/peripherals/adapters are often scarce!)
:* 2022-09-09 WARNING: PLEASE USE APPROACH 2. (BELOW) IF POSSIBLE &mdash; AS APPROACH 1. (ABOVE) OFTEN FAILS TO START PROPERLY WITHIN THE 1ST MINUTE ([https://github.com/iiab/iiab/issues/3362 #3362]).


2. Likewise a very easy/friendly approach is possible if you have access to the "Desktop" (graphical) version of Raspberry Pi OS.  Simply click the Raspberry start icon (top-left of screen) > Accessories > SD Card Copier:
2. Likewise a very easy/friendly approach is possible if you have access to the "Desktop" (graphical) version of Raspberry Pi OS.  Simply click the '''Raspberry start menu''' (top-left of screen) '''> Accessories > SD Card Copier''':


:* ''This approach works to copy to another brand/model of microSD card that happens to be a few bytes smaller!''
:* ''This approach works to copy to another brand/model of microSD card that happens to be a few bytes smaller!''
Line 1,391: Line 1,608:
:* You can also copy one external microSD card to another, if you have 2 microSD card readers/writers.
:* You can also copy one external microSD card to another, if you have 2 microSD card readers/writers.
:* Instructions:
:* Instructions:
:** Read the "SD card copier" section which is the third headlined section in "[https://www.raspberrypi.org/blog/another-update-raspbian/ The latest update to Raspberry Pi OS]" (below sections "Bluetooth" and "Bluetooth audio") from May 13, 2016.  Likewise you can read the equivalent text underlying its [https://github.com/raspberrypi-ui/piclone/blob/master/data/piclone.ui#L152-L166 Help screen].
:** Read its [https://github.com/raspberrypi-ui/piclone/blob/master/data/piclone.ui#L303-L315 Help screen instructions].  For a quick summary from the original May 13, 2016 announcement, see the "SD card copier" section which is the third headlined section in "[https://www.raspberrypi.com/news/another-update-raspbian/ The latest update to Raspberry Pi OS]" (look below sections "Bluetooth" and "Bluetooth audio").
:** The underlying command is [https://github.com/raspberrypi-ui/piclone piclone].
:** The underlying command is [https://github.com/raspberrypi-ui/piclone piclone].
:** This approach can be slower than 3. and 4. (below) but is far easier to understand (and a real lifesaver in the field, when duplication hardware/peripherals/adapters are often scarce!)
:** This approach can be slower than 3. and 4. (below) but is far easier to understand (and a real lifesaver in the field, when duplication hardware/peripherals/adapters are often scarce!)


3. On Linux or macOS, we strongly recommend the built-in command [https://www.linuxnix.com/what-you-should-know-about-linux-dd-command/ dd] if you are comfortable at the command-line.
3. On Linux or macOS, we strongly recommend the built-in command [https://linuxconfig.org/how-dd-command-works-in-linux-with-examples dd] <!-- [https://www.linuxnix.com/what-you-should-know-about-linux-dd-command/ dd] --> if you are comfortable at the command-line.


:* ''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 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 [https://github.com/iiab/iiab-factory/blob/master/box/rpi/howto-mkimg.txt min-sd and cp-sd] commands found [https://github.com/iiab/iiab-factory/tree/master/box/rpi here] (min-sd is the underlying magic that shrinks or truncates microSD cards, without any data loss).
:* If so, you can solve this using the [https://github.com/iiab/iiab-factory/blob/master/box/rpi/howto-mkimg.txt min-sd and cp-sd] commands found [https://github.com/iiab/iiab-factory/tree/master/box/rpi here] (min-sd is the underlying magic that shrinks or truncates microSD cards, without any data loss).
::* Or consider [https://www.ostechnix.com/pishrink-make-raspberry-pi-images-smaller/ PiShrink] ([https://github.com/Drewsif/PiShrink#pishrink README])
::* Or consider [https://www.ostechnix.com/pishrink-make-raspberry-pi-images-smaller/ PiShrink] ([https://github.com/Drewsif/PiShrink#pishrink README])
::* Or consider [https://github.com/billw2/rpi-clone rpi-clone] by Bill Wilson.  As of 2024, consider [https://github.com/geerlingguy/rpi-clone Jeff Geerling's fork] ("A shell script to clone a booted disk on a Raspberry Pi") thanks to [https://github.com/framps @framp].
:* On macOS, 'dd' will run extremely slowly if you don't use macOS's own special syntax.  So we recommend this macOS recipe, as an example:
:* On macOS, 'dd' will run extremely slowly if you don't use macOS's own special syntax.  So we recommend this macOS recipe, as an example:
:#Insert a brand new microSD card
::*Insert a brand new microSD card
:#Determine mount point of card: <code>diskutil list</code>
::*Determine mount point of card: <code>diskutil list</code>
:#Unmount card (this presumes its mount point is /dev/disk2): <code>sudo diskutil unmountDisk /dev/disk2</code>
::*Unmount card (this presumes its mount point is /dev/disk2): <code>sudo diskutil unmountDisk /dev/disk2</code>
:#Copy source file (e.g. source.img) from Mac's disk to card: <code>sudo dd if=source.img of=/dev/rdisk2 bs=4m</code>
::*Copy source file (e.g. source.img) from Mac's disk to card: <code>sudo dd if=source.img of=/dev/rdisk2 bs=4m status=progress</code>
:#Eject card: <code>sudo diskutil eject /dev/disk2</code>
:::* ''Helpful Tip:'' The "r" device (e.g. <code>/dev/rdisk2</code> NOT <code>/etc/disk2</code>) is the raw one.  It should let you write 1 byte at a time, and is ~20X faster.
:::* ''Helpful Tip:'' If your macOS is older and <code>status=progress</code> doesn't work, you can type <code>ctrl-T</code> at the shell running dd to send it the INFO signal, to provide you a snapshot of how much has been transferred.
::*Eject card: <code>sudo diskutil eject /dev/disk2</code>


4.1 On Windows 10, strongly consider [https://github.com/filipxsikora/dotnet-disk-imager dotNet Disk Imager] which is a "dotNet equivalent to Win32 Disk Imager, but more lightweight and with more features."  [Several of us use this on Windows 8 and Windows 10, e.g. Tim Moody writes: "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"].
4.1 On Windows 10/11, strongly consider [https://github.com/filipxsikora/dotnet-disk-imager dotNet Disk Imager] which is a "dotNet equivalent to Win32 Disk Imager, but more lightweight and with more features."  [Several of us use this on Windows 8 and Windows 10, e.g. Tim Moody writes: "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"].


:* ''If however you're copying to a different brand/model of microSD card that happens to be a few bytes smaller, consider minimizing/truncating IIAB's main ext4 partition using [http://www.eassos.com/partitionguru.php DiskGenius (formerly PartitionGuru)] with these instructions:''
:* ''If however you're copying to a different brand/model of microSD card that happens to be a few bytes smaller, consider minimizing/truncating IIAB's main ext4 partition using [https://www.eassos.com/partitionguru.php DiskGenius (formerly PartitionGuru)] with these instructions:''
:** [https://www.eassos.com/blog/how-to-resize-ext4-linux-partition-without-data-loss-on-windows/ How to resize EXT4 Linux partition without data loss on Windows10/8/7?]''
:** [https://www.eassos.com/blog/how-to-resize-ext4-linux-partition-without-data-loss-on-windows/ How to resize EXT4 Linux partition without data loss on Windows10/8/7?]''
:*** [https://www.eassos.com/how-to/how-to-resize-a-partition.php How To Resize A Partition]
:*** [https://www.eassos.com/how-to/how-to-resize-a-partition.php How To Resize A Partition]
:** [https://www.eassos.com/blog/how-to-backup-clone-raspberry-pi-sd-card-on-windows/ How to backup/clone Raspberry Pi SD card on Windows?]
:** [https://www.eassos.com/blog/how-to-backup-clone-raspberry-pi-sd-card-on-windows/ How to backup/clone Raspberry Pi SD card on Windows?]
:* DiskGenius Professional software is $99.90 but it appears a [https://www.diskgenius.com/editions.php Free Trial] might also be available, while [https://www.diskgenius.com/download.php DiskGenius Free] and their older [http://www.eassos.com/partitionguru-free.php PartitionGuru Free] might possibly be missing the essential feature to shrink/minimize/truncate your ext4 partition?
:* DiskGenius Professional software is $99.90 but it appears a [https://www.diskgenius.com/editions.php Free Trial] might also be available, while [https://www.diskgenius.com/download.php DiskGenius Free] and their older [https://www.eassos.com/partitionguru-free.php PartitionGuru Free] might possibly be missing the essential feature to shrink/minimize/truncate your ext4 partition?


4.2 On Windows 7 or Windows 8 ''(must be prior to Windows 10!)'' consider the "Read" button in [https://sourceforge.net/projects/win32diskimager/ Win32 Disk Imager] to back up an IIAB microSD to your Windows hard disk:
4.2 On Windows 7 or Windows 8 ''(must be prior to Windows 10!)'' consider the "Read" button in [https://sourceforge.net/projects/win32diskimager/ Win32 Disk Imager] to back up an IIAB microSD to your Windows hard disk:
Line 1,420: Line 1,640:
:* 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"
:* 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.
:* ''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 [http://download.iiab.io/packages/imager/ IMAGER] software to back up, shrink (truncate) and copy Internet-in-a-Box microSD cards:
<!--3.3 Please try our prototype [https://download.iiab.io/packages/imager/ 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 [https://etcher.io/ Etcher.io] and [https://sourceforge.net/projects/win32diskimager/ Win32 Disk Imager]) as it permits you to use other manufacturers' microSD cards ''even when'' they are marginally smaller!
:* IMAGER does more than just make backups and duplicate (similar to [https://etcher.io/ Etcher.io] and [https://sourceforge.net/projects/win32diskimager/ 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-->
:* CLARIF: this only works on Windows as of IMAGER version 0.2-->


5. Is it possible [https://clonezilla.org/ Clonezilla] can do part of this job?  Clonezilla is free software for disk cloning, disk imaging, data recovery, and deployment.
5. Is it possible [https://clonezilla.org/ Clonezilla] can do part of this job?  Clonezilla (unlike [https://filezilla-project.org/ FileZilla]) is free software for disk cloning, disk imaging, data recovery, and deployment.


See: [[#How_do_I_customize_my_Internet-in-a-Box_home_page.3F|How do I customize my Internet-in-a-Box home page?]]<br>
See: [[#How_do_I_customize_my_Internet-in-a-Box_home_page%3F|How do I customize my Internet-in-a-Box home page?]]<br>
See: [[#Can_I_upgrade_or_reinstall_server_apps.3F|Can I upgrade or reinstall server apps?]]<br>
See: [[#Can_I_upgrade_or_reinstall_server_apps%3F|Can I upgrade or reinstall server apps?]]<br>
See: [[#What_security_tips_exist?|What security tips exist?]]<br>
See: [[#What_security_tips_exist%3F|What security tips exist?]]<br>
See: [[#Can_I_permanently_attach_an_external_USB_drive,_to_add_more_content?|Can I permanently attach an external USB drive, to add more content?]]<br>
See: [[#Can_I_permanently_attach_an_external_USB_drive,_to_add_more_content%3F|Can I permanently attach an external USB drive, to add more content?]]<br>
See: [[#Can_I_install_IIAB_onto_a_USB_drive.3F|Can I install IIAB onto a USB drive?]]<br>
See: [[#Can_I_install_IIAB_onto_a_USB_drive%3F|Can I install IIAB onto a USB drive?]]<br>


== What are the best places for community support? ==
== What are the best places for community support? ==


<!--Start with-->
<!--Start with-->
<!--http://IIAB.io forums,-->
<!--https://IIAB.io forums,-->
<!--[https://webchat.freenode.net/?channels=#schoolserver live chat on irc] or post to one of-->
<!--[https://webchat.freenode.net/?channels=#schoolserver live chat on irc] or post to one of-->
<!--As our community forums are being rebuilt ([https://github.com/iiab/iiab/issues/1759 #1759]) please consider the "Discussion" page at Wikipedia's [https://meta.wikimedia.org/wiki/Internet-in-a-Box Internet-in-a-Box Meta-Wiki] &mdash; and -->
<!--As our community forums are being rebuilt ([https://github.com/iiab/iiab/issues/1759 #1759]) please consider the "Discussion" page at Wikipedia's [https://meta.wikimedia.org/wiki/Internet-in-a-Box Internet-in-a-Box Meta-Wiki] &mdash; and -->


'''''The fastest response will arise if you post a "New issue" here:'''''
1) '''''The fastest response will arise if you post a "New issue" here:'''''


* [https://github.com/iiab/iiab/issues github.com/iiab/iiab/issues]
* [https://github.com/iiab/iiab/issues github.com/iiab/iiab/issues]
Line 1,446: Line 1,666:
'''''Those who do not have GitHub accounts should consider creating one.'''''
'''''Those who do not have GitHub accounts should consider creating one.'''''


'''''Describe your issue in full (with context) so that others may help &mdash; including screenshots if possible, and output from the [https://github.com/iiab/iiab/blob/master/scripts/iiab-diagnostics.README.md <code>sudo iiab-diagnostics</code>] command (including the actual pastebin URL, Thanks!)'''''
'''''Describe your issue in full (with context) so that others may help &mdash; including screenshots if possible &mdash; and the ACTUAL PASTEBIN URL that is generated after you run [https://github.com/iiab/iiab/blob/master/scripts/iiab-diagnostics.README.md <code>sudo iiab-diagnostics</code>]'''''
<!--'''''Include context (and especially, the URL generated by the 'iiab-diagnostics' command) so that others can fully reproduce the issue you are facing, Thanks!'''''-->
<!--'''''Include context (and especially, the URL generated by the 'iiab-diagnostics' command) so that others can fully reproduce the issue you are facing, Thanks!'''''-->


While you can write to bugs @ iiab.io, we apologize that a response is ''NOT'' guaranteed.
2) Or consider posting to our technical discussion forum:
<!--If you need live (irc) chat support from global volunteers, but have intermittent Internet, consider an intermediary computer ([https://en.wikipedia.org/wiki/BNC_(software)#IRC irc bouncer]).  An irc bouncer accumulates irc responses when you're offline.  This enables you to follow the flow of conversations that are ongoing 24x7, when you return online.  Finally, if you're a regular contributor to Internet-in-a-Box, we can help arrange an irc bouncer for you.  If so please get in touch, and please see [https://docs.google.com/document/d/1LofncyUS90gO8DFgDJZKLf2DPnEUlJe0MVoa5-i7L8A/edit Reno McKenzie's irc instructions].-->
 
* https://github.com/iiab/iiab/discussions
 
3) For field/community topics, consider getting in touch using Twitter:
 
* [https://twitter.com/internet_in_box @internet_in_box]
<!-- 4) Consider also our Community/Design calls, that take place live most every Thursday, at 10AM NYC Time, off of: http://MINUTES.IIAB.IO -->
 
4) And don't hesitate to also write to our mailing list!


Consider also our Community/Design calls, that take place live most every Thursday, at 10AM NYC Time, off of: http://MINUTES.IIAB.IO
* [https://groups.google.com/group/unleashkids groups.google.com/group/unleashkids]
<!-- * [http://lists.laptop.org/pipermail/server-devel/ lists.laptop.org/pipermail/server-devel/] &nbsp; &nbsp; ''FOCUS: technology/networking/upgrading'' -->


Don't hesitate also to write to these 2 mailing lists:
''FOCUS: teachers/content/learning/libraries.''
Please take inspiration from our earlier work with almost a thousand "One Laptop Per Child" global grassroots communities, enabling their nearby educational communities to connect on a local level, ''very powerfully and directly Helping Each Other:'' http://olpcMAP.net


* [https://groups.google.com/group/unleashkids groups.google.com/group/unleashkids] &nbsp; ''FOCUS: teachers/content/learning/libraries''
<!-- 4) While you can write to bugs @ iiab.io, we apologize that a response is ''NOT'' guaranteed.
* [http://lists.laptop.org/pipermail/server-devel/ lists.laptop.org/pipermail/server-devel/] &nbsp; &nbsp; ''FOCUS: technology/networking/upgrading''
<!--If you need live (irc) chat support from global volunteers, but have intermittent Internet, consider an intermediary computer ([https://en.wikipedia.org/wiki/BNC_(software)#IRC irc bouncer]).  An irc bouncer accumulates irc responses when you're offline. This enables you to follow the flow of conversations that are ongoing 24x7, when you return online. Finally, if you're a regular contributor to Internet-in-a-Box, we can help arrange an irc bouncer for you.  If so please get in touch, and please see [https://docs.google.com/document/d/1LofncyUS90gO8DFgDJZKLf2DPnEUlJe0MVoa5-i7L8A/edit Reno McKenzie's irc instructions].-->


Finally, please take inspiration from our earlier work with almost a thousand "One Laptop Per Child" global grassroots communities, enabling their nearby educational communities to connect on a local level, ''very powerfully and directly Helping Each Other:'' http://olpcMAP.net
5) BUSINESS CONTACT: if you need to get in touch regarding strategic alliances or partnerships with Internet-in-a-Box, please email Adam Holt (holt @ unleashkids.org).


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


See: [[#What_are_the_default_passwords?|What are the default passwords?]]<br>
See: [[#What_are_the_default_passwords%3F|What are the default passwords?]]<br>
See: [[#How_can_I_remotely_manage_my_Internet-in-a-Box.3F|How can I remotely manage my Internet-in-a-Box?]]<br>
See: [[#How_can_I_remotely_manage_my_Internet-in-a-Box%3F|How can I remotely manage my Internet-in-a-Box?]]<br>
See: [[#What_are_the_default_passwords?|What are the default passwords?]]<br>
See: [[#What_are_the_default_passwords%3F|What are the default passwords?]]<br>
See: [[#How_can_I_help.3F|How can I help?]]
See: [[#How_can_I_help%3F|How can I help?]]


== How can I help? ==
== How can I help? ==


Please see the '''[https://internet-in-a-box.org/pages/contributing.html Contributing]''' section of [https://internet-in-a-box.org Internet-in-a-Box.org]
Please see the '''[https://internet-in-a-box.org/contributing.html Contributing]''' section of [https://internet-in-a-box.org Internet-in-a-Box.org]
 
<!-- Take a look at our weekly '''[http://minutes.iiab.io Agenda/Minutes]''' to see what others are working on. --> <!--after getting to know https://iiab.io forums,-->
Take a look at our weekly '''[http://minutes.iiab.io Agenda/Minutes]''' to see what others are working on. <!--after getting to know http://iiab.io forums,-->


Technical developers please (1) look through the tasks in our [https://github.com/iiab/iiab/milestones upcoming milestones] and (2) consider our [https://github.com/iiab/iiab/wiki/IIAB-Contributors-Guide IIAB Contributors Guide].
Technical developers please (1) consider our '''[https://github.com/iiab/iiab/wiki/Technical-Contributors-Guide Technical Contributors Guide]''' and (2) look through the tasks in our '''[https://github.com/iiab/iiab/milestones upcoming milestones]'''.


Implementers and IT people can help us <i>improve this very (wiki i.e. editable) document</i> ([http://FAQ.IIAB.IO FAQ.IIAB.IO]) as well as Wikipedia's [https://meta.wikimedia.org/wiki/Internet-in-a-Box Internet-in-a-Box Meta-Wiki].
Implementers and IT people please contact us if you can help <i>improve this very (wiki i.e. editable) document</i> ([https://wiki.iiab.io/go/FAQ FAQ.IIAB.IO]) as well as our [https://github.com/iiab/iiab/wiki GitHub Tech Docs].  <!-- and Wikipedia's [https://meta.wikimedia.org/wiki/Internet-in-a-Box Internet-in-a-Box Meta-Wiki]. -->


Librarians, videographers and designers are needed to help us deepen our communications &mdash; please [[#What_are_the_best_places_for_community_support?|make contact]] directly if you're able to help!  With apologies that our original list of <!--http://wiki.laptop.org/go/XS_Community_Edition/Microtasks--> [https://github.com/iiab/iiab/labels/good%201st%20issue volunteer microtasks] is currently quite stale.
Librarians, videographers and designers are needed to help us deepen our communications &mdash; please [[#What_are_the_best_places_for_community_support%3F|make contact]] directly if you're able to help!  <!-- With apologies that our original list of --> <!--https://wiki.laptop.org/go/XS_Community_Edition/Microtasks--> <!-- [https://github.com/iiab/iiab/labels/good%201st%20issue volunteer microtasks] is currently quite stale. -->


The voices and participation of <i>in-field</i> implementers and teachers are always welcome (over WhatsApp or Skype if necessary, even if your English is not perfect!) as you are <i>the</i> 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~
The voices and participation of <i>in-field</i> implementers and teachers are always welcome (over WhatsApp or Skype if necessary, even if your English is not perfect!) as you are <i>the</i> 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:
Finally, everyone is encouraged to post ideas and suggestions to our community mailing list:


* https://groups.google.com/group/unleashkids &nbsp; ''FOCUS: teachers/content/learning/libraries''
* https://groups.google.com/group/unleashkids &nbsp; ''FOCUS: teachers/content/learning/libraries''
* http://lists.laptop.org/pipermail/server-devel/ &nbsp; &nbsp; ''FOCUS: technology/networking/upgrading''
<!-- * http://lists.laptop.org/pipermail/server-devel/ &nbsp; &nbsp; ''FOCUS: technology/networking/upgrading'' -->
 
Serious digital librarians are also invited us to join our content engineering calls, that occur on certain Saturdays, building off our <!--http://iiab.io/t/offliners-anonymous-crushing-it-content-yet/48--><!--http://boxing.team-->[http://OFF.NETWORK] Content Hackathon, refining "web scraping" techniques that make available entirely new (categories of) high-quality Content Packs.


In 2023, serious digital librarians and humanitarian scrapers are also invited to join our content engineering design discussions that bring together all countries — building off our original <!--http://iiab.io/t/offliners-anonymous-crushing-it-content-yet/48--><!--http://boxing.team-->[http://OFF.NETWORK Medical & Educational Content Hackathon] back in 2017 — but now refining "web scraping" techniques for entirely new (categories of) very-high-quality Content Packs.  Don't hesitate to [[#What_are_the_best_places_for_community_support%3F|make contact!]]
<!--
<hr>
<hr>


''This section below is years-old and needs a complete overhaul:<!--, as our work accelerates into important new areas-->
''This section below is years-old and needs a complete overhaul:<!--, as our work accelerates into important new areas-->
<!--
Take seriously the [https://wiki.laptop.org/go/XS_Community_Edition/Features#Features_Planned "Features Planned"]] section of our [https://wiki.laptop.org/go/XS_Community_Edition/Features Features] page helping schools globally getting their highest priorities implemented.


Take seriously the [http://wiki.laptop.org/go/XS_Community_Edition/Features#Features_Planned "Features Planned"]] section of our [http://wiki.laptop.org/go/XS_Community_Edition/Features Features] page helping schools globally getting their highest priorities implemented.
Schools greatly benefit from [https://wiki.laptop.org/go/XS_Community_Edition/0.4/Testing testing on diverse hardware]] if you can help!  Online contribution are strongly welcome, with in-person human interaction at our <!--[[XS_Community_Edition/7.0/Sprint|--> <!-- quasi-quarterly face-to-face meetups advancing our education efforts faster yet.
 
Schools greatly benefit from [http://wiki.laptop.org/go/XS_Community_Edition/0.4/Testing testing on diverse hardware]] if you can help!  Online contribution are strongly welcome, with in-person human interaction at our <!--[[XS_Community_Edition/7.0/Sprint|--> quasi-quarterly face-to-face meetups advancing our education efforts faster yet.


Finally, organizing everyone's [http://wiki.laptop.org/go/XS_Community_Edition/Vision many ideas], [http://wiki.laptop.org/go/XS_Community_Edition/Use_Cases use cases] and [[#What_technical_documentation_exists.3F|docs]] is real work, and as such we very strongly welcome savvy communicators!
Finally, organizing everyone's [https://wiki.laptop.org/go/XS_Community_Edition/Vision many ideas], [https://wiki.laptop.org/go/XS_Community_Edition/Use_Cases use cases] and [[#What_technical_documentation_exists%3F|docs]] is real work, and as such we very strongly welcome savvy communicators!
<!--Please also suggest ''your own ideas'' on mailing list [http://lists.laptop.org/listinfo/server-devel server-devel@lists.laptop.org], or contact [http://wiki.laptop.org/go/User:Holt Adam Holt] (holt @ unleashkids.org), thanks!-->
-->
<!--Please also suggest ''your own ideas'' on mailing list [http://lists.laptop.org/listinfo/server-devel server-devel@lists.laptop.org], or contact [https://wiki.laptop.org/go/User:Holt Adam Holt] (holt @ unleashkids.org), thanks!-->


See: [[#How_can_I_remotely_manage_my_Internet-in-a-Box.3F|How can I remotely manage my Internet-in-a-Box?]]<br>
See: [[#How_can_I_remotely_manage_my_Internet-in-a-Box%3F|How can I remotely manage my Internet-in-a-Box?]]<br>
See: [[#What_are_the_best_places_for_community_support?|What are the best places for community support?]]<br>
See: [[#What_are_the_best_places_for_community_support%3F|What are the best places for community support?]]<br>
See: [[#How_can_I_donate_to_Internet-in-a-Box.3F|How can I donate to Internet-in-a-Box?]]
See: [[#How_can_I_donate_to_Internet-in-a-Box%3F|How can I donate to Internet-in-a-Box?]]


== How can I donate to Internet-in-a-Box? ==
== How can I donate to Internet-in-a-Box? ==
Line 1,514: Line 1,743:
Release History:
Release History:


* [https://github.com/iiab/iiab/wiki/IIAB-7.2-Release-Notes IIAB 7.2] is expected November 2021.
* [https://github.com/iiab/iiab/wiki/IIAB-8.2-Release-Notes IIAB 8.2] is expected in 2024.
* [http://wiki.laptop.org/go/IIAB/7.1 IIAB 7.1] was released [https://github.com/iiab/iiab/wiki/IIAB-7.1-Release-Notes June 6, 2020].
* [https://github.com/iiab/iiab/wiki/IIAB-8.1-Release-Notes IIAB 8.1] was released December 31, 2023.
* [http://wiki.laptop.org/go/IIAB/7.0 IIAB 7.0] was released [https://github.com/iiab/iiab/wiki/IIAB-7.0-Release-Notes September 30, 2019] ([https://groups.google.com/forum/m/#!topic/unleashkids/Xe0eBQ4GFso Announcement]).
* [https://github.com/iiab/iiab/wiki/IIAB-8.0-Release-Notes IIAB 8.0] was released December 31, 2022.
* [http://wiki.laptop.org/go/IIAB/6.7 IIAB 6.7] was released [https://github.com/iiab/iiab/wiki/IIAB-6.7-Release-Notes February 21, 2019].
* [https://github.com/iiab/iiab/wiki/IIAB-7.2-Release-Notes IIAB 7.2] was released December 31, 2021.
* [http://wiki.laptop.org/go/IIAB/6.6 IIAB 6.6] was released [https://github.com/iiab/iiab/wiki/IIAB-6.6-Release-Notes September 12, 2018].
* [https://wiki.laptop.org/go/IIAB/7.1 IIAB 7.1] was released [https://github.com/iiab/iiab/wiki/IIAB-7.1-Release-Notes June 6, 2020].
* [http://wiki.laptop.org/go/IIAB/6.5 IIAB 6.5] was released [https://groups.google.com/forum/m/#!topic/unleashkids/jYML3TLOUgg May 24, 2018].
* [https://wiki.laptop.org/go/IIAB/7.0 IIAB 7.0] was released [https://github.com/iiab/iiab/wiki/IIAB-7.0-Release-Notes September 30, 2019] ([https://groups.google.com/forum/m/#!topic/unleashkids/Xe0eBQ4GFso Announcement]).
* [http://wiki.laptop.org/go/IIAB/6.4 IIAB 6.4] was released [http://lists.laptop.org/pipermail/server-devel/2017-October/008211.html October 5, 2017] &mdash; embracing new contributors and rebasing from Debian 8 to 9.
* [https://wiki.laptop.org/go/IIAB/6.7 IIAB 6.7] was released [https://github.com/iiab/iiab/wiki/IIAB-6.7-Release-Notes February 21, 2019].
* [http://wiki.laptop.org/go/IIAB/6.3 IIAB 6.3] was released [http://lists.laptop.org/pipermail/server-devel/2017-July/008184.html July 13, 2017].
* [https://wiki.laptop.org/go/IIAB/6.6 IIAB 6.6] was released [https://github.com/iiab/iiab/wiki/IIAB-6.6-Release-Notes September 12, 2018].
* [http://wiki.laptop.org/go/XS_Community_Edition/6.2 IIAB/XSCE 6.2] was released [http://lists.laptop.org/pipermail/server-devel/2017-April/008144.html April 19, 2017].
* [https://wiki.laptop.org/go/IIAB/6.5 IIAB 6.5] was released [https://groups.google.com/forum/m/#!topic/unleashkids/jYML3TLOUgg May 24, 2018].
* [http://wiki.laptop.org/go/XS_Community_Edition/6.1 XSCE 6.1] was released [http://lists.laptop.org/pipermail/server-devel/2016-September/007961.html September 22, 2016].
* [https://wiki.laptop.org/go/IIAB/6.4 IIAB 6.4] was released [http://lists.laptop.org/pipermail/server-devel/2017-October/008211.html October 5, 2017] &mdash; embracing new contributors and rebasing from Debian 8 to 9.
* [http://wiki.laptop.org/go/XS_Community_Edition/6.0 XSCE 6.0] was released [http://lists.laptop.org/pipermail/server-devel/2016-March/007854.html March 27, 2016], following our [http://wiki.laptop.org/go/XS_Community_Edition/6.0/Sprint Toronto Summit], including [http://wiki.laptop.org/go/XS_Community_Edition/Features many new features] for educators and administrators.  For example [http://en.wikipedia.org/wiki/Elgg_%28software%29 Elgg] for students and [http://en.wikipedia.org/wiki/OwnCloud ownCloud] for teachers, were tested in Malaysia starting March 2015.
* [https://wiki.laptop.org/go/IIAB/6.3 IIAB 6.3] was released [http://lists.laptop.org/pipermail/server-devel/2017-July/008184.html July 13, 2017].
* [http://wiki.laptop.org/go/XS_Community_Edition/5.1 XSCE 5.1] was released [http://lists.laptop.org/pipermail/server-devel/2014-July/007464.html July 27, 2014].  Official [https://github.com/xsce/xsce/blob/master/ReleaseNotes5.1.rst release notes] outlined significant steps forward: Samba filesharing, XOVis visualization of student work patterns, vnStat traffic-monitoring console, better Internet-in-a-Box searchability, customizable web-filtering requested by many schools, OpenVPN remote access, and a new module for automated field-testing.
* [https://wiki.laptop.org/go/XS_Community_Edition/6.2 IIAB/XSCE 6.2] was released [http://lists.laptop.org/pipermail/server-devel/2017-April/008144.html April 19, 2017].
* [http://wiki.laptop.org/go/XS_Community_Edition/5.0 XSCE 5.0] was released [http://wiki.laptop.org/go/XS_Community_Edition/5.0/Road_Map Jan 22, 2014] introducing [http://wiki.laptop.org/go/XS_Community_Edition/5.0/Ansible_Progress Ansible progress] for developers especially ([http://lists.laptop.org/pipermail/server-devel/2014-January/007148.html announcement]).  Compare XSCE 5.0 RC 1 which was released [http://lists.laptop.org/pipermail/server-devel/2013-December/007031.html Dec 17, 2013], formerly known as 0.5 RC 1.
* [https://wiki.laptop.org/go/XS_Community_Edition/6.1 XSCE 6.1] was released [http://lists.laptop.org/pipermail/server-devel/2016-September/007961.html September 22, 2016].
* [http://wiki.laptop.org/go/XS_Community_Edition/0.4 XSCE 0.4] was released [http://wiki.laptop.org/go/XS_Community_Edition/0.4/Road_Map Oct 3, 2013].
* [https://wiki.laptop.org/go/XS_Community_Edition/6.0 XSCE 6.0] was released [http://lists.laptop.org/pipermail/server-devel/2016-March/007854.html March 27, 2016], following our [https://wiki.laptop.org/go/XS_Community_Edition/6.0/Sprint Toronto Summit], including [https://wiki.laptop.org/go/XS_Community_Edition/Features many new features] for educators and administrators.  For example [https://en.wikipedia.org/wiki/Elgg_%28software%29 Elgg] for students and [https://en.wikipedia.org/wiki/OwnCloud ownCloud] for teachers, were tested in Malaysia starting March 2015.
* [http://wiki.laptop.org/go/XS_Community_Edition/0.3 XSCE 0.3] was released [http://wiki.laptop.org/go/XS_Community_Edition/0.3/Road_Map June 6, 2013].
* [https://wiki.laptop.org/go/XS_Community_Edition/5.1 XSCE 5.1] was released [http://lists.laptop.org/pipermail/server-devel/2014-July/007464.html July 27, 2014].  Official [https://github.com/xsce/xsce/blob/master/ReleaseNotes5.1.rst release notes] outlined significant steps forward: Samba filesharing, XOVis visualization of student work patterns, vnStat traffic-monitoring console, better Internet-in-a-Box searchability, customizable web-filtering requested by many schools, OpenVPN remote access, and a new module for automated field-testing.
* [https://wiki.laptop.org/go/XS_Community_Edition/5.0 XSCE 5.0] was released [https://wiki.laptop.org/go/XS_Community_Edition/5.0/Road_Map Jan 22, 2014] introducing [https://wiki.laptop.org/go/XS_Community_Edition/5.0/Ansible_Progress Ansible progress] for developers especially ([http://lists.laptop.org/pipermail/server-devel/2014-January/007148.html announcement]).  Compare XSCE 5.0 RC 1 which was released [http://lists.laptop.org/pipermail/server-devel/2013-December/007031.html Dec 17, 2013], formerly known as 0.5 RC 1.
* [https://wiki.laptop.org/go/XS_Community_Edition/0.4 XSCE 0.4] was released [https://wiki.laptop.org/go/XS_Community_Edition/0.4/Road_Map Oct 3, 2013].
* [https://wiki.laptop.org/go/XS_Community_Edition/0.3 XSCE 0.3] was released [https://wiki.laptop.org/go/XS_Community_Edition/0.3/Road_Map June 6, 2013].


Since May 2017, IIAB code has been available at: https://github.com/iiab
Since May 2017, IIAB code has been available at: https://github.com/iiab
Line 1,538: Line 1,770:
Or consider main repo definition: [http://xsce.activitycentral.com/repos/xsce-devel.repo http://xsce.activitycentral.com/repos/xsce-devel.repo]-->
Or consider main repo definition: [http://xsce.activitycentral.com/repos/xsce-devel.repo http://xsce.activitycentral.com/repos/xsce-devel.repo]-->


See: [[#What_are_the_best_places_for_community_support?|What are the best places for community support?]]<br>
See: [[#What_are_the_best_places_for_community_support%3F|What are the best places for community support?]]<br>
See: [[##How_did_IIAB.2FXSCE.27s_design_evolve.3F|How did IIAB/XSCE's design evolve?]]
See: [[##How_did_IIAB.2FXSCE.27s_design_evolve%3F|How did IIAB/XSCE's design evolve?]]


== How did IIAB/XSCE's design evolve? ==
== How did IIAB/XSCE's design evolve? ==
Line 1,545: Line 1,777:
Here's our brief-but-growing participatory design archive / lineage:
Here's our brief-but-growing participatory design archive / lineage:


* Our earliest work is based on [http://wiki.laptop.org/go/School_server One Laptop Per Child's original XS design and implementation] which arose in [http://wiki.laptop.org/index.php?title=School_server&oldid=23045 January 2007] to be used in [http://olpcMAP.net many countries], thanks to John Watlington and Daniel Drake.
* Our earliest work is based on [https://wiki.laptop.org/go/School_server One Laptop Per Child's original XS design and implementation] which arose in [https://wiki.laptop.org/mediawiki/index.php?title=School_server&oldid=23045 January 2007] to be used in [http://olpcMAP.net 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.
* 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 [https://docs.google.com/document/pub?id=1dnhU2F6EntepVXTgN8QpkME8fZVUuPjcCoMUfAVKbcc Design Document] in September 2012.
* After the XS Community Edition grassroots team came together during the middle of 2012, using the XSCE name selected by George HuntSridhar Dhanapalan wrote the [https://docs.google.com/document/pub?id=1dnhU2F6EntepVXTgN8QpkME8fZVUuPjcCoMUfAVKbcc Design Document] in September 2012.
* Field implementer Tony Anderson expanded on these ideas laying out some [http://wiki.laptop.org/go/XS_Community_Edition/Use_Cases Use Cases] in October 2012, while many others contributed to a broadening roadmap of [http://wiki.laptop.org/go/XS_Community_Edition/Features features].
* Field implementer Tony Anderson expanded on these ideas laying out some [https://wiki.laptop.org/go/XS_Community_Edition/Use_Cases Use Cases] in October 2012, while many others contributed to a broadening roadmap of [https://wiki.laptop.org/go/XS_Community_Edition/Features features].
* [https://github.com/iiab/internet-in-a-box Internet-in-a-Box] (also built by volunteer professionals, including Caltech and JPL software engineers) was founded separately by Braddock Gaskill in this same [https://github.com/iiab/internet-in-a-box/commit/9c3a5ab5a7a19e9eb084cc0ddeac942d66dbaa69 mid-2012] timeframe, in Southern California.
* [https://github.com/iiab/internet-in-a-box Internet-in-a-Box] (also built by volunteer professionals, including Caltech and JPL software engineers) was founded separately by Braddock Gaskill in this same [https://github.com/iiab/internet-in-a-box/commit/9c3a5ab5a7a19e9eb084cc0ddeac942d66dbaa69 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!
* 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.
* 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.
* 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.
* 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.
* 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.


[http://wiki.laptop.org/go/IIAB#Our_History_.26_Inspiration Community history] is vital to all seeking to avoid reinventing mistakes of the past, thanks for Everyone's thoughtful input past & present!
[https://wiki.laptop.org/go/IIAB#Our_History_.26_Inspiration Community history] is vital to all seeking to avoid reinventing mistakes of the past, thanks for Everyone's thoughtful input past & present!

Latest revision as of 23:59, 26 March 2024


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

Do you need the best of the Internet (Wikipedia, OpenStreetMap, Khan Academy, Stack Exchange, ETC) with local content and learning apps for all?

Customize an "Offline Internet" for your school, for your community — or for your very own family!

Listen to the 23min BBC podcast "How to put the internet in a box" (2020-10-20) to learn how this works. See also a great community example in North India (3min) from 2021. Internet-in-a-Box (IIAB) is used in medical clinics as well, as can be seen in this Dominican Republic video.


Please see our internet-in-a-box.org web site.

Internet-in-a-Box brings the power of a free Digital Library of Alexandria to any community worldwide.

Whether costing $10 or $1000, an Internet-in-a-Box "learning hotspot" brings classroom/library devices to life, in ways that very deeply empower learning and community.


RECAP: To create your own Internet-in-a-Box [1] [2], look over a few live demo examples and check out our growing collection of videos.

Internet-in-a-Box arose from One Laptop Per Child's original school server (2007-2012) and our global grassroots community, adding in the quality content and learning apps shared by the best educational systems worldwide.

Now anyone can do this, building up your local community's very own 21st Century digital library, using free and open source software.


READY, SET, INSTALL: Internet-in-a-Box (IIAB) is built by a global network of professional volunteers, inspired by One Laptop Per Child's famous laptops and their innovative Sugar Learning Platformbut now with a much wider vision of serving all — both in schools and beyond.

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?

Where is Internet-in-a-Box used?

Internet-in-a-Box (IIAB) is in use in dozens of countries, from smaller communities to large-scale institutional deployments.

Please see our regular global community updates at: @internet_in_box

Examples include orphanages and schools in Haiti, schools across southern Mexico, rural communities and libraries across southwest Ghana, remote schools in Myanmar/Burma and Cambodia, villages across India, a girls science school in Rwanda, community centers in Kenya, 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.

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?

Unleash the best of Internet learning without costs or distractions. Pack your Internet-in-a-Box (IIAB) full of incredible Wikipedia + Maps + Literature + Khan Academy + Video!

The first step is to add content gems to your IIAB. Learn how to download high-quality free content, like Wikipedia ZIM files.

Not just schools but also medical clinics, museums, and prisons are taking advantage — as well as individual educators and parents taking charge by building their very own "Library of Alexandria" community learning hotspots.

How can kids best take advantage of these crown jewels of learning? After you've added content, offer your students direct access via IIAB Apps 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 and Satellite Photos for your Continent, or the entire World 
 http://box/wiki       MediaWiki 1.40+ (Wikipedia's own wiki software for document collaboration, used to use http://box/mediawiki)
 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/NGINX proxy e.g. for enhanced privacy #852
 http://box/books      Calibre-Web E-Book Library, an alternative to Calibre (above), with a modern web interface 
 http://box/moodle     Moodle 4.3+ (learning management system)
 http://box/lokole     Lokole is an Email service that works offline for rural communities, students and teachers.
 http://box/kolibri    Kolibri 0.15+ is like KA Lite, but much improved for educators. Unproxied equivalent: http://box:8009/kolibri
 http://box/nodered    Node-RED visual programming for electronics projects (IoT)
 http://box/wordpress  WordPress 6.3+ (blogging & community publishing)
 http://box/mediawiki  Redirects to http://box/wiki (see above)
 http://box/nextcloud  Nextcloud 27+ (students can store their files/photos on Internet-in-a-Box, similar to Dropbox and Google Docs)
 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 4 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://10.10.10.10/admin
 http://box/munin      Network/Infra monitoring
 http://box/awstats    Usage statistics


See: Can teachers display their own content?
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://10.10.10.10/usb

Warnings:

  1. If you're using the Desktop (graphical) version of Raspberry Pi OS, please consider this workaround so that USB drives mount cleanly every after boot: #2456
  2. While generally not necessary (or realistic, for rural teachers etc, as mentioned on #2277) you can unmount drives by running: systemctl stop usbmount@dev-sda*
  3. 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
  4. 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, please set iiab_usb_lib_show_all: False in /etc/iiab/local_vars.yml prior to installing IIAB.
  5. Note that all Linux users should be able to read and write to USB drives inserted into IIAB as of 2021-03-25 (PR #2715). Kolibri requires this. If however you prefer to block non-root users, please set usb_lib_umask0000_for_kolibri: False in /etc/iiab/local_vars.yml prior to installing IIAB.

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 for background details.

CLARIFICATION: If your Linux OS has a graphical desktop, it's common to see popup message warnings like:

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

It's safe to ignore these messages. Or you can make these popup messages go away, typically by clicking through your graphical File Manager's preferences or OS settings, and unchecking the box for "Mount removable media automatically when they are inserted" or "Automatically mount removable media when inserted and on startup." #86

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:

  • The Raspberry Pi 4 ($35+), Raspberry Pi 5 ($60+) and Raspberry Pi 400 ($70 computer-in-keyboard) are best for classrooms, in almost all cases! Their internal Wi-Fi hotspot supports up to 32 student WiFi client devices (but see #823 for the very latest Wi-Fi firmware info!) RECOMMENDATION: Buy any Raspberry Pi with at least 2 GB RAM, especially if your Internet-in-a-Box will include Kolibri, Moodle or Nextcloud.
    • The older Raspberry Pi 3 and 3 B+ ($35+) are also possible, despite their 1GB RAM limitation.
    • Finally the Raspberry Pi Zero W ($10) and Raspberry Pi Zero 2 W ($15) work great as learning kiosks, despite their meager 512MB RAM (Internet-in-a-Box is used in rural medical clinics, and by families in their homes). NOTE that your microSD card should be prepared with IIAB software and provisioned with Content in a more powerful Raspberry Pi — then later insert the microSD into your Zero (2) W. (It continues to astonish us how powerful these tiny computers really are, the size of a cigarette lighter yet able to serve 32 students simultaneously, with their powerful built-in Wi-Fi!)
  • Refurbished "PC" Laptops & Thin Clients: When recycled / upcycled conscientiously, quality donated laptops and PC's can work extremely well as your Internet-in-a-Box, becoming a "Learning 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 64-bit Linux well, preferably with a BIOS that permits it to run while the screen is closed.
  • Mini PC's like the ASUS NUC (acquired from Intel in 2023): Avoid classic/desktop PCs whenever possible, as they consume far too much electricity. However: tough, well-rounded, low-power Mini PCs (such as the NUC) world extremely well, and have proven very effective as school servers in the developing world since 2014. We prefer Mini PC's models that accept 2.5-inch SATA drives (HDD or SSD) and work with DC voltages up to 19V. WARNINGS:
    • The internal Wi-Fi in most NUC computers is regrettably blocked from connecting to more than 12 Wi-Fi client devices. Compare this to the Raspberry Pi's mentioned above — whose internal Wi-Fi can support 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. Consider also Beelink's NUC clones, and Gigabyte BRIX (e.g. GB-BSI3H-6100) which likewise is almost an exact clone of the NUC. The BRIX allows internal Wi-Fi to scale beyond the NUC's annoying limitation of 12 connections maximum, if you 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 NUCs since 2015 (5th generation NUCs and onwards) as the NUC's Wi-Fi module is unfortunately soldered in.
  • ARM Mini PCs: CPUs like TrimSlice / Utilite CompuLab 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 lack of 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?


MEMORY: Some do fine with 512MB RAM (even in 2023!) 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 2GB or 4GB from an RPi 4 — or 8GB or more within a Mini PC — when server-side loads become very intensive. For example if you are running an LMS, experiencing a lot of OpenStreetMap traffic, running a Wikipedia Treasure Hunt with multiple students running full-text searches of Wikipedia — or offering streaming & fileserver-like capabilities broadly to many students.


STORAGE: While there's increasing movement from hard disks to SSDs and microSD cards every year, many others still swear by tried-and-true hard drives. Certainly rotating media are the clear winner when TB (or multi-terabyte) storage is 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.


Please ask further hardware questions on our community forums !

See: What OS should I use?
See: Is a quick installation possible?
See: Can I create a Wi-Fi hotspot using an old laptop?
See: Can I install IIAB onto a USB drive?
See: What are the best places for community support?

What OS should I use?

Check IIAB Platforms for the latest Linux OS compatibility details!


1) Raspberry Pi OS on Raspberry Pi 4, 5 or 400 is best if this is your first time — regardless if you prefer the full/graphical Raspberry Pi OS with desktop with its great desktop apps for students — or consider Raspberry Pi OS Lite for a more lightweight "headless" server:


2) On PC-like hardware (or virtual machines) pick a 64-bit OS from this list: (either with graphical desktop or "headless", and whether-or-not with LTS multi-year support)


Others like Reno McKenzie & Josh Dennis experimented successfully (tweaks required!) with IIAB on the lean & mean DietPi.com back in 2017. Similarly, Ubermix 4.1 was successfully tested in 2019.

Please avoid Docker, as our Ansible provisioning requires low-level access to the operating system.

Finally, if there are situations where porting to a new OS/distribution will tangibly help schools/libraries/clinics across an entire region, please don't hesitate to reach out 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?

1. Yes! Download one of our IIAB Images for Raspberry Pi to your microSD card. You can then boot the microSD card in almost any Raspberry Pi.

Clarification: the above IIAB images contain software only (you then add content !) and can occasionally be months out-of-date.


2. If you want the very latest IIAB software that undergoes continuous improvement and QA, we recommend you instead use the 1-line-installer at download.iiab.io and check out IIAB's new Technical Contributors Guide.

First verify that your hardware and Linux OS are appropriate:

  • If you're using a PC/Laptop or VM, install a minimal OS like Ubuntu 22.04+, Debian 12+ or Linux Mint 21+.

Then run IIAB's 1-line installer to install Internet-in-a-Box (IIAB) 8.0's latest pre-release, by typing in:

  curl iiab.io/install.txt | bash

This can take an hour or more to complete — depending whether you choose SMALL-sized (~10 server apps), MEDIUM-sized (~16 server apps) or LARGE-sized (~30 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!

While a lot has changed since 2019, consider also the "ZERO to IIAB" installation video on our YouTube channel.

Remember: IIAB's 1-line installer might need you to run sudo iiab multiple times, before IIAB's software install fully completes — e.g. if Internet connectivity is interrupted for any reason. When your IIAB software install is 100% complete, you'll be asked to reboot — typically within about-an-hour-or-so (so you can begin installing content!)


3. Linux hackers: other distros might be possible, but can require extensive babysitting to get right. Consider the long-form "Do Everything from Scratch" install instructions if porting IIAB to a new Linux distribution is your goal.


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?
See: Can I install IIAB onto a USB drive?

What services (IIAB apps) are suggested during installation?

When installing Internet-in-a-Box (IIAB) at https://download.iiab.io, you're given a choice of SMALL-sized, MEDIUM-sized or LARGE-sized — to get you started fast!

Which services (IIAB apps) are included in each of these 3? The summary table below helps you choose among IIAB's almost 40 powerful apps — optionally with a complete LMS (learning management system) like Kolibri, Moodle, WordPress, Sugarizer or Nextcloud.

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

SMALL MEDIUM LARGE IIAB APP URL DOCS DESCRIPTION
X X X box/awstats 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. See Also: Matomo
X X X box/books box/libros box/livres Calibre-Web


(Video Tips)

Calibre-Web is a web app for organizing E-Books into bookshelves. You can begin your community library with an existing Calibre database.
X X X box:8008 KA Lite


(Video Tips)

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/matomo Matomo


(Video Tips)

Matomo is a web analytics alternative to Google Analytics, emphasizing privacy and data ownership. See Also: AWStats
X X X box/maps OpenStreetMap


(Video Tips)

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 includes 10+ zoom levels of satellite imagery!
X X X box/usb USB_LIB Content from USB sticks/drives, that teachers can insert anytime.
I I I (none) Bluetooth Bluetooth access to IIAB's Admin Console, for IIAB field operators/administrators and advanced teachers too. Provides two services, pan (or Personal Area Network) and term (terminal emulation) — installed (I) but not enabled. Works on Raspberry Pi only.
I I I (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 — installed (I) but not enabled. #1182
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.
I I I (none) remote.it https://remote.it can help you remotely maintain an IIAB. Some benefits include: crossing multiple NATs/firewalls using a single TCP port, without requiring router port forwarding, and reducing your network's vulnerability. — installed (I) but not enabled.
X X box/kolibri Kolibri


(Video Tips)

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 X box/nextcloud Nextcloud


(Video Tips)

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


(Live Demo)

Program or be programmed! Explore creativity puzzles originally from MIT's One Laptop Per Child global project. (64-BIT ONLY)
X X box:9091 Transmission Transmission is a BitTorrent client (software) that helps you auto-download KA Lite (Khan Academy) videos and similar. (COMPILING TRANSMISSION 4.0.4+ TAKES AN HOUR AS OF OCTOBER 2023; TRANSMISSION 4.1+ SHOULD FIX THAT IN 2024)
X X box/wordpress WordPress


(Video Tips)

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/print or localhost: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/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 600+ 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 (64-BIT ONLY)
X box/jupyterhub JupyterHub


(Video Tips)

High Schools may want to consider JupyterHub to integrate coding with dynamic interactive graphing — A New Way to Think About Programming — allowing students to integrate science experiment results and program output within their notebook/document/blog.
X box/wiki <- 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


(Video Tips)

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/moodle Moodle


(Video Tips)

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.
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/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 box/nodered Node-RED


(Video Tips)

Node-RED enables electronics projects with a flow-based development tool for visual programming, originally developed by IBM for wiring together hardware devices, APIs and online services as part of the Internet of Things (IoT). "Low-code programming for event-driven applications." See also: Mosquitto
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 box/phpmyadmin ? phpMyAdmin phpMyAdmin is a free and open source administration tool for MySQL and MariaDB — installed (I) but not enabled in LARGE.
I (none) Samba Samba is the standard Windows interoperability suite of programs for Linux and Unix — installed (I) but not enabled in LARGE.
box:12080 AzuraCast


(Video Tips)

AzuraCast is simple, self-hosted web radio. Use it to schedule student newscasts, podcasts, music (e.g. MP3's and similar) and even do live-streaming. (64-BIT ONLY; 4+ GB RAM RECOMMENDED)
box:8080 Calibre


(Video Tips)

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. (VERY SLOW INSTALL)
box:8081 box/stream ? Cham Cham is an experimental/lightweight live video streaming platform with adaptive bitrates for IIAB. PR #1743
box/dokuwiki (deprecated, Jan 2020) DokuWiki DokuWiki was written in PHP, to work on plain text files (and thus not need a database). Novel design, but it never caught on, and was poorly maintained.
box/elgg (deprecated, August 2021) Elgg Elgg is (was) a social networking engine used by offline schools to create a collaborative environment. Includes basic blogging, microblogging, file sharing, networking and groups.
(none) (deprecated, 2019) ejabberd ejabberd is a free and open source instant messaging server.
box/lokole Lokole Lokole is an Email service that works offline for rural communities, students and teachers. With a 3G/4G modem, you can arrange to batch-upload / batch-download emails once per night — for almost no cost at all — depending on mobile data plans in your country.
box:2812 ? Monit Monit is a process supervision tool. View system status from the command line, or browser. Arguably no longer necessary, as a result of systemd: #1849
box:83/freepbx (Apache) box/freepbx (NGINX) 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). (VERY SLOW INSTALL)
(none) Squid Squid is a proxy server that can be helpful for caching and bandwidth shaping, as well as basic allowlist/denylist URL filtering. See IIAB's sample /etc/squid/squid.conf

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?

IIAB Tech Docs explain the infrastructure that makes Internet-in-a-Box possible.

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

Developers can also consider our Technical Contributors Guide, first published in October 2017, and overhauled in late 2021.

More generally, see our Tech Skills Videos (alternate view) focused on networking, Raspberry Pi, web basics, and security — with subtitles in English, Spanish and French. Some of which are also on IIAB's YouTube channel.

Offline Field Operators should also check our growing collection of Internet-in-a-Box tech support docs (and eventually videos!) available on your very own Internet-in-a-Box at http://box/info

Finally you can force your IIAB to update these offline docs (when your IIAB is online) by running: /usr/bin/iiab-refresh-wiki-docs

See: What security tips exist?
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 apps/services.

FYI the latest Ansible version recommendation is posted near Line 11 of scripts/ansible.

If you must upgrade Ansible, make sure your IIAB is online, and then run:

 cd /opt/iiab/iiab
 sudo scripts/ansible

Done! (It will explain how to verify your Ansible installation.)

Finally if your IIAB is much older, upgrading Ansible can be challenging (And At Your Own Risk). But if you must: (run as root, when your IIAB is online)

  1. Run ansible --version to see what version of Ansible is installed.
  2. Remove all prior versions of Ansible using apt purge ansible-core (or apt purge ansible-base or apt purge ansible or pip3 uninstall ansible-core or pip3 uninstall ansible-base or pip3 uninstall ansible) depending on 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. Once again try to run cd /opt/iiab/iiab then sudo scripts/ansible
  5. Run ansible --version and/or pip3 show ansible-core to verify (on rare occasion you might first need to log out and log back in, if Ansible ends up being moved, e.g. from /usr/bin to /usr/local/bin or vice versa)

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

PRO TIP: IIAB's Ansible install script attempts to upgrade ~4 Ansible Collections as well. See the line that begins with: ansible-galaxy collection install --force-with-deps

PRO TIP: For those wanting to run a single Ansible playbook or role, run cd /opt/iiab/iiab then sudo ./runrole <ROLE NAME> (see runrole's source code).

See: Is a quick installation possible?
See: What services (IIAB apps) are suggested during installation?
See: What technical documentation exists?

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

  1. The message "Connected, no Internet" is perfectly normal (in an offline environment). 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 need to use your finger to find this notification first, 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.
  2. Recent Samsung and Huawei smartphones (since about 2019) require to you to Turn Off "Mobile Data" before you can browse to http://box, http://box.lan or http://10.10.10.10 (or http://172.18.96.1 if your Internet-in-a-Box pre-dates July 2022)

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

What are the default passwords?

For KA Lite, Kolibri, Calibre, Calibre-Web, Nextcloud, Moodle, CUPS, Elgg, JupyterHub, 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. For MediaWiki however, Admin/changeme2020 is the initial username/password.

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

However for IIAB's own Admin Console[*] at http://box/admin, http://box.lan/admin or http://10.10.10.10/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 Raspberry Pi OS: 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 -i".

[*] 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, 3 B+ or 4, 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! 2020-09-23 Warning: MySQL/MariaDB passwords cannot easily be changed after IIAB install (#2542).

Admin Console: Note that very occasionally it might be necessary to run systemctl restart iiab-cmdsrv.service if http://box.lan/admin shows red errors upon login.

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

See: What can I do with E-books and Internet-in-a-Box?
See: What technical documentation exists?
See: Can I password protect the Wi-Fi hotspot?
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 Jamaica, Mexico, Haiti and other places around the world, will be posted. Here is a South Asia Medical Version including more than 30 languages. 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?

OPTIONAL: Some 2019 videos on Internet-in-a-Box's YouTube channel (several available as .mp4 and .webm) are a bit out-of-date, but can illustrate the big picture, showing how 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://10.10.10.10 from any nearby smartphone, tablet or laptop/computer. If you've just installed Internet-in-a-Box (IIAB) on your home network, here are some great tricks to find its IP Address.

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: Please see Admin Console's 5 technical overview docs (NEW, as of 2022!) 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, 3 B+ or 4) 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 change to Mobile view or Desktop view?
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 change to Mobile view or Desktop view?

Starting with Internet-in-a-Box 7.0 (#1775) IIAB includes a Mobile/Desktop button, but it's a bit hard to find, so here are basic instructions:

  1. Look in the top-left corner of your IIAB home page (e.g. http://box or http://box.lan)
  2. Click on the 3 dots (vertical ellipsis)
  3. A white popup/dropdown menu will appear
  4. Click on its middle icon (which looks like 2 squares, one square on top of the other) to toggle your current browser view between Mobile view and Desktop view!

Notes:

  • You can permanently change visual aspects of IIAB's Mobile view and Desktop view within http://box.lan/admin > Content Menus > Properties of Current Menu > [check or uncheck any of the 4 + 4 checkboxes for Description, Extra Description, Sub-menu and Footnote] > Save Menu.
  • Separately, many mobile browsers have their own button to force Desktop view — typically found in the top-right under the browser's own vertical ellipsis. Look there for the "Desktop site [ ]" checkbox in Chrome, or the "Request desktop site [ ]" checkbox in Firefox.

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

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:

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

If you want a self-contained (single-unit) knowledge hotspot, consider the Wi-Fi capability possibly already built into the computer where you install IIAB. Run iw list and look for "AP" under "Supported interface modes" to see if it's capable of Access Point mode / AP mode (#3057) as would be enabled by hostapd. (If the iw command isn't yet installed, run sudo apt install iw — also see "Can I create a Wi-Fi hotspot using an old laptop?" just below.)

Optionally, you may want to attach a Wi-Fi Access Point to your IIAB. If you want higher-powered Wi-Fi equipment and antenna(e) fully external to your IIAB server, consider approaches such as the cantenna and MeshNet approaches used by Anish Mangal in India.

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

Also consider 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/learning hotspots" in every sense) in turn allowing kids to take advantage of amazing free Digital Libraries like https://internet-in-a-box.org

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.

NOTE: To determine whether your PC/machine's internal WiFi chip has Linux/distro support for AP Mode (allowing for many students to connect to this hotspot) please run /usr/sbin/iw list and look for * AP under Supported interface modes: or software interface modes — as outlined at #3057.

Equivalent to the above, most IIAB's should have a line in /etc/iiab/iiab.ini saying either can_be_ap = True or can_be_ap = False (PR #3222).

Similarly, you can try running:

 sudo iiab-hotspot-on

REMINDER: If you ever add or remove a USB Wi-Fi adapter (or an entire Wi-Fi router, typically connected over Ethernet), you then need to run:

 sudo iiab-network

You're likely to have good luck with Qualcomm Atheros chipsets — certainly older Atheros chipsets have good support in GNU/Linux (https://wiki.debian.org/ath9k).

February 2019 Example: Testing confirmed that IIAB 6.7's hostapd Wi-Fi hotspot worked 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 Wi-Fi hotspot name?

The Wi-Fi hotspot name (also known as SSID) is what most people use to connect to Internet-in-a-Box using their Wi-Fi devices. In other words the name that appears on the air, for your IIAB's wireless network / Access Point / AP.

How to rename it depends on whether your Wi-Fi hotspot 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:
      sudo 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 (menu) > 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 several 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 to avoid rebooting.
    • Finally you can run sudo iiab-hotspot-on and sudo iiab-hotspot-off which are found in /usr/bin — especially useful if you've used a Raspberry Pi's internal Wi-Fi to install IIAB software and content. See Common Customizations for more detail.

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 password protect the Wi-Fi hotspot?

Internet-in-a-Box (IIAB) is generally intended as a free library completely open to all!

That said, if you have command-line access to your IIAB using a screen/keyboard or ssh, you can try setting a Wi-Fi password as follows: (assuming your IIAB Wi-Fi hotspot is internal, or is a USB Wi-Fi adapter)

  1. Run:
    sudo nano /etc/iiab/local_vars.yml
    
  2. Look near Lines 72-73 in your /etc/iiab/local_vars.yml to set these 2 variables:
    hostapd_secure: True
    hostapd_password: ACTUAL_PASSWORD
    
  3. Save the file (Ctrl-O) and exit (Ctrl-X).
  4. Run sudo iiab-network and confirm that it completes without error (about 3 minutes later).
  5. Test it! Further discussion: #3477

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 strongly desired, this can be implemented within each school/library/clinic by editing /etc/iiab/local_vars.yml — and then run sudo iiab-network

Or: log into Admin Console (http://box/admin or http://box.lan/admin) > Configure (menu) > Network Parameters > Host Name > Save Configuration > Install Configured Options (waiting patiently for that to complete under Utilities (menu) > Display Job Status which can take ~20 min on older Raspberry Pi's!)

Many different names have been used in the past, such as http://schoolserver.lan and http://school.lan — anything that resolves locally to http://10.10.10.10 should be sufficient with standard networking (or http://172.18.96.1 if your Internet-in-a-Box pre-dates July 2022). 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.unused/school.external.zone.db
https://github.com/iiab/iiab/blob/master/roles/network/templates/named.unused/school.internal.zone.db.j2
https://github.com/iiab/iiab/blob/master/roles/network/templates/named.unused/school.local.zone.db.j2

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 (fixed) IP address such as 192.168.1.99, use lines like the following in /etc/iiab/local_vars.yml — and then run sudo iiab-network :

 wan_ip: 192.168.1.99
 wan_netmask: 255.255.255.0
 wan_gateway: 192.168.1.254
 wan_nameserver: 192.168.1.254
 wan_try_dhcp_before_static_ip: True

By default this is a FALLBACK static (fixed) IP address, which requires an Ethernet cable and link-light showing. If that cable connects IIAB to an Internet router/cablemodem or similar (that is turned on) IIAB should receive a DHCP IP address within about 30 seconds. Or, if there is no DHCP on the wire, IIAB will set its own IP address (typically on eth0) to 192.168.1.99 per this example, about 45 seconds later.

Specifically, if you keep wan_try_dhcp_before_static_ip: True your /etc/dhcpcd.conf will contain: (on any OS where IIAB sets up /etc/dhcpcd.conf)

 profile static_eth0
 static ip_address=192.168.1.99/24
 static routers=192.168.1.254
 static domain_name_servers=192.168.1.254
 
 interface eth0
 fallback static_eth0

Or if you set wan_try_dhcp_before_static_ip: False your /etc/dhcpcd.conf will contain: (on any OS where IIAB sets up /etc/dhcpcd.conf)

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

IN GENERAL, you may need to unplug your IIAB's Ethernet cable and plug it back in before a static IP address takes effect! As such, hard-core traditionalists might also want to add the following to /etc/network/interfaces.d/iiab, to force a static IP address even before the Ethernet "carrier" (i.e. link light) is detected:

 auto eth0
 iface eth0 inet static
     address 192.168.1.99
     broadcast 192.168.1.255
     netmask 255.255.255.0
     gateway 192.168.1.254
     dns-nameservers 192.168.1.254

FYI the above 7 lines also work when nothing at all is added to /etc/dhcpcd.conf, if you want an alternative approach in support of intermittent online updates of your IIAB via Ethernet cable to cablemodem etc (careful though, this unsupported approach is risky as your eth0 will often have 2 IP addresses!)

WHEREAS on Ubuntu, the wan_try_dhcp_before_static_ip variable is currently ignored (i.e. treated as False) and Netplan stores your static IP address settings from /etc/iiab/local_vars.yml into /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.254
       nameservers:
         addresses: [192.168.1.254]
         search: [lan]

Debian 12's equivalent to be clarified in future (please help us here if you can!)

FINALLY, if IIAB is already installed, also consider IIAB's Admin Console (http://box/admin or http://box.lan/admin) > Configure (menu) > 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?

If you've just installed Internet-in-a-Box (IIAB) on your home network, here are some great tricks to find its IP Address.

WI-FI RECOMMENDATIONS:

  • Please change "host_country_code: US" to the correct country code, in /etc/iiab/local_vars.yml, prior to installing IIAB. If IIAB is already installed, also run sudo iiab-network and then reboot.
    • FYI as of 2022-01-04 this sets the country code in /etc/hostapd/hostapd.conf but not in /etc/wpa_supplicant/wpa_supplicant.conf (right after installing Raspberry Pi OS, you make that happen by running raspi-config -> Localisation Options > WLAN Country). #3097
  • IF YOU CONNECT YOUR IIAB'S INTERNAL WI-FI TO THE INTERNET OVER 5 GHz, YOU'LL PREVENT OLDER LAPTOPS/PHONES/TABLETS (WHICH REQUIRE 2.4 GHz) FROM CONNECTING TO YOUR IIAB'S INTERNAL HOTSPOT. This relates to wifi_up_down: True in /etc/iiab/local_vars.yml
  • If your IIAB Raspberry Pi is connected to the Internet over Wi-Fi, and you need to change its upstream Wi-Fi connection: run sudo iiab-hotspot-off then sudo raspi-config (to [dis]associate from/to any upstream WiFi access point) then sudo iiab-hotspot-on and reboot — as outlined in Section (2) of Common Customizations.

PLEASE ALSO 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 (sudo iiab-network) after all your Ethernet and Wi-Fi network interfaces are plugged in and turned on properly (or unplugged properly!) according to 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 run sudo iiab-network

FYI Wi-Fi (e.g. for Internet access, etc) is available on the graphical/desktop version of Ubuntu 22.04 LTS (e.g. use its desktop GUI to set SSID and password) — whereas server versions of Ubuntu don't offer Wi-Fi out of the box.

NOTE: To determine whether your PC/machine's internal WiFi chip has Linux/distro support for AP Mode (allowing for many students to connect to this hotspot) please run /usr/sbin/iw list and look for "AP" under "Supported interface modes:" or "supported interface modes" — as outlined at #3057.

Some prefer Gigabyte BRIX (a drop-in replacement Mini PC, instead of the ASUS [formerly Intel] NUC) as an Atheros internal Wi-Fi module can be inserted, to scale beyond the NUC'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 unleashkids@googlegroups.com !

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 Wi-Fi hotspot 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?

To customize your Internet-in-a-Box (IIAB), modify IIAB configuration variables within /etc/iiab/local_vars.yml

It's best to do this prior to installing IIAB, when IIAB's 1-line installer prompts you with "Edit /etc/iiab/local_vars.yml to customize your Internet-in-a-Box? [Y/n]"

Three common example local_vars.yml files are posted for comparison (SMALL-sized, MEDIUM-sized, and LARGE-sized). See also this medical example used by the Wiki Project Med Foundation e.g. for http://med.iiab.me. In addition see our bare bones example, very useful for unit testing of a single IIAB App.


Customize your IIAB installation (and its selection of apps/services, etc) by proceeding as follows:

  1. Edit /etc/iiab/local_vars.yml using a text editor such as nano, vi, or emacs.
  2. If IIAB is already installed, you MUST then enact your changes:
    • One way to do this is cd /opt/iiab/iiab followed by sudo ./iiab-configure (this can take many minutes on a Raspberry Pi, depending on your changes!)
    • Or, run a (fast) surgical strike using cd /opt/iiab/iiab followed by sudo ./runrole <ROLE NAME> to run a single Ansible role or IIAB Stage.
      • Try sudo ./runrole (without parameters) to see its options, e.g. sudo ./runrole --reinstall <ROLE NAME>
      • Or, run sudo iiab-network to run IIAB's 'network' role.
    • If you must, you can force the running of all Stages 0-9, WITH the 'network' role. Use cd /opt/iiab/iiab followed by sudo ./iiab-install --reinstall
      • DANGER: You may first want to delete /opt/iiab/iiab/iiab_state.yml (to apply more force, At Your Own Risk!)
  3. Don't ever modify /opt/iiab/iiab/vars/default_vars.yml, as explained in the IIAB Architecture and IIAB Variables docs.


PRO TIP: Some very practical networking variables are posted at the bottom of the IIAB Networking document.


See: What services (IIAB apps) are suggested during installation?
See: What are the default passwords?
See: Any other networking tips?
See: Can I upgrade IIAB software?
See: Can I upgrade or reinstall server apps?
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.

"apache_allow_sudo: True" is the default in /etc/iiab/local_vars.yml to make this possible.

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". FYI if do you change this variable's value in /etc/iiab/local_vars.yml, you should then run:

 cd /opt/iiab/iiab
 sudo ./runrole www_options

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

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

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

The best way is to run iiab-summary to get a quick ~20 line overview of your Internet-in-a-Box (IIAB) system.

Also, look for iiab_base_ver near the top of your /opt/iiab/iiab/vars/default_vars.yml. This is followed by a number like "8.1" showing the version level (even if you're running a pre-release of that version!) You can also look in /etc/iiab/iiab.env for the line(s) with "IIAB_RELEASE=".

Finally, your iiab branch name is visible if you log into your IIAB'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 typically shows "master" (or something like "release-8.1").

The 40-character "Commit ID" string gives more detail. You can compare this to commits within https://github.com/iiab/iiab/commits/master and https://github.com/iiab/iiab/releases — e.g. if you're running the older IIAB 8.0 from December 31, 2022, it would begin with 8f04d45.

CAUTION: the letter 'g' is confusingly sometimes added in front of such 7-character githashes (abbreviated from the full 40-character SHA-1 githash) in a few places, like the install image filenames at https://download.iiab.io/8.1/

See: Is a quick installation possible?
See: What are the default passwords?
See: Can I upgrade IIAB software?

Can I upgrade IIAB software?

Please understand this can DESTROY your Internet-in-a-Box if attempted on an older IIAB !

If your IIAB is more than a few weeks old, it's generally much better to install IIAB from scratch at https://download.iiab.io

But if you're willing to proceed AT YOUR OWN RISK (MAKE A BACKUP FIRST) here are instructions, if you've connected your IIAB to the Internet: (about 15 commands in total)

 sudo -i
 cd /opt/iiab/iiab
 git config branch.master.remote origin
 git config branch.master.merge refs/heads/master
 git checkout master           # If 'git branch' output shows 'master'
 git checkout -b master        # Or, create 'master' branch & check it out.
 git pull

WARNING: At this point it's best to regenerate your /etc/iiab/local_vars.yml settings and customizations, starting with a fresh copy from one of the 3 local_vars_*.yml files (SMALL-sized, MEDIUM-sized, or LARGE-sized) available in /opt/iiab/iiab/vars

WARNING: You may want to delete /opt/iiab/iiab/iiab_state.yml (to apply more force, AT YOUR OWN RISK!)

Then attempt to upgrade as follows:

 ./iiab-install --reinstall    # Takes about 10-20 min
 cd /opt/iiab/iiab-admin-console
 git config branch.master.remote origin
 git config branch.master.merge refs/heads/master
 git checkout master           # If 'git branch' output shows 'master'
 git checkout -b master        # Or, create 'master' branch & check it out.
 git pull
 ./install                     # Takes about 2-4 min

FYI the 2+2 "git config" lines above are NOT necessary if your .git/config file is already correct in each local repo (/opt/iiab/iiab and /opt/iiab/iiab-admin-console) as explained at https://stackoverflow.com/questions/658885/how-do-you-get-git-to-always-pull-from-a-specific-branch

FYI the 2+2 "git checkout" lines above are NOT necessary if each local repo is already on the master branch. You can run 'git branch' in each of the 2 above (local repo) directories, if you want to see what branch they're on.

See: What is local_vars.yml and how do I customize it?
See: How do I know what version of IIAB I'm running?
See: Can I upgrade or reinstall server apps?
See: Can I get content updates every few months or semester?
See: How do I back up, shrink & copy IIAB microSD cards?

Can I upgrade or reinstall server apps?

1) Most IIAB Apps can be reinstalled to the very latest available version when you're online, as follows:

 sudo -i
 cd /opt/iiab/iiab
 ./runrole --reinstall <APP OR ROLE NAME>

WARNING: Make a backup of ALL data and content first, if you do not want to take risks!

SPECIFICALLY: Each app does this a bit differently, but the general rule is to (try) to preserve all content and user data during an app reinstall.

CLARIFICATION 1: IIAB does not support offline reinstalls, as a general rule. In some cases however, you can run ./runrole --reinstall [APP OR ROLE NAME] even when offline, to reinstall certain apps to a cleaner/known state, e.g. whatever app version was most recently downloaded to your system.

CLARIFICATION 2: What is installed (and implicitly, what is not) can be viewed within /etc/iiab/iiab_state.yml


2) HIGH RISK: If your IIAB was recently installed, you can try to reinstall all of your apps to the latest available versions, and reinstall IIAB itself, as follows: (this could take a while!)

 sudo -i
 mv /etc/iiab/iiab_state.yml /etc/iiab/iiab_state.yml.old
 cd /opt/iiab/iiab
 git pull    # THIS LINE AT YOUR OWN RISK!
 ./iiab-install --reinstall

WARNING: Make a backup of ALL data and content first, if you do not want to take risks!

CLARIFICATION: IIAB does not support offline reinstalls, as a general rule. In some cases however, the above will still work even when run offline.


3) Prior to February 2020, IIAB implementers were advised to (at their own risk) individually delete the following files or directories, to attempt an upgrade or reinstall of these common server apps. And then run "cd /opt/iiab/iiab" then "./iiab-install --reinstall" or "./runrole --reinstall <ROLE NAME>" :

  • /library/www/nextcloud/version.php WAS /opt/nextcloud/version.php (Nextcloud version stored therein; reinstalls are easiest if you "sudo mysql" then "DROP DATABASE nextcloud;" (confirmed by "SHOW DATABASES;") and delete the entire /library/www/nextcloud WAS /opt/nextcloud). SEE ALSO: https://docs.nextcloud.com/server/latest/admin_manual/maintenance/update.html AND https://docs.nextcloud.com/server/latest/admin_manual/maintenance/upgrade.html
  • /opt/iiab/kiwix/bin/kiwix-serve (Run "/opt/iiab/kiwix/bin/kiwix-serve --version" to show kiwix-tools version number, since 3.0.2 on 2020-02-13.)
  • /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. Optionally, take a look in /library/pgsql-iiab/ outlined just 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" — or since early 2020 "cd /usr/local/calibre-web-py3; git log" — which can also be 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. Log in then click "Admin" at the top of http://box/books, at the bottom the current version number is listed, so long as you're on the "stable update channel" which is the default)
  • /library/games/minetest and/or /library/games/0.4.17.1 version number may vary! (delete these dirs as nec, to help force a reinstall of Minetest)
  • /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)
  • [Deletion of /library/wordpress is optional; online-upgrade is automatic/mandatory when running "./iiab-install --reinstall" or "./runrole wordpress" in /opt/iiab/iiab] Also Note: 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 database "iiab_wp" by running "mysql" as root, and then "drop database iiab_wp;" confirmed by "show databases;". Dropping the db is an easy way to change the language of WordPress' user interface — or this can also be done in http://box/wordpress > Settings > General > Site Language — and if the desired language is not one of your OS's installed locales, WordPress will try to download it.)
  • [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 "./runrole --reinstall 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 visible within http://box.lan/wiki/Special:Version and in dir name e.g. /library/mediawiki-ACTUAL.VERSION.NUMBER, as installed by /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)
  • [Upgrading a very recent version of Lokole MAY require deletion e.g. with "rm -rf /library/lokole"] In any case, attempt to install the latest Lokole using: "./runrole --reinstall lokole". (Lokole version is shown by "grep ^Version /library/lokole/venv/lib/python3.*/site-packages/opwen_email_client-*/*" [METADATA on some OS's, PKG-INFO on others]. If removing Lokole entirely, you may also want to clear out its Apache config files: "rm -rf /library/lokole /etc/apache2/sites-*/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; apt update then apt install kolibri can work to upgrade Kolibri since August 2022. CAUTION: Administrators need to type in the username kolibri when apt upgrading Kolibri as of 2022, due to Kolibri bug learningequality/kolibri-installer-debian#115] (Kolibri version shown by /usr/bin/kolibri --version — a full wipe/purge of Kolibri can be accomplished by apt purge kolibri and then removing [1] /library/kolibri [2] /etc/kolibri and [3] /usr/bin/kolibri as nec.)
  • [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 directories /opt/iiab/sugarizer-server/node_modules and MongoDB's entire /library/dbdata/mongodb)
  • [No file deletion required; online-upgrade is automatic/mandatory during "./iiab-install --reinstall" or "./runrole --reinstall gitea"] (High-level Gitea version is shown by "ls -l /library/gitea/gitea" — point release is shown at bottom-left of http://box/gitea)
  • After JupyterHub is installed, here are 2 ways to check the version number: (1) ls -d /opt/iiab/jupyterhub/lib/python3.*/site-packages/jupyterhub-* (2) http://box/jupyterhub -> log in (e.g. Admin/changeme) -> File menu -> Hub Control Panel -> Admin menu. If you want to reinstall JupyterHub from scratch, first delete directory /opt/iiab/jupyterhub — and read more about JupyterHub operations here: https://github.com/iiab/iiab/blob/master/roles/jupyterhub/README.md

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?

Can I get content 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.

Despite these obstacles, remote upgrades are becoming increasingly possible now that high-bandwidth connections are available within cities in the developing world. For Example: bringing a rural IIAB device into the city for a night (or a few days) to plug it into an online cablemodem, can be a very efficient and affordable way to update content — particularly within countries that offer unlimited downloads, at a fixed monthly rate.

Notwithstanding, terabyte download costs explain why drop-shipped hard drives containing "complete content catalogs" are often still more economic and efficient than downloading.

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, e.g. for schools with very high-bandwidth Internet connections. Note that older Content Packs can be individually be removed within Admin Console (http://box.lan/admin) > Manage Content, when there's a need to free up disk space. Likewise IIAB Apps such as KA Lite and Kolibri offer administrative interfaces, supporting deletion of lessons/videos within their environments, as well as downloading new ones.

As a practical matter, remote schools may receive larger updates via hard drive or USB memory stick every semester or every year — e.g. flown in or driven in or mailed in by a partner. Empowering them with new maps / encyclopedias / E-Books / video lessons — as well as other content and apps.

Keep in touch as new options evolve! Please make contact to keep up with other communities' offline content collections and recommendations.

See: What are the default passwords?
See: How do I customize my Internet-in-a-Box home page?
See: How do I add ZIM files, like Wikipedia?
See: Can I permanently attach an external USB drive, to add more content?
See: What are the best places for community support?

What security tips exist?

Please read more about the iiab-admin Linux user and group, which allow you to log in to IIAB's Admin Console:

Some IIAB installations 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 sudo rm /root/.ssh/authorized_keys

Whether running your server online or offline, please see 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?

Can I use HTTPS / TLS / SSL instead of HTTP?

This is impossible with an Internet-in-a-Box (IIAB) set up in a permanently OFFLINE school or community, as the World Wide Web Consortium sadly does not allow this (reasons explained here). Worse, those who try to force this with self-signed web server certificates find that everyday users (the world's poorest citizens, and others!) do not tolerate the complexity and hassle of scary browser pop-up overrides.

If however you're setting up an IIAB that will be ONLINE (with regular Internet access) then HTTPS encryption is thankfully easy to set up:

  1. Set gui_port: 443 in /etc/iiab/local_vars.yml preferably prior to installing IIAB. (Or if IIAB software is already installed, modify and then run /usr/bin/iiab-gen-iptables so that your iptables firewall opens up port 443 instead of port 80).
  2. After IIAB software is installed, edit /etc/nginx/server.conf to remove or comment out server_name $hostname; — instead set your actual domain name e.g. server_name MY-DOMAIN.ORG;
  3. Run:
    sudo -i
    apt install certbot python3-certbot-nginx
    certbot --nginx -d MY-DOMAIN.ORG
    
  4. The above certbot command asks you a few simple questions to help arrange auto-renewal of your web certificate every 60-to-90 days, before it modifies your /etc/nginx/server.conf (check this file carefully for any further manual modifications that you might require!)
  5. If you modified any NGINX (web server) configuration files, run nginx -t && nginx -s reload to validate then "reload" NGINX.
  6. Test HTTPS access to your IIAB, by browsing to your actual Internet domain name, e.g. https://MY-DOMAIN.ORG
  7. If you later need to manually renew your web certificate (e.g. if its Internet access is very unreliable) then consider commands like: certbot renew --dry-run, certbot renew --force-renewal or simply certbot renew

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

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

1. You can use https://remote.it to remotely support almost any IIAB. Simply run sudo iiab-remoteit at the Linux command-line (of any IIAB that is online) and it tells you what to do. And if necessary, long-form instructions are here: https://github.com/iiab/iiab/tree/master/roles/remoteit

2. Another option is OpenVPN permitting remote maintenance of your IIAB over ssh and http, among a core trusted group. This is a well-tested arrangement, likewise suitable for a wider enterprise's remote administration needs. (Alternatively the newer WireGuard can also be considered, as is now integrated with the Linux kernel.) #318 #1124

3. Smaller-scale implementers may prefer traditional Linux-and-ssh arrangements across firewalls using https://ngrok.com or https://dataplicity.com or https://www.zerotier.com — possibly in combination with router port-forwarding and Dynamic DNS services like No-IP (https://noip.com).

4. In all 3 above cases, consider low-bandwidth screen sharing using the screen command as explained in IIAB's Technical Contributors Guide.

5. Beginners may prefer graphical screensharing via Zoom, Google Meet, or TeamViewer "unattended access" especially if you have a graphical desktop environment on your Internet-in-a-Box. This can also be priceless when mentoring/learning at a distance, thanks to TeamViewer's screen-sharing, keyboard-sharing and mouse-sharing — helping to onboard new operators who aren't yet comfortable with 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.

And if you want, enable TeamViewer's fully "unattended access" by setting a more permanent password for remote access here: TeamViewer > Extras > Options > Security > Personal Password (for unattended access).

Raspberry Pi: If you're using the Raspberry Pi OS (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 version 15.51.5 as of 2024-03-16). 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 includes seamless ongoing upgrades via apt.

Bonus: headless installation/configuration is also now supported (e.g. on Raspberry Pi OS Lite) with "teamviewer info" "teamviewer passwd <ACTUAL-PASSWORD>" and "teamviewer help" per https://community.teamviewer.com/English/kb/articles/6318-how-to-install-teamviewer-for-linux.

Note: Developers' ssh keys may be included with IIAB install images, to facilitate remote support during Beta programs and similar. Read "What security tips exist?" if you want instructions to remove these keys.

Admin Console: if http://box.lan/admin shows red errors when you try to log in, please read the red messages and try reloading the page a minute later — you can also take a look at the output of: systemctl status iiab-cmdsrv.service

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?

Please consider AWStats and Matomo in the table above.

EXAMPLE — to help teachers understand which ZIM files are most popular:

  1. Ensure the following lines are in /etc/iiab/local_vars.yml
    kiwix_install: True
    kiwix_enabled: True
  2. If the above lines are newly added, run cd /opt/iiab/iiab then sudo ./runrole kiwix
  3. Visit http://box/awstats to view stats:

Background:

See: What services (IIAB apps) are suggested during installation?
See: What is local_vars.yml and how do I customize it?

How do I add ZIM files, like Wikipedia?

Please read "How do I customize my Internet-in-a-Box home page?" Several HOW-TO videos on Internet-in-a-Box's YouTube channel (some available as .mp4 and .webm) can also help you install content onto your IIAB:

1. To download ZIM files, log in to your Internet-in-a-Box's (IIAB) Admin Console (http://box.lan/admin) -> Install Content -> Get ZIM Files from Kiwix

2. Or, if you already have content on hand (like ZIM files or OER2Go/RACHEL modules) on a portable USB disk or USB flash drive, insert the USB drive into your Internet-in-a-Box (IIAB). Then use your IIAB's Admin Console (http://box.lan/admin) -> Install Content -> Manage Content to copy the content you need, installing it onto your IIAB:

  • The USB drive must have the same /library layout as your IIAB:
    • ZIM files belong in /library/zims/content
    • OER2Go/RACHEL modules belong in /library/www/html/modules
  • Copying content works in both directions! (You can also copy ZIM files and OER2Go/RACHEL modules from your IIAB to the USB drive — to bring content to another IIAB, community or school.)

3. Or, if you prefer the command-line, download the ZIM file you want (e.g. from https://download.kiwix.org/zim/) directly to your IIAB's /library/zims/content — for example:

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

Then run /usr/bin/iiab-make-kiwix-lib to update your IIAB's ZIM file index:

 sudo iiab-make-kiwix-lib

While rarely necessary, if you need to completely rebuild your IIAB's ZIM file index, run:

 sudo iiab-make-kiwix-lib -f

4. Finally, whichever approach you choose above, test that your new ZIM file(s) are browsable at http://box/kiwix and that search features (at the top-right of the page) are working!

IN FUTURE:

  • Students may be able to take small ZIM files home with them, on their own phones.
  • Teachers might be able to auto-display (or auto-install) ZIM files from USB sticks/drives inserted into any IIAB: #857 #1538

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) the ZIM comes with associated index files that must be placed in /library/zim/index — please see: https://github.com/iiab/iiab/tree/master/roles/kiwix#readme

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, also here) 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 sudo ./runrole transmission then sudo 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 https://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 /opt/iiab/iiab-factory/content/khan/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 8006" (make sure your mk-other-kalite is up-to-date!)

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-admin-console/roles/js-menu/templates/config.json.j2 (live at /library/www/html/js-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). A separate/crude hack to get other languages to work with ports 8006 or 8007 is to put "lang": "fr", or "lang": "es", in the .json file in the /library/www/html/js-menu/menu-files/menu-defs directory.

More Documentation? Please see the original KA Lite README.

Changing Calibre's port is similar: Modify calibre_port (e.g. from port 8080) in /etc/iiab/local_vars.yml prior to installing IIAB, which you can later confirm in /library/www/html/js-menu/config.json

What about Kolibri, also from Learning Equality? Please see the Kolibri README.

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

How do I add zoomable maps for my region?

Please explore our Live Demo and read our new IIAB Maps instructions from May 2022 for IIAB 8.0, which explains:

INVITATION: If you can help ongoing efforts to polish maps for children in offline schools in all countries, directly contributing to beautifying OpenStreetMap (VIDEO) 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.
  • If you must change it later, follow the WordPress instructions for Changing The Site URL which offers 5 different ways to get this done, 2 of which involved editing /library/wordpress/wp-config.php
  • Please review your options at #3071.

How do I optimize Matomo or PBX or WordPress for high-traffic usage?

  • Then run cd /opt/iiab/iiab followed by sudo ./runrole www_options and then reboot.
  • Of course, make sure your Internet-in-a-Box has enough RAM and disk! Background: #1147

Optionally you might further customize the 6 settings {upload_max_filesize, post_max_size, max_execution_time, max_input_time, memory_limit, max_input_vars} in both /etc/php/<ACTUAL VERSION NUMBER>/*/php.ini files (reboot if so!) This is best done prior to IIAB's install, within /opt/iiab/iiab/roles/www_options/tasks/php-settings.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!

How do I set the Moodle URL (like http://box.lan/moodle) so it works for everyone?

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?

How do I add TuxMath?

Run this:

 sudo -i
 cd /library/www/html/modules
 git clone https://gitlab.com/Afrikalan/tuxmath-js --depth 1
 rm -rf tuxmath-js/.git*

Using Admin Console, set up a menu item on your IIAB home page, to help students access http://box/modules/tuxmath-js

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

How do I add Scratch-like “Snap!” ?

Run this:

 sudo -i
 cd /library/www/html/modules
 git clone https://github.com/jmoenig/Snap en-snap -b v9.2.13 --depth 1
 rm -rf en-snap/.git*

Using Admin Console, set up a menu item on your IIAB home page, to help students access http://box/modules/en-snap (or similar!)

Examples:

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

Captive Portal Administration: What tips & tricks exist?

When installed on Raspberry Pi OS, 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://10.10.10.10) 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.

DEVELOPERS: please see the Captive Portal README.md for a high-level summary of its mechanics and how it works, then look through the code here: https://github.com/iiab/iiab/tree/master/roles/captiveportal/

CAUTION: IIAB's Captive Portal is experimental, so you need to try it on the smartphones and client devices most common in your community. Please also see these older Known Issues.


Captive Portal is installed but not enabled in IIAB 8.1. Here are instructions to enable it:

  • sudo -i
  • Run 'nano /etc/iiab/local_vars.yml' to set both these variables: (typically around Lines 379-380)
 captiveportal_install: True
 captiveportal_enabled: True
  • cd /opt/iiab/iiab
  • ./runrole captiveportal     # Or, if necessary: ./runrole --reinstall captiveportal


Conversely, note that many schools prefer to disable Captive Portal entirely, which can be done as follows:

  • sudo -i
  • Run 'nano /etc/iiab/local_vars.yml' to set this variable to False: (typically around Line 342)
 captiveportal_enabled: False
  • cd /opt/iiab/iiab
  • ./runrole captiveportal


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 and browser!

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?

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?
See: WordPress & Moodle Administration: What tips & tricks 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    # Or if the device is partitioned: mkfs.ext4 /dev/sdXN

Before running the above, change 'X' (and 'N' if necessary) to correspond 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' (and 'N' if necessary) before you run:

 e2label /dev/sdX IIAB-LIBRARY-EXT    # Or if the device is partitioned: e2label /dev/sdXN 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

Alternatively, a popular option is to put ALL your content in the USB drive's own top-level library folder. (This works well with Admin Console -> Install Content -> Manage Content to import/export content.) BONUS: If you choose this approach, you can avoid creating the symbolic link[s] mentioned further below!

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

Either way, create the needed mount point on your IIAB, by running:

 mkdir /library-ext

After you've tested that your USB drive automounts correctly on boot, create any 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: Use the very same IIAB to set up and verify that the external USB drive's file ownership and read/write permissions work (e.g. use Linux commands chown and chmod if necessary).

CLARIF 4: 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.

CLARIF 5: Another way to do this (e.g. on a more temporary basis) is "bind mounting" as mentioned at #2679, #3106 and "What is a bind mount?"

CLARIF 6: If your Linux OS has a graphical desktop, it's common to see popup message warnings like:

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

It's safe to ignore these messages. Or you can make these popup messages go away, typically by clicking through your graphical File Manager's preferences or OS settings, and unchecking the box for "Mount removable media automatically when they are inserted" or "Automatically mount removable media when inserted and on startup." #86

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?
See: Can I install IIAB onto a USB drive?

Can I install IIAB onto a USB drive?

This can fail with consumer-grade hardware, because the boot device's USB 3.0 frequencies (e.g. radiating from a USB flash drive, Raspberry Pi "hat" or other peripheral — especially those lacking a ferrite RF choke and/or lacking proper USB3 cable shielding) very often interfere with the Raspberry Pi's internal Wi-Fi.

As explained in #2638, raspberrypi/firmware#1430 and this 2012 Intel White Paper:

 USB 3.0 Radio Frequency Interference Impact on 2.4GHz Wireless Devices
 
 https://www.usb.org/document-library/usb-30-radio-frequency-interference-impact-24-ghz-wireless-devices (PDF)

DO THIS FIRST: A 1st order test of the quality of your hardware is to set up USB 3.0 boot (do this prior to installing IIAB) then connect to your building's 2.4GHz (NOT 5GHz !) Wi-Fi — without an Ethernet cable! Then carefully test web/online tasks like running apt update, downloading large files, ping mit.edu, etc — evaluating packet loss over many minutes to be sure. (If your hardware/layout cannot function reliably as a Wi-Fi client device, don't even bother trying to set it up as an Internet-in-a-Box learning hotspot!)

This can work however, if you've acquired the right RF-shielded hardware, and set it up carefully. So if you've carefully validated your hardware/setup's ability to work with 2.4GHz Wi-Fi, then installing Internet-in-a-Box (IIAB) onto a USB stick or USB drive is possible — e.g. by following Shanti Bhardwa's Steps 1 to 14 (#2585) — or Dirk Uys' Steps 1 to 14 (#1799) for Raspberry Pi 3-and-higher.

For Raspberry Pi Zero W, Step 17 will also be necessary (copying bootcode.bin to the first partition).

THEFT WARNING: Of course there is a risk your USB (flash or hard disk) drive might be stolen, as there's always a temptation for others to "borrow" external USB devices. For many similar/such practical reasons, an IIAB microSD card (placed inside the Raspberry Pi) usually makes much more sense.

PRIVACY AND SECURITY WARNING: If you're booting from a USB device (e.g. an external disk or flash drive) please set usb_lib_enabled: False in /etc/iiab/local_vars.yml prior to installing IIAB, so that your filesystem is not viewable at http://box/usb. You can also do this after installing IIAB, using Admin Console (http://box.lan/admin) > Content > Services Enabled > USB based content libraries (uncheck the checkbox) > Save Configuration > Install Configured Options — give it 1-2 minutes and then verify that this completed in Utilities (menu) > Display Job Status — and finally reboot. (#2552)

See: What hardware should I use?
See: What is local_vars.yml and how do I customize it?
See: Can I permanently attach an external USB drive, to add more content?

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 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. Self-Clone your entire Internet-in-a-Box (IIAB) e.g. to an external microSD card, using IIAB's Admin Console http://box.lan/admin > Install Content > Clone IIAB (details).

  • This approach works to copy to another brand/model of microSD card that happens to be a few bytes smaller!
  • Copy from your IIAB's internal microSD to an external microSD (placed in a microSD card reader/writer, that plugs into one of your IIAB's USB ports).
  • This is based on piclone_cmd (similar to rpi-clone) which brings the Raspberry Pi's "SD Card Copier" approach below (piclone) to the command-line, and other platforms and OS's (e.g. 64-bit Ubuntu not just 32-bit Raspberry Pi OS) (#2268).
  • This approach can be slower than 3. and 4. (below) but is far easier to understand (and a real lifesaver in the field, when duplication hardware/peripherals/adapters are often scarce!)
  • 2022-09-09 WARNING: PLEASE USE APPROACH 2. (BELOW) IF POSSIBLE — AS APPROACH 1. (ABOVE) OFTEN FAILS TO START PROPERLY WITHIN THE 1ST MINUTE (#3362).

2. Likewise a very easy/friendly approach is possible if you have access to the "Desktop" (graphical) version of Raspberry Pi OS. Simply click the Raspberry start menu (top-left of screen) > Accessories > SD Card Copier:

  • This approach 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 its Help screen instructions. For a quick summary from the original May 13, 2016 announcement, see the "SD card copier" section which is the third headlined section in "The latest update to Raspberry Pi OS" (look below sections "Bluetooth" and "Bluetooth audio").
    • The underlying command is piclone.
    • This approach can be slower than 3. and 4. (below) but is far easier to understand (and a real lifesaver in the field, when duplication hardware/peripherals/adapters are often scarce!)

3. On Linux or macOS, we strongly recommend the built-in command dd if you are comfortable at the command-line.

  • 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).
  • On macOS, 'dd' will run extremely slowly if you don't use macOS's own special syntax. So we recommend this macOS recipe, as an example:
  • Insert a brand new microSD card
  • Determine mount point of card: diskutil list
  • Unmount card (this presumes its mount point is /dev/disk2): sudo diskutil unmountDisk /dev/disk2
  • Copy source file (e.g. source.img) from Mac's disk to card: sudo dd if=source.img of=/dev/rdisk2 bs=4m status=progress
  • Helpful Tip: The "r" device (e.g. /dev/rdisk2 NOT /etc/disk2) is the raw one. It should let you write 1 byte at a time, and is ~20X faster.
  • Helpful Tip: If your macOS is older and status=progress doesn't work, you can type ctrl-T at the shell running dd to send it the INFO signal, to provide you a snapshot of how much has been transferred.
  • Eject card: sudo diskutil eject /dev/disk2

4.1 On Windows 10/11, strongly consider dotNet Disk Imager which is a "dotNet equivalent to Win32 Disk Imager, but more lightweight and with more features." [Several of us use this on Windows 8 and Windows 10, e.g. Tim Moody writes: "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"].

4.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.

5. Is it possible Clonezilla can do part of this job? Clonezilla (unlike FileZilla) 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?
See: Can I install IIAB onto a USB drive?

What are the best places for community support?

1) The fastest response will arise if you post a "New issue" here:

Those who do not have GitHub accounts should consider creating one.

Describe your issue in full (with context) so that others may help — including screenshots if possible — and the ACTUAL PASTEBIN URL that is generated after you run sudo iiab-diagnostics

2) Or consider posting to our technical discussion forum:

3) For field/community topics, consider getting in touch using Twitter:

4) And don't hesitate to also write to our mailing list!

FOCUS: teachers/content/learning/libraries. Please take inspiration from our earlier work with almost a thousand "One Laptop Per Child" global grassroots communities, enabling their nearby educational communities to connect on a local level, very powerfully and directly Helping Each Other: http://olpcMAP.net


5) BUSINESS CONTACT: if you need to get in touch regarding strategic alliances or partnerships with Internet-in-a-Box, please email Adam Holt (holt @ unleashkids.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?

Please see the Contributing section of Internet-in-a-Box.org

Technical developers please (1) consider our Technical Contributors Guide and (2) look through the tasks in our upcoming milestones.

Implementers and IT people please contact us if you can help improve this very (wiki i.e. editable) document (FAQ.IIAB.IO) as well as our GitHub Tech Docs.

Librarians, videographers and designers are needed to help us deepen our communications — please make contact directly if you're able to help!

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 our community mailing list:

In 2023, serious digital librarians and humanitarian scrapers are also invited to join our content engineering design discussions that bring together all countries — building off our original Medical & Educational Content Hackathon back in 2017 — but now refining "web scraping" techniques for entirely new (categories of) very-high-quality Content Packs. Don't hesitate to make contact!

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?

Release History:

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

Older RPM builds from 2013 may be available from https://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 professionals, 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!