bootable system images, minibase+buildroot
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
brrootfs fix Mesa configuration for Weston Jan 29, 2018
brvendor update w-l patch for xorg Feb 2, 2018
minibase @ 4312982 bump minibase to 0.6.2 Feb 10, 2018
sys-0-boot build scripts rework Jan 18, 2018
sys-2-crypt fix module path in sys-2-crypt Feb 28, 2018
.gitignore build scripts rework Jan 18, 2018
.gitmodules minibase submodule Nov 21, 2017
README fix Mesa configuration for Weston Jan 29, 2018


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.

The images should be bootable with qemu as well as with reasonably recent
x86_64 hardware with Intel or AMD graphics.

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

To see How the system is assembled without having to mess with
Buildroot, download prebuilt.tar.xz and skip the buildroot part 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.

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
(Skip until "Update ./minibase ..." if working with prebuilt.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.

Build the system:

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

Stage resulting rootfs:

	cd brrootfs

Update ./minibase and build it:

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

Assemble plaintext image:

	cd sys-1-plain

Assemble encrypted image:

	cd sys-2-crypt

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 in respective directories:

	cd sys-1-plain

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 -a [dev]         # 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

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.