iiab/roles/usb_lib at master - external/iiab

mirror of https://github.com/iiab/iiab.git synced 2025-02-12 11:12:06 +00:00

History

A Holt 1ec743a654 70-usb-library.j2: Fix logger string quotation marks		2025-02-11 10:42:05 -05:00
..
defaults	Begin to remove iiab_usb_lib_show_all and IIAB_USB_LIB_SHOW_ALL	2025-01-25 15:47:56 -05:00
files	usbmount copyright URL clarifs for PR #3929	2025-01-31 04:24:07 -05:00
tasks	usb_lib/README.rst, usb_lib/tasks/install.yml: Add docs on how to disable Desktop auto-mount functionality on RPi Desktop; other minor doc cleanup	2025-02-02 20:44:02 +00:00
templates	70-usb-library.j2: Fix logger string quotation marks	2025-02-11 10:42:05 -05:00
README.rst	Further update usb_lib/README.rst	2025-02-02 16:22:38 -05:00

README.rst

==============
usb_lib README
==============

**PLEASE SEE** `"Can teachers display their own content?" <https://wiki.iiab.io/go/FAQ#Can_teachers_display_their_own_content?>`_ **AND** `"Can students upload their own work?" <https://wiki.iiab.io/go/FAQ#Can_students_upload_their_own_work?>`_ **WITHIN https://FAQ.IIAB.IO FOR UP-TO-DATE DOCUMENTATION!**

This role (1) implements functionality similar to LibraryBox, to mount "teacher content" from USB sticks / drives for students, and (2) allows students to upload their work to the teacher's USB stick / drive:

#. Students should have nearly immediate access to "teacher content" (on all inserted USB sticks) by browsing to http://box/usb.
#. Students can also click the "Upload to USB" button on top of this same page (http://box/usb), to upload their work to the teacher's USB stick.  (FYI student uploads appear in folders like ``UPLOADS.YYYY-MM-DD`` within the root of the teacher's USB stick).

As of January 2025, automount is handled by usbmount: (`devmon included with udevil <https://ignorantguru.github.io/udevil/>`_ might be considered in future)

* A script in this role (/etc/usbmount/mount.d/70-usb-library) looks in the root of the mounted USB stick for folder /PUBLIC and if found, creates a symlink of the form /library/www/html/local_content/USBn pointing to /media/usbn/PUBLIC — where n is generally one of {0, 1, 2, 3, 4, 5, 6, 7}.  *RESULT: Only documents within /PUBLIC are browsable by students.*  This option is very useful to **prevent students from copying uploaded homework!**
* If however folder /PUBLIC is not found, the symlink is created to the root of the mounted USB stick.  *RESULT: EVERYTHING on the USB stick is browsable by students — just like with a traditional community bulletin board.*  This option is very useful when students are uploading artwork, photo essays, personal audio recordings and **science projects that are intended to be shared!**

Technical Details:

* USB sticks / drives must be formatted with one of the filesystems listed under "FILESYSTEMS=" at ``/etc/usbmount/usbmount.conf`` — these are specified on/around Line 17 of: `/opt/iiab/iiab/roles/usb_lib/files/usbmount/usbmount.conf <https://github.com/iiab/iiab/blob/master/roles/usb_lib/files/usbmount/usbmount.conf#L17>`_

* If your IIAB was built on a Graphical Desktop OS (instead of a headless OS, like Raspberry Pi OS Lite), USB sticks will problematically be mounted twice by default, once by usbmount and once by the desktop.  You must disable the automount function in the Desktop in order to use the "Upload to USB" functionality, which allows students to upload their work to your USB stick.

  * EXAMPLE: To disable Desktop automount within "Raspberry Pi OS with desktop", go to File Manager (pcmanfm) → Edit → Preferences → Volume Management, and uncheck "Mount removable media automatically when they are inserted".

* IIAB will generally mount USB sticks / drives 'rw' allowing root to both read and write to them.  In addition, in March 2021 (`PR #2715 <https://github.com/iiab/iiab/pull/2715>`_) Kolibri exports were enabled, by also giving non-root users read and write access to VFAT/FAT32, NTFS and exFAT USB sticks — using ``umask=0000`` (in /etc/usbmount/usbmount.conf) to override the ``umask=0022`` default.  This ``umask=0000`` is also required for students to upload to the teachers's VFAT/FAT32, NTFS and exFAT USB sticks, as introduced in January 2025 (`PR #3875 <https://github.com/iiab/iiab/pull/3875>`_).  If, however, you prefer to restore usbmount's default, set ``usb_lib_writable_sticks: False`` in `/etc/iiab/local_vars.yml <http://FAQ.IIAB.IO/#What_is_local_vars.yml_and_how_do_I_customize_it%3F>`_ — please do this prior to installing IIAB — so you don't have to run: ``cd /opt/iiab/iiab ; ./runrole --reinstall usb_lib``

* Official `usbmount 0.0.22 (2011-08-08) <https://github.com/rbrito/usbmount/tags>`_ documentation:

  * https://github.com/hfuchs/usbmount/blob/master/README (2010-08-11)
  * https://github.com/rbrito/usbmount/blob/master/README.md (2018-08-10)
  * https://github.com/rbrito/usbmount/blob/master/usbmount.conf (2010-04-25)

* Dev Notes at the top of: https://github.com/iiab/iiab/blob/master/roles/usb_lib/tasks/install.yml

  * January 2025 work to improve automount reliability during boot: `PR #3916 <https://github.com/iiab/iiab/pull/3916>`_