thinRoot is a buildroot (https://buildroot.org/) powered operating system environment to create lightweight user-defined kiosk systems or ThinClients for generic x86_64 hardware (e.g. intelNUC, standard PCs, Laptops, etc.) or single-board computer (SBC) driven embedded systems (RaspberryPi, ASUS Tinkerboard, etc.) to smoothly connect to server-based desktop environments (Linux/Windows Terminalserver, VDIs, etc.) via included ThinLinc, RDP (xfreerdp), VNC, SPICE, etc. clients or to create simple web-kiosk systems displaying a single fullscreen webpage upon bootup.

🍪 Features

• allows to be setup as a lightweight and generic ThinClient system which after bootup providing a simple connection GUI (using qutselect) with options to connect via ThinLinc, RDP (via freerdp), VNC or SPICE to Linux- or Windows-based desktop systems (Terminalserver, VDI, etc.) including potential USB device redirection/forwarding.
• allows to be setup to start only a fullscreen webbrowser (via WebKit/MiniBrowser) for simple fullscreen webkiosk use-cases.
• direct support for SPICE-based connections to SPICE-enabled VDI systems hosted via ProxmoxVE including cluster proxied connection support.
• boots and operates completly in a full-fledged RAM disk with no mandatory local disk storage requirements.
• allows to be booted solely using existing PXE+TFTP/HTTP+DHCP-based netboot environments or to directly install the thinRoot images onto a small local boot disk.
• allows to use a TFTP/HTTP-connected bootserver: fetches environment files from a bootserver which then can be used to define alternative system bootup procedures (based on the hostname/MAC of the client system) by simply changing these environment files on the TFTP/HTTP bootserver.
• highly optimized for a small footprint: compressed kernel and system for fast network-based bootup use-cases.
• easily adaptable to other potential use cases apart from simple web-kiosk or ThinClient environment uses.
• can be easily enhanced to support more x86/ARM-based hardware.

💻 Requirements

1. A supported x86_64/ARM-based hardware. Well working and tested hardware:
   • All generic x86_64-based hardware (e.g. Intel NUC, modern Laptops, etc.) which come with directly supported PXE boot capabilities (Legacy or UEFI) in the BIOS.
   • All ARM-based single board computer (SBC) systems supported by the U-Boot bootloader which is used to provide a common way to boot the kernel and initrd via network. This includes:
     • RaspberryPi5 Model B, RaspberryPi Compute Module 5, RaspberryPi 500
     • RaspberryPi4 Model B, RaspberryPi Compute Module 4, RaspberryPi 400
     • RaspberryPi3 Model B+, RaspberryPi3 Model B, RaspberryPi3 Model A+, RaspberryPi Compute Module 3, RaspberryPi Zero 2 W
     • TinkerBoard S, TinkerBoard
2. An already working PXE+TFTP/HTTP+DHCP bootserver environment where the thinRoot images and its environment files can be installed and directly accessed upon bootup via TFTP/HTTP sideloading.
3. In case of a ThinClient use-case: A network-based desktop environment (e.g. Windows Terminalserver, VDI system, etc.) to connect to via ThinLinc, RDP, VNC or SPICE protocol.
4. In case of a web-kisok use-case: A web page that can be configured using a bootserver-definable environment file so that thinRoot automatically starts as a lightweight web-kiosk.

☁️ Quick-Installation

The installation of thinRoot is quite straight forward as it is delivered as fully network bootable system images which boot directly into a RAMdisk using images hosted by a an already existing PXE+TFTP/HTTP+DHCP environment:

1. Download latest release zip archive for the hardware platform you are interesed in:
   • generic-x86_64
     1. Put the unarchived *.img file into your tftpboot PXE environment (e.g. under /tftpboot/thinroot).
   • RaspberryPi, Tinkerboard:
     1. Put the unarchived *-[platform]-kernel.img and *-[platform].img file into your existing tftpboot PXE environment where [platform] corresponds to your chosen hardware image.
     2. Use an imaging tool (e.g. Etcher to flash the included *-[platform]-sdcard.img files to a fresh microSD card or USB thumb drive.
     3. Modify the /boot/bootEnv.txt file in the FAT32 boot partition to match your TFTP/HTTP bootserver setup.
2. Make sure your PXE+TFTP/HTTP+DHCP/bootserver provides the image files also via HTTP (e.g. using a nginx proxy against /tftpboot).
3. (generic-x86_64): Modify your PXE+TFTP/HTTP+DHCP/bootserver environment to load the corresponding *.img via HTTP and with the following APPEND line
   • iPXE/UEFI boot environment:

     set root-path http://192.168.74.30/thinroot/
     kernel ${root-path}thinroot.img
     imgargs thinroot.img BOOT_IMAGE=${root-path}/thinroot.img console=tty2 noswap noinitrd consoleblank=120 init_on_alloc=1 init_on_free=0 slab_nomerge net.ifnames=0 intel_iommu=igfx_off quiet loglevel=0

   • Syslinux/Legacy boot environment:

     LABEL      thinroot
     MENU LABEL ^thinRoot (stable)
     KERNEL     http://192.168.74.30/thinroot/thinroot.img
     APPEND     console=tty2 noswap noinitrd consoleblank=120 init_on_alloc=1 init_on_free=0 slab_nomerge net.ifnames=0 intel_iommu=igfx_off quiet loglevel=0

4. (rpi*, tinkerboard*): Modify the /boot/bootEnv.txt file on the microSD card/USB thumb drive to match your PXE+TFTP/HTTP+DHCP environment:

   bootserver=192.168.74.30
   kernel_img=thinroot/thinroot-tinkerboard-kernel.img
   initrd=thinroot/thinroot-tinkerboard.img
   extraargs=BASE_PATH=http://192.168.74.30/thinroot
   

   Make sure to remove comments (#) from lines which are required and modify the pathes to match your PXE+TFTP/HTTP+DHCP environment. For example, it might also simply be enough to just enable the extraargs=... line if you want the image on the microSD card itself to be booted. However, if you want to fetch the kernel image and initrd from the bootserver make sure to uncomment these lines as well.

😋 How to contribute

As the thinRoot project is an open source based project everyone is invited to contribute to this project. So, if you are a talented developer and want to contribute to the success of thinRoot feel free to send over pull requests or report issues / enhancement requests. Please note, however, the licensing and contributing implications and accept that - in short - anything you contribute to this repository/project (especially source code) will be (re)licensed under the Apache 2.0 license (see CONTRIBUTING.md). In addition, please understand that we will only accept contributions (either source code or issues in the issue tracker) if these comply to our CODE OF CONDUCT.

💰 Donations

Even for those that don't have the technical knowhow to help developing on thinRoot there are ways to support our development. Please consider sending us a donation to not only help us to compensate for expenses regarding thinRoot, but also to keep our general development motivation on a high level. So if you want to donate some money please feel free to send us money via PayPal. And if you are running a business which might integrate thinRoot in one of your products please contact us for a regular donation plan which could not only show that you do care about open source development, but also could secure your product by ensuring that development on thinRoot continues in future.

🚧 Development

Building your own thinRoot image is a very straight forward process using this build environment – given that you have sufficient Linux/Unix knowledge and you know what you are actually doing. But if you know what you are doing and which host tools are required to actually be able to run a thinRoot build, it should be as simple as:

$ git clone https://github.com/jens-maus/thinRoot
$ cd thinRoot
$ make PRODUCT=generic-x86_64 release
[wait up to 1h]
$ cp release/thinroot-YYYYMMDD-generic-x86_64.img /tftpboot/thinroot/

📜 License

The thinRoot build environment itself – the files found in this git repository – as well as the thinRoot images are licensed under the conditions of the Apache License 2.0. Please note, however, that the buildroot distribution thinRoot is using is licensed under the GPLv2 license instead.

👪 Authors

See Contributors for a complete list of people that have directly contributed to this project.