README

This repository contains build scripts and filesystem skeletons for
bootable minibase images based on Buildroot. When built, the images
will contain just enough to run X, Weston and (if the hardware is there)
connect to a wifi network.


Pre-built images
~~~~~~~~~~~~~~~~
To try the system without going through the whole build process,
download either sys-plain.tar.xz or sys-crypt.tar from

  https://github.com/arsv/minibase-br/releases

To see how the system is assembled download prebuilt.tar.xz and follow
the build instructions below.


System contents
~~~~~~~~~~~~~~~
The resulting images contain
	
	* ~3MB kernel
	* ~6MB of kernel modules
	* ~7MB of firmware blobs for iwlwifi
	* ~650KB of minibase tools

	* ~600KB musl (not needed for minibase)
	* ~200KB dropbear
	* ~100KB of kilo and dash (needed for X)

	* about 30MB of X, weston and their dependencies
	  (hard to tell apart at this point)

Current configuration does *not* include busybox and runs solely
on minibase. The point of these images is to showcase minibase,
not to be usable.


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

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

and also

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

Syslinux is difficult to work with, so for now the scripts rely
on the host distro to provide it.


How to build the images
~~~~~~~~~~~~~~~~~~~~~~~
Download and unpack prebuilt.tar.bz2.

# This tarball was built from buildroot-2017.08.tar.bz2, using configuration
# in ./brvendor (as BR2_EXTERNAL). It can be re-built, but the process is quite
# long and completely irrelevant for the purpose of showcasing minibase.

Update ./minibase and build it:

	git submodule update --init
	cd minibase
	./configure
	make
	make install    # this will install into ./out

Assemble plaintext image:

	cd sys-1-plain
	make

Assemble encrypted image:

	cd sys-2-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 unwrap the keys when
encrypting the image. Any subsequent run will only ask for passphrase to
unwrap the keys.


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

	cd sys-1-plain
	./xqemu.sh

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

The password for sys-2-crypt is "swordfish".


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

	cd sys-1-plain
	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.

    C-F2: switch to VT2 (root shell)
    C-F3: switch to VT3 (Xorg, default VT)
    C-F4: switch to VT4 (Weston, 1st instance)
    C-F5: switch to VT5 (Weston, 2nd instance)
    C-Esc: bring up the greeter. Commands there:

        Esc: return back
	Shift-R: reboot
	Shift-P: poweroff
	Shift-S: sleep (real hw only, does nothing in qemu)
	Shift-L: lock

The system boots into X/Fluxbox running on VT3.
Right-click on desktop and run urxvt.

There's another root console on ttyS0 (serial).
In qemu, press C-A-2 to access it, C-A-1 to go back.
(some qemu versions may need C-A-3 not C-A-2)

Inspect system state:

	pstree                 # processes
	logcat                 # syslog contents

Use `svctl` to query top-level supervisor:

	svctl                  # process list
	svctl stop udevmod
	svctl start udevmod
	svctl poweroff

	svctl show keymon      # properly running service
	svctl show badsrv      # failed service

Use `vtctl` to control vtmux:

	vtctl 4                # switch to VT4

Use `wictl` to scan/connect to network:

	wifi scan              # scan wifi
	wifi connect blackhole # ask passphrase and connect to a named AP

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

	ifctl                  # show networking devices
	ifctl [dev] auto-dhcp  # bring up and dhpc $dev

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.

Emulated keyboard in some qemu versions (?) sends bogus scancodes for arrow
keys. This can be verified using `inputs -r`. Does not seem to happen on real
hardware. No fix atm, and it's probably not something that should be fixed in
minibase.

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.

While the kernel is modular, the supplied configuration only includes modules
for the stuff I have at hand (Intel based laptops). Feel free to reconfigure
if necessary. Sadly enabling everything is not an option for a system that aims
to be "small" in any sense of the word.

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.