English | 中文

Build RAM-based Debian systems. Debootstrap a minimal rootfs, package it as squashfs, and boot it entirely from RAM using overlayfs.

The system runs read-only from squashfs with a writable tmpfs overlay — all changes live in RAM and disappear on reboot.

# Build a base image
sudo ./mkramsys init base.sqfs

# Open a session to customize
sudo ./mkramsys open base.sqfs
sudo ./mkramsys install vim curl openssh-server
sudo ./mkramsys driver          # auto-detect and install firmware

# Produce final squashfs and close session
sudo ./mkramsys commit system.sqfs

Boot the result with a kernel and initramfs from boot/:

linux /vmlinuz boot=ramsys ramsys.src=/dev/sda1 ramsys.dir=system.sqfs
initrd /initrd.img

• Root privileges
• debootstrap, mksquashfs (squashfs-tools), bash
• For open: unsquashfs (squashfs-tools)
• For driver: modinfo, modprobe

mkramsys [-w DIR] <command> [options]

Global option -w DIR overrides automatic session discovery with an explicit session directory.

sudo ./mkramsys init [--boot-dir DIR] [--mirror URL] [--codename NAME] [--comp-level N] <output.sqfs>

Creates a standalone Debian squashfs image via debootstrap. Installs a kernel, generates an initramfs with the ramsys boot script, extracts boot files, then purges the kernel and cleans the rootfs to minimize image size.

No session is created — this is a pure image builder.

sudo ./mkramsys open [--force] <sqfs-path>

Starts a session on an existing squashfs file. Creates a session directory (in /tmp by default, override with -w) and writes .mkramsys-session in the current directory so subsequent commands find the session automatically.

sudo ./mkramsys driver

Scans the host for required firmware:

1. Loaded kernel modules (/proc/modules) — queries firmware dependencies
2. Hardware modaliases (/sys/bus/*/devices/*/modalias) — resolves to modules, queries firmware
3. CPU vendor — selects amd64-microcode or intel-microcode

Maps detected firmware files to Debian packages via apt-file and installs them. Automatically enables the non-free-firmware repository.

sudo ./mkramsys install [-f packages.txt] [PKG...]

Installs packages through the overlay. Changes accumulate in the session upper directory.

-f FILE reads package names from a file (one per line, # comments supported).

sudo ./mkramsys shell [-c CMD] [-l] [SCRIPT [ARGS...]]

sudo ./mkramsys build [--comp-level N] <output.sqfs>

Snapshots the current overlay state as a squashfs image without running cleansys. The session remains active for further modifications.

sudo ./mkramsys commit [--comp-level N] <output.sqfs>

Runs cleansys --full inside the chroot and from the host, creates the final squashfs image, then closes the session. This is a terminal operation — the session directory and .mkramsys-session are deleted.

sudo ./mkramsys reset [--force]

Deletes the overlay upper directory, discarding all changes made since open. The source image and session are not affected. --force skips the confirmation prompt.

sudo ./mkramsys close [--force]

Deletes the session directory and .mkramsys-session marker, discarding all overlay changes. --force skips the confirmation prompt.

Image creation (init) and image modification (open/commit/close) are separate concerns:

# Create → open → modify → finalize
sudo ./mkramsys init base.sqfs
sudo ./mkramsys open base.sqfs
sudo ./mkramsys install vim
sudo ./mkramsys commit final.sqfs

# Or: snapshot without closing, keep working
sudo ./mkramsys open base.sqfs
sudo ./mkramsys install vim
sudo ./mkramsys build snapshot.sqfs    # session stays active
sudo ./mkramsys install curl
sudo ./mkramsys commit final.sqfs      # cleansys + close

Session discovery: open writes .mkramsys-session in the current directory. Subsequent commands read this file to find the session. Use -w DIR to override with an explicit path.

Session directory layout:

/tmp/mkramsys-session.XXXXXX/
├── .mkramsys        # Session marker
├── .source          # Absolute path to source squashfs
├── .lock            # flock target
├── upper/           # Overlay changes (persistent across commands)
└── .work/           # Overlay workdir

A lockfile prevents concurrent access to the same session.

The initramfs boot script (boot=ramsys) copies a squashfs file into RAM and mounts it with overlayfs as the root filesystem.

./build.sh              # produces dist/mkramsys (single file, ~42KB)
./build.sh output.sh    # custom output path

The build script bundles all sources into one self-contained script with embedded resource files. No external files needed at runtime.

GPLv3