TinyBox Linux

TinyBox Linux is a minimal, educational Linux distribution built from scratch. It demonstrates how to build a Linux system using the Linux Kernel and ToyBox for the userspace. The entire distribution fits in a few megabytes.

Features

• Extremely Small: ~3 MB (Kernel + Initramfs).
• Educational: Built from source to understand the Linux boot process.
• Networking: Includes networking support (DHCP, DNS).
• Custom Kernel: Uses a highly optimized tinyconfig kernel.
• ToyBox: Uses minimal utilities for the shell and user environment.

Current Versions & Sizes

• Linux Kernel: 6.17.91 (bzImage: 2.65 MB)
• ToyBox: 0.8.13 (initramfs.cpio.gz: 500 KB)
• ISO Image: image.iso: 3.7 MB

Quick Start

Prerequisites

• QEMU: To run the distribution.
• Docker (Optional): For building in a clean environment.
• Linux Build Tools: build-essential, git, curl, cpio, bison, flex, bc, libelf-dev, libssl-dev.

QEMU Setup for Windows

• QEMU Prebuilt Zip [38.5 MB] - concise version of the installer [172 MB]

Exe files can be downloaded from here: https://qemu.weilnetz.de/w64/

To recreate the zip using a downloaded installer:

./extract_qemu.sh qemu-w64-setup-20250826.exe

Running Pre-built Images

You can run the pre-built images located in bootfiles/ or cd-root/ using QEMU.

On Windows:

# Run from ISO
.\qemu-system-x86_64.exe -cdrom image.iso

# Run from Kernel + Initrd
.\qemu-system-x86_64.exe -kernel bzImage -initrd initramfs.cpio.gz

Building from Scratch

The build process is divided into three main parts: the Kernel, the Userspace (Root Filesystem), and the Bootable ISO.

1. Build the Kernel (bzImage)

The kernel is the core of the OS. We use a minimal configuration.

• Script: setup.sh (for defconfig) or follow tinymenuconfig.md (for tinyconfig).
• Process:
  1. Clone the Linux kernel source.
  2. Configure it (make tinyconfig then make menuconfig).
  3. Enable necessary features: 64-bit, TTY, Printk, ELF support, Networking (TCP/IP), PCI, E1000 driver.
  4. Compile: make -j $(nproc).
  5. Result: arch/x86/boot/bzImage.

Update on aarch64

git clone -b linux-6.99.y --depth 1 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git
wget https://raw.githubusercontent.com/EN10/TinyBoxLinux/refs/heads/main/bootfiles/.config
time yes "" | make ARCH=x86_64 CROSS_COMPILE=x86_64-linux-gnu- -j 4

2. Get the Userspace (ToyBox)

The userspace contains the shell (/bin/sh) and utilities (ls, cp, ip, etc.). We use ToyBox.

• Guide: toybox.md
• Process:
  1. Download the latest pre-built root filesystem from landley.net.
  2. Extract initramfs.cpio.gz.

3. Create Bootable ISO

To boot from a CD/DVD or USB, we wrap the Kernel and Initramfs into an ISO using Syslinux.

• Guide: make-isoimage.md
• Process:
  1. Install syslinux and isolinux.
  2. Use the kernel's make isoimage target or manually create the ISO structure with isolinux.bin and isolinux.cfg.
  3. Note: Ensure you point to the correct initramfs (initramfs.cpio.gz).

Directory Structure

• bootfiles/: Contains the compiled kernel (bzImage) and initramfs (initramfs.cpio.gz). Also contains QEMU helper scripts.
• cd-root/: Contains the ISO image and ISOLINUX configuration.
• lib/: Helper scripts for finding dependencies and installing extra packages (like elinks, wget, strace).
• setup.sh: Script to setup the environment and build a basic system.
• networking.sh: Script to build BusyBox with networking support.
• tinymenuconfig.md: Documentation for the minimal kernel configuration.
• toybox.md: Documentation for ToyBox.
• CROSS_COMPILE.sh: Helper for cross-compiling.

References & Credits

• Making Simple Linux Distro from Scratch - setup.sh
• Building a tiny Linux kernel - menuconfig
• Networking from Gentoo Wiki - networking.sh
• Find Library Dependencies
• Make a Bootable CD With ISOLINUX - make isoimage
• BusyBox, ToyBox