How to Make a Bootable USB from a Linux Live Kit Build

Updated

After ./build finishes, Linux Live Kit leaves two artifacts in /tmp: an ISO image and a TAR archive. For a USB stick you want the TAR archive, not the ISO. Unpack it onto the USB device, then run bootinst.sh from the boot sub-directory — that install script is what makes the device bootable, and it works for both Linux and Windows machines.

This assumes you have already completed a build and have a USB device you can erase. The steps below cover the copy, the boot installer, and the checks worth doing before you reboot.

Prerequisites

  • A finished Linux Live Kit build, with the generated TAR archive sitting in /tmp.
  • A USB device large enough to hold the unpacked tree. The build's size depends on how aggressively you stripped unnecessary files in step 3 of the build process.
  • Root access on the machine doing the copy, since you are writing directly to a block device.
  • The kernel modules the build relies on (squashfs plus either aufs or overlayfs) must be supported by the kernel you built against — that was already a requirement at build time, and it carries over to the target hardware.

Step 1: Identify the USB device

Before writing anything, confirm which block device is your USB stick. Getting this wrong means overwriting the wrong disk.

lsblk -o NAME,SIZE,TYPE,MOUNTPOINT

Look for a removable device whose size matches your stick. Note the device node (for example /dev/sdb) — you want the whole device, not a partition like /dev/sdb1. Unmount any partition that is currently mounted:

umount /dev/sdb1

Step 2: Unpack the TAR archive onto the USB device

The TAR archive in /tmp contains the full boot tree. Extract it directly to the USB device.

tar -xpf /tmp/<your-build>.tar -C /mnt/usb

If you prefer to write to the raw device rather than a mounted filesystem, mount the USB device first, then extract into the mount point. The important part is that the archive's contents — including the boot sub-directory — land at the root of the USB device, not nested inside an extra folder.

Expected result: the USB device now contains the same directory layout as the TAR archive, with a boot directory among the entries.

Step 3: Run the boot installer

This is the step that actually makes the device bootable.

cd /mnt/usb/boot
./bootinst.sh

bootinst.sh installs the bootloader so the device can start on both Linux and Windows systems. Run it as root. When it finishes, unmount the device cleanly before removing it:

sync
umount /mnt/usb

Expected result: the USB device is bootable on a machine that supports booting from USB, and the same device also works when written to CD/DVD media, since Linux Live Kit supports both boot paths.

What the installer gives you

Feature What it means for your USB
bootinst.sh in boot/ Installs a bootloader usable on Linux and Windows
Boot from USB or CD/DVD Same build tree works for either medium
Persistent changes via DynFileFS Dynamic-size filesystem for saving changes, even on VFAT or NTFS
Load data from another directory or an ISO The LiveKit data does not have to sit at the device root

The DynFileFS point matters if you plan to save changes: it supports writing persistent changes to VFAT or NTFS, which is what most USB sticks ship with. Without it, a FAT-formatted stick would be read-only for your session data.

Common snags

  • Extracted into a subfolder. If the archive unpacks into a directory instead of the device root, the bootloader will not find its files. Check the layout after extraction.
  • Ran the installer from the wrong directory. bootinst.sh lives in the boot sub-directory. Running it from elsewhere, or copying it out, breaks the relative paths it expects.
  • Skipped unmounting before extraction. Writing to a mounted device while it is in use can leave a partial tree. Unmount first, or extract to a clean mount point.
  • Persistent net rules left in place. The build guide recommends removing udev's persistent net rules and similar distro-specific settings, because they can stop the system working correctly on different hardware. If your USB boots on one machine but not another, this is a likely cause.
  • Kernel module mismatch. If squashfs and aufs/overlayfs are not available on the target machine's kernel, the Live system will not mount its filesystem.

Verifying the result

  1. Reboot the target machine and enter its boot menu (usually a function key at power-on).
  2. Select the USB device.
  3. Confirm the Live system reaches a usable desktop or shell.
  4. If you enabled persistent changes, create a file, reboot, and check whether it survived — that confirms DynFileFS is writing correctly to the stick's filesystem.

If the device does not appear in the boot menu, re-run bootinst.sh and confirm the USB device's partition table is one the target firmware can read.