This repository contains build scripts and filesystem skeletons for
bootable minibase images. There are two of them currently, encrypted
and non-encrypted, both based on Buildroot. When built, the images
will contain just enough to run Weston and (if the hardware is present)
connect to a wifi network.

The images should be bootable with qemu as well as with reasonably recent
x86_64 hardware with Intel graphics (and preferably iwlwifi wireless card).

WARNING: buildroot takes lots of time and about 6GB of space to build.


Pre-built images
~~~~~~~~~~~~~~~~
Check Releases tab, and skip to Booting with qemu below.
https://github.com/arsv/miniroot/releases

  sys-plain is bootable image with non-encrypted rootfs.
  sys-crypt is bootable image with encrypted rootfs.

  miniroot contains complete initrd+bootfs+rootfs tree
    for those who'd like to take a look at the files but
    do not want to bother with mounting disk images.


System contents
~~~~~~~~~~~~~~~
The resulting images contain
	
	* ~4MB kernel
	* ~6MB of kernel modules
	* ~9MB of firmware blobs for iwlwifi
	* ~550KB of minibase tools
	* ~1MB musl+busybox (the latter only used for interactive shell)
	* about 30MB of weston and its dependencies
	* about 7MB atop of that for xwayland support

Ignoring root shells (which shouldn't be there in a real system),
the `weston` executable is the first one to load libc during boot.


Prerequisites
~~~~~~~~~~~~~
The host system need a usable GNU toolchain:

	* common POSIX tools
	* binutils, gcc, make
	* wget to download the sources

Also must be available:

	* mtools
	* syslinux, with files in /usr/share/syslinux
	  (tweak the scripts if the files are in another location)

Buildroot could be used to build both, but most system have them as packages
anyway so why bother.


How to build the images
~~~~~~~~~~~~~~~~~~~~~~~
Download https://buildroot.org/downloads/buildroot-2017.08.tar.bz2,
unpack it and rename the directory into ./buildroot.

# If the host system runs glibc-2.26:
#
#	cp brvendor/package/flex/0002*.patch buildroot/package/flex/
#
# otherwise the build will fail.

Clone (or download and unpack) https://github.com/arsv/minibase to ./minibase.
Build minibase:

	cd minibase
	./configure
	make
	make install    # this will install into ./out

Build the rest of the buildroot system:

	cd buildroot
	make BR2_EXTERNAL=../brvendor minibase_defconfig
	make            # this will take lots of time

Assemble plaintext image:

	cd sys-plain
	make

Assemble encrypted image:

	cd sys-crypt
	make

The first sys-crypt build will generate image encryptions keys which will
then be re-used unless removed manually. The tool will ask for passphrase
when generating the keys, and then once again to unlock the keys when
encrypting the image. Any subsequent run will only ask for passphrase to
unlock the keys.


System structure
~~~~~~~~~~~~~~~~
At the end of the build, the complete contents of initrd, bootfs and rootfs
will be in respective directories. Feel free to investigate them.

The kernel invokes initrd/init on startup. That script in turn execs into
rootfs/sbin/system/start which is a script as well.

The system is assembled by merging the contents of minibase/out,
buildroot/output/target, and dropin/. The first two provide executables while
the files from dropin determine system configuration.


Booting with qemu
~~~~~~~~~~~~~~~~~
Run xqemu.sh in respective directories:

	cd sys-plain
	./xqemu.sh

The scripts will attempt to run qemu with -enable-kvm.

Password for sys-crypt is "swordfish".


Booting with real hardware
~~~~~~~~~~~~~~~~~~~~~~~~~~
Write the image onto usb stick:

	cd sys-crypt
	dd if=whole.img of=/dev/sdb   # make sure it's the right device

and try to persuade the box to boot from that.

The image should be both BIOS and UEFI bootable on x86_64 hardware.
Mixed-mode UEFI (32-bit UEFI on 64-bit CPU) may or may not work.

There is absolutely nothing minibase-specific about booting the system,
any configuration that will get the kernel and initrd into the memory
should work. Feel free to experiment.

The system uses MBR ID 0x11223344 to find its boot media.


Getting around the system
~~~~~~~~~~~~~~~~~~~~~~~~~
The system is configured to be usable in qemu. VT switch combos are C-Fx,
not C-A-Fx as usual.

The system should boot into Weston running on VT3. Tap C-F4 to switch to
another Weston instance (starting it if necessary) on VT4. Tap C-F2 for a
root console. There's another root console on ttyS0 (serial). In qemu,
press C-A-3 to access it.

Use `svctl` to query top-level supervisor:

	svctl                  # process list
	svctl -t udevmod       # stop udevmod
	svctl -s udevmod       # start it again
	svctl -P               # poweroff

	svctl keymon           # properly running service
	svctl badsrv           # failed service

Use `vtctl` to control vtmux:

	vtctl 4                # switch to VT4

Use `wictl` to scan/connect to network:

	wictl -s               # scan wifi
	wictl -p blackhole     # ask passphrase and connect to a named AP

The above only works if there are any wifi devices available. Wired interfaces
may be queries and initialized using ifctl:

	ifctl                  # show networking devices
	ifctl -a [dev]         # bring up and dhpc dev

The interactive shell is busybox sh, and there's a bunch of common commands
provided by busybox as well. If network is connected, try

	ping example.com       # should not work with non-suid busybox
	sudo ping example.com  # should work

Tap C-Esc to bring up the control VT. Shift-R to reboot, Shift-P to poweroff.

If running on real hardware, press C-Power to power the system off, and hold
C-A-Del for about a second to reboot.


Troubleshooting and caveats
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Errors at "Waiting for devices" stage indicate lack of necessary modules,
especially USB-related.

Weston may not display cursor in qemu upon boot. Try switching VTs (C-Esc Esc)
to force reinitialization. Not a minibase issue as far as I can tell at this
point. Should work much better on real hardware.

Weston may pause on startup in qemu, showing its startup message with
non-blinking cursor. Try moving the VM mouse. Seems to be related to missing
mouse cursor issue above.

Weston degrades into unusable mess when running in non-KVM qemu. Apparently
the slow emulated CPU breaks some frame sync assumptions. Without KVM, it may
also take something like 5+ seconds to start, showing blank screen in process.

The kernel is configured for the hardware I have at hand. Feel free
to reconfigure if necessary. Sadly enabling everything is not an option
for a system that aims to be "small".

No wireless interfaces on HW with a supported Intel card likely likely means
no firmware for this particular card. Try to figure out which file it needs,
and drop it to /lib/firmware.