Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/damianiglesias/amnesiaOS/llms.txt

Use this file to discover all available pages before exploring further.

The initramfs is a gzip-compressed CPIO archive that the Linux kernel decompresses directly into a tmpfs at boot. Because AmnesiaOS never mounts a persistent root device, this archive is the entire running OS — everything the system does after the kernel hands off to userspace happens inside it. scripts/build-initramfs.sh automates the full assembly: downloading BusyBox, building the directory tree, creating device nodes, writing the network and init scripts, and packing the final image.

​
Running the script

The script must be run as root because creating device nodes with mknod requires elevated privileges: 
sudo bash scripts/build-initramfs.sh
When the script completes it prints the output path and compressed size. The finished archive is written to: 
/boot/initramfs-6.16.1.img
build-initramfs.sh must be run as root — the mknod calls for /dev/console, /dev/null, and /dev/tty will silently fail without the required permissions, producing a non-bootable image. Running the script on a non-Linux host (e.g. macOS or WSL without a real Linux kernel) is not supported.

​
What the script does

1

Create directory structure

The script creates the full FHS-compatible skeleton that BusyBox and the init system expect to find at runtime:
mkdir -pv /initramfs/{bin,dev,etc,lib,lib64,proc,sys,tmp,mnt/root,root,run,sbin,usr/{bin,sbin,lib,share/udhcpc}}
2

Download BusyBox 1.35.0

BusyBox provides every userspace utility the initramfs needs in a single statically-linked binary. The script downloads the pre-built musl-linked x86_64 binary and skips the download if the file is already present:
wget -O /initramfs/bin/busybox \
    https://busybox.net/downloads/binaries/1.35.0-x86_64-linux-musl/busybox
chmod +x /initramfs/bin/busybox
3

Create utility symlinks

BusyBox uses argv[0] to decide which applet to run, so the script creates a symlink for each utility pointing back to the busybox binary:
sh, mount, umount, cp, ls, cat, mkdir, rm, mv, pwd, echo, grep,
sed, awk, find, chmod, chown, ln, ps, kill, top, df, free, uname,
date, ip, ifconfig, ping, tar, gzip, gunzip, vi, more, less,
head, tail, sleep, hostname, dmesg, su, login, wget, basename, udhcpc
All symlinks are created inside /initramfs/bin/ with ln -sfv busybox /initramfs/bin/<cmd>.
4

Create device nodes

Three device nodes are created with mknod. These must exist before the kernel tries to open them during early boot:
NodeTypeMajorMinorMode
/dev/consolechar51622
/dev/nullchar13666
/dev/ttychar50666
5

Write DHCP script

The udhcpc DHCP client calls a helper script to apply the lease it receives from the network. The script is installed at /initramfs/usr/share/udhcpc/default.script:
#!/bin/sh
case "$1" in
    deconfig)
        ip addr flush dev "$interface"
        ;;
    bound|renew)
        ip addr add "$ip"/"${mask:-${subnet:-24}}" dev "$interface"
        if [ -n "$router" ]; then
            ip route add default via "$router" dev "$interface"
        fi
        if [ -n "$dns" ]; then
            > /etc/resolv.conf
            for d in $dns; do
                echo "nameserver $d" >> /etc/resolv.conf
            done
        fi
        ;;
esac
exit 0
The deconfig case flushes the interface address when releasing a lease. The bound/renew case applies the assigned IP, default route, and DNS resolvers.
6

Write /init

/init is the first userspace process the kernel executes after decompressing the initramfs. The script writes the following to /initramfs/init and marks it executable:
#!/bin/sh
mount -t proc proc /proc
mount -t sysfs sysfs /sys
mount -t devtmpfs devtmpfs /dev 2>/dev/null

echo "AmnesiaOS - RAM boot OK"
echo "Configuring network..."

ip link set lo up 2>/dev/null

for iface in /sys/class/net/*; do
    name=${iface##*/}
    if [ "$name" != "lo" ]; then
        ip link set "$name" up 2>/dev/null
        udhcpc -i "$name" -n -q -s /usr/share/udhcpc/default.script 2>/dev/null \
            && echo "Network configured on $name"
    fi
done

exec /bin/sh
The init script mounts the three essential pseudo-filesystems (proc, sysfs, devtmpfs), brings up the loopback interface, iterates over every non-loopback network interface to request a DHCP lease, then drops into an interactive BusyBox shell.
7

Pack the archive

The completed initramfs tree is packed into a gzip-compressed CPIO archive — the exact format the Linux kernel’s initramfs loader expects:
cd /initramfs
find . | cpio -o -H newc | gzip -9 > /boot/initramfs-6.16.1.img
The -H newc flag selects the “new ASCII” CPIO format required by the kernel. gzip -9 applies maximum compression to keep the archive as small as possible since it must be loaded entirely into RAM.

Build docs developers (and LLMs) love

Get started for freeTalk to us